En esta página, se muestra cómo enumerar los objetos almacenados en tus buckets de Cloud Storage, que están ordenados por nombre y de forma lexicográfica en la lista.
Antes de comenzar
Para obtener los permisos que necesitas para enumerar objetos, pídele a tu administrador que te otorgue el rol de IAM de Visualizador de objetos de almacenamiento (roles/storage.objectViewer) para el bucket que contiene los objetos que deseas enumerar. Si deseas enumerar objetos dentro de carpetas administradas, puedes otorgar roles/storage.objectViewer en la carpeta administrada que contiene los objetos que deseas ver en lugar del bucket.
Si planeas usar la Cloud de Confiance consola para realizar las tareas de esta página,
pídele a tu administrador que te otorgue el rol básico de Visualizador (roles/viewer) además del rol de Visualizador de objetos de almacenamiento (roles/storage.objectViewer).
Estos roles contienen los permisos necesarios para enumerar objetos. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:
Permisos necesarios
storage.objects.liststorage.buckets.list- Este permiso solo es necesario si deseas usar la Cloud de Confiance consola para realizar las tareas en esta página.
También puedes obtener estos permisos con otros roles predefinidos o roles personalizados.
Para obtener más información sobre cómo otorgar roles a los buckets, consulta Configura y administra políticas de IAM en buckets.
Enumerar los objetos de un bucket
Console
- En la consola de Cloud de Confiance , ve a la página Buckets de Cloud Storage.
En la lista de buckets, haz clic en el nombre del bucket que posee el contenido que deseas ver.
Línea de comandos
Usa el comando gcloud storage ls:
gcloud storage ls gs://BUCKET_NAME
Aquí:
BUCKET_NAMEes el nombre del bucket que contiene los objetos que deseas enumerar. Por ejemplo,my-bucket
Bibliotecas cliente
C++
Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C++.
Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
En la siguiente muestra, se enumeran todos los objetos en un bucket:
En el siguiente ejemplo, se enumeran los objetos con un prefijo dado:
C#
Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage C#.
Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
En la siguiente muestra, se enumeran todos los objetos en un bucket:
En el siguiente ejemplo, se enumeran los objetos con un prefijo dado:
Go
Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Go.
Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
En la siguiente muestra, se enumeran todos los objetos en un bucket:
En el siguiente ejemplo, se enumeran los objetos con un prefijo dado:
Java
Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Java.
Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
En la siguiente muestra, se enumeran todos los objetos en un bucket:
En el siguiente ejemplo, se enumeran los objetos con un prefijo dado:
Node.js
Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Node.js.
Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
En la siguiente muestra, se enumeran todos los objetos en un bucket:
En el siguiente ejemplo, se enumeran los objetos con un prefijo dado:
PHP
Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage PHP.
Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
En la siguiente muestra, se enumeran todos los objetos en un bucket:
En el siguiente ejemplo, se enumeran los objetos con un prefijo dado:
Python
Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Python.
Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
En la siguiente muestra, se enumeran todos los objetos en un bucket:
En el siguiente ejemplo, se enumeran los objetos con un prefijo dado:
Ruby
Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Ruby.
Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
En la siguiente muestra, se enumeran todos los objetos en un bucket:
En el siguiente ejemplo, se enumeran los objetos con un prefijo dado:
API de REST
API de JSON
Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado
Authorization.Usa
cURLpara llamar a la API de JSON con una solicitud para enumerar objetos:curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.s3nsapis.fr/storage/v1/b/BUCKET_NAME/o"
En el ejemplo anterior,
BUCKET_NAMEes el nombre del bucket cuyos objetos deseas incluir en una lista. Por ejemplo,my-bucket
API de XML
Tener la gcloud CLI instalada e inicializada, lo que te permite generar un token de acceso para el encabezado
Authorization.Usa
cURLpara llamar a la API de XML con una solicitud de bucketGET:curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.s3nsapis.fr/BUCKET_NAME?list-type=2"
En el ejemplo anterior,
BUCKET_NAMEes el nombre del bucket cuyos objetos deseas incluir en una lista. Por ejemplo,my-bucket.Puedes usar un parámetro de string de consulta
prefix=PREFIXpara limitar los resultados a los objetos que tienen el prefijo especificado.
Enumera los objetos de una carpeta
Console
- En la consola de Cloud de Confiance , ve a la página Buckets de Cloud Storage.
En la lista de buckets, haz clic en el nombre del bucket que contiene la carpeta.
En la pestaña Objetos de la página Detalles del bucket, haz clic en el nombre de la carpeta cuyo contenido deseas ver.
Línea de comandos
Usa el comando gcloud storage ls para enumerar los objetos de una carpeta:
gcloud storage ls gs://BUCKET_NAME/FOLDER_NAME
Aquí:
BUCKET_NAMEes el nombre del bucket que contiene la carpeta. Por ejemplo,my-bucketFOLDER_NAMEes el nombre de la carpeta que contiene los objetos que deseas enumerar. Por ejemplo,my-folder
API de REST
API de JSON
Para enumerar los objetos de una carpeta, usa una solicitud de enumeración de objetos con los parámetros prefix y delimiter. Cuando se establece el parámetro prefix, la operación de lista se limita a devolver solo los objetos y las carpetas que se encuentran debajo del prefijo. Cuando se establece el parámetro delimiter, la lista prefixes[] de la respuesta se completa con los nombres de las carpetas que se encuentran bajo el prefijo especificado.
Por ejemplo:
Para enumerar todos los objetos de la carpeta
image/dentro del bucketmy-bucket, usa la siguiente URL:"https://storage.s3nsapis.fr/storage/v1/b/my-bucket/o?prefix=image&delimiter=/".Esto podría devolver los objetos
my-bucket/image/cat.jpegymy-bucket/image/dog.jpeg.Para incluir objetos en subcarpetas dentro de
image/, quita el parámetrodelimiter:"https://storage.s3nsapis.fr/storage/v1/b/my-bucket/o?prefix=image".Esto podría devolver los objetos
my-bucket/image/cat.jpeg,my-bucket/image/dog.jpegymy-bucket/image/dog/shiba.jpeg.
Para usar comodines en tu solicitud de enumeración de objetos y hacer coincidir objetos por expresión glob, usa el parámetro matchGlob. Por ejemplo, matchGlob=**.jpeg coincide con todos los objetos que terminan en .jpeg. Cuando usas matchGlob, debes establecer delimiter en /.
Por ejemplo, usa la siguiente URL para hacer coincidir todos los objetos de la carpeta image que terminan en .jpeg:
"https://storage.s3nsapis.fr/storage/v1/b/my-bucket/o?prefix=image&delimiter=/&matchGlob=**.jpeg"
Para obtener más detalles sobre el uso de parámetros para filtrar objetos, consulta la documentación de referencia de la API de JSON de la lista de objetos.
Caso de uso
Usar prefix para enumerar el contenido de una carpeta puede ser útil cuando solo tienes permiso para enumerar objetos en la carpeta, pero no en todo el bucket. Por ejemplo, supongamos que tienes el rol de IAM de visualizador de objetos de almacenamiento (roles/storage.objectViewer) para la carpeta administrada my-bucket/my-managed-folder-a/, pero no para la carpeta administrada my-bucket/my-managed-folder-b/. Para mostrar solo los objetos en my-managed-folder-a, puedes especificar prefix=my-managed-folder-a/.
Filtra objetos
Cuando enumeres objetos, puedes usar prefijos o sufijos en tu solicitud de lista para filtrar objetos por nombre.
Console
Consulta Filtrado y ordenamiento para obtener información sobre cómo filtrar y ordenar objetos en buckets o carpetas.
Línea de comandos
Puedes usar comodines en tu comando gcloud storage ls para filtrar objetos por prefijo o sufijo. Por ejemplo, el siguiente comando solo enumera los objetos del bucket my-bucket cuyo nombre comienza con image y termina con .png:
gcloud storage ls gs://my-bucket/image*.png
Si la solicitud se realiza correctamente, la respuesta se verá como la siguiente:
gs://my-bucket/image.png gs://my-bucket/image-dog.png gs://my-bucket/image-cat.png ...
Puedes usar comodines de doble asterisco para que coincidan cero o más niveles de carpetas en una ruta. Por ejemplo, el siguiente comando solo enumera los objetos cuyo nombre termina en .jpeg en cualquier carpeta o subcarpeta dentro del bucket my-bucket:
gcloud storage ls gs://my-bucket/**/*.jpeg
Si la solicitud se realiza correctamente, la respuesta se verá como la siguiente:
gs://my-bucket/puppy.jpeg gs://my-bucket/pug.jpeg gs://my-bucket/pets/dog.jpeg ...
API de REST
Consulta cómo enumerar objetos en carpetas para obtener información sobre cómo filtrar objetos por carpeta o prefijo de nombre de objeto.
Cómo filtrar objetos por contextos
Puedes usar un filtro para mostrar solo los objetos que tienen los contextos especificados (vista previa) en la respuesta de la lista.
Línea de comandos
Usa el comando gcloud alpha storage objects list:
gcloud alpha storage objects list gs://BUCKET_NAME --metadata-filter='contexts."KEY"="VALUE"'
Aquí:
BUCKET_NAMEes el nombre del bucket que contiene el objeto según el cual deseas filtrar el contexto. Por ejemplo,my-bucketKEYes la clave de contexto adjunta al objeto.VALUEes el valor asociado con la clave de contexto.
Si se realiza de forma correcta, la respuesta se verá como el ejemplo siguiente:
---
bucket: my-bucket
contexts:
Department:
createTime: '2023-01-01T00:00:00.000000+00:00'
type: CUSTOM
updateTime: '2023-01-01T00:00:00.000000+00:00'
value: HR
DataClassification:
createTime: '2023-01-01T00:00:00.000000+00:00'
type: CUSTOM
updateTime: '2023-01-01T00:00:00.000000+00:00'
value: Confidential
name: employees.txt
...
Bibliotecas cliente
Java
Si deseas obtener más información, consulta la documentación de referencia de la API de Cloud Storage Java.
Para autenticarte en Cloud Storage, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.
Antes de ejecutar muestras de código, configura la variable de entorno GOOGLE_CLOUD_UNIVERSE_DOMAIN como s3nsapis.fr.
API de REST
API de JSON
La solicitud Object: list muestra un ejemplo de cómo usar el parámetro de consulta filter:
curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.s3nsapis.fr/storage/v1/b/BUCKET_NAME/o/?filter=contexts.%22KEY%22%3D%22VALUE%22"
Aquí:
BUCKET_NAMEes el nombre del bucket que contiene el objeto según el cual deseas filtrar el contexto. Por ejemplo,my-bucket.KEYes la clave de contexto adjunta al objeto.VALUEes el valor asociado con la clave de contexto.
Sintaxis
Cloud Storage admite la siguiente sintaxis para el filtro.
| Sintaxis | Descripción |
|---|---|
contexts."KEY":* |
Coincide con cualquier objeto que tenga un contexto con la clave especificada adjunta. |
contexts."KEY"="VALUE" |
Coincide con cualquier objeto que tenga un contexto con la clave y el valor especificados adjuntos. |
|
O
|
Coincide con cualquier objeto que no tenga un contexto con la clave especificada adjunta. |
|
O
|
Coincide con cualquier objeto que no tenga un contexto con la clave y el valor especificados adjuntos. |
Consideraciones de rendimiento al enumerar objetos
La estructura subyacente de los buckets con el espacio de nombres jerárquico habilitado influye en el rendimiento de la operación de enumeración de objetos, en comparación con los buckets con espacio de nombres plano. Para obtener más información, consulta Optimiza el rendimiento en buckets con el espacio de nombres jerárquico habilitado.
¿Qué sigue?
- Descarga un objeto de tu bucket .
- Mira y edita metadatos de objetos.
- Borra objetos de tu depósito.
- Obtén más información sobre cómo paginar resultados.