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 Google Cloud 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.list
storage.buckets.list
- Este permiso solo es necesario si deseas usar la Google Cloud consola para realizar la tarea 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 para los buckets, consulta Usa IAM con buckets.
Enumerar los objetos de un bucket
Console
- En la consola de Google Cloud , 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_NAME
es 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.
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.
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.
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.
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.
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.
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.
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.
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
cURL
para 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.googleapis.com/storage/v1/b/BUCKET_NAME/o"
En el ejemplo anterior,
BUCKET_NAME
es 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
cURL
para llamar a la API de XML con una solicitud de bucketGET
:curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/BUCKET_NAME?list-type=2"
En el ejemplo anterior,
BUCKET_NAME
es 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=PREFIX
para limitar los resultados a los objetos que tienen el prefijo especificado.
Enumera los objetos de una carpeta
Console
- En la consola de Google Cloud , 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_NAME
es el nombre del bucket que contiene la carpeta. Por ejemplo,my-bucket
FOLDER_NAME
es 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 objetos y carpetas con el 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.googleapis.com/storage/v1/b/my-bucket/o?prefix=image&delimiter=/"
.Esto podría devolver los objetos
my-bucket/image/cat.jpeg
ymy-bucket/image/dog.jpeg
.Para incluir objetos en subcarpetas dentro de
image/
, quita el parámetrodelimiter
:"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=image"
.Esto podría devolver los objetos
my-bucket/image/cat.jpeg
,my-bucket/image/dog.jpeg
ymy-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.googleapis.com/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.
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 de espacio de nombres planos. 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.