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 planeas usar la consola de Google Cloud 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 consola de Google Cloud 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
Completa los siguientes pasos para enumerar los objetos en 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.
Opcional: Usa filtrado y orden para limitar y organizar los resultados en la lista.
Línea de comandos
Usa el comando gcloud storage ls
con la marca --recursive
:
gcloud storage ls --recursive gs://BUCKET_NAME/**
Aquí:
BUCKET_NAME
es el nombre del bucket cuyos objetos deseas incluir en una lista. Por ejemplo,my-bucket
.
La respuesta se ve como el siguiente ejemplo:
gs://my-bucket/cats.jpeg gs://my-bucket/dogs.jpeg gs://my-bucket/thesis.txt ...
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
.Puedes usar el parámetro de consulta
includeFoldersAsPrefixes=True
para mostrar carpetas administradas como parte de los resultados de la lista. Cuando usas el parámetroincludeFoldersAsPrefixes
, el parámetrodelimiter
debe configurarse como/
.
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.
Filtra objetos
Console
Para filtrar objetos por su prefijo de nombre con la consola de Google Cloud, usa el campo Filtrar objetos y carpetas en la página Detalles del bucket.
Consulta filtrado y orden para ver las opciones de filtrado adicionales disponibles con la consola de Google Cloud.
Línea de comandos
Cuando se enumeran objetos mediante Google Cloud CLI, puedes usar comodines para filtrar objetos que comienzan con un prefijo especificado o terminan con un sufijo especificado. Por ejemplo, el siguiente comando coincide con los objetos que comienzan con image
y terminan en .png
:
gcloud storage ls gs://my-bucket/image*.png
Para obtener más información sobre los filtros mediante Google Cloud CLI, consulta la documentación de gcloud storage ls
.
API de REST
API de JSON
Cuando haces una lista de objetos con la API de JSON de Cloud Storage, puedes usar los parámetros de cadena de consulta prefix
o matchGlob
para filtrar tus resultados. Para obtener detalles sobre el uso de estos parámetros de cadena de consulta, revisa la documentación de referencia de la API de JSON de la lista de objetos.
Filtra por prefijo
Puedes usar el parámetro de cadena de consulta o prefix=PREFIX
para limitar los resultados a los objetos o las carpetas administradas que tienen el prefijo especificado. Por ejemplo, para enumerar todos los objetos en el bucket my-bucket
con el prefijo folder/subfolder/
, realiza una solicitud de listado de objetos con la URL "https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=folder/subfolder/"
.
Usar prefix
para enumerar los contenidos de una carpeta administrada es útil
cuando solo tienes el permiso para enumerar los objetos de la carpeta
administrada, pero no el bucket completo. 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/
.
Cuando limites los resultados a una carpeta administrada y los objetos que contiene, debes finalizar PREFIX
con /
(por ejemplo, prefix=my-managed-folder/
). De lo contrario, los resultados también pueden incluir objetos que estén junto a la carpeta administrada. En este ejemplo, tienes un bucket que contiene los siguientes objetos:
my-bucket/abc.txt
my-bucket/abc/object.txt
Si especificas prefix=abc/
, se pueden mostrar los objetos
my-bucket/abc/object.txt
, mientras que si especificas prefix=abc
, se pueden mostrar
my-bucket/abc.txt
y my-bucket/abc/object.txt
.
Filtra por expresión glob
Puedes usar el parámetro de cadena de consulta matchGlob=GLOB_PATTERN
para filtrar los resultados y ver solo los objetos que coinciden con una expresión glob específica. Por ejemplo, se puede usar matchGlob=**.jpeg
para hacer coincidir todos los objetos que terminan en .jpeg
.
Las solicitudes que usan el parámetro matchGlob
fallan si también incluyen un parámetro delimiter
configurado como un valor distinto de /
.
Consideraciones de rendimiento cuando se genera una lista de objetos
La estructura subyacente de los buckets con el espacio de nombres jerárquico habilitado puede influir en el rendimiento de la operación de enumeración de objetos, en comparación con los buckets de espacio de nombres plano. Para obtener más información sobre cómo optimizar el rendimiento cuando se enumeran objetos en buckets con espacio de nombres jerárquico habilitado, consulta Cómo enumerar objetos.
¿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.