Nesta página, veja como listar os objetos armazenados nos buckets do Cloud Storage, que são ordenados na lista de maneira lexicográfica pelo nome.
Antes de começar
Para receber as permissões necessárias para listar objetos, peça ao administrador
que conceda a você o papel do IAM de Leitor de objetos do Storage (roles/storage.objectViewer
)
para o bucket que contém os objetos que você quer
listar.
Se você quiser retornar Access Control Lists de objetos como parte da solicitação ou usar o console do Google Cloud para executar as tarefas desta página, você precisará de papéis alternativos:
Se você quiser retornar ACLs de objetos como parte de sua solicitação, peça ao administrador para conceder a você o papel Administrador de objetos do Storage (
roles/storage.objectAdmin
) em vez do papel de Leitor de objetos do Storage (roles/storage.objectViewer
).Se você planeja usar o console do Google Cloud para executar as tarefas nesta página, peça ao administrador para conceder a você o papel Administrador do Storage (
roles/storage.admin
) em vez do Leitor de objetos do Storage (roles/storage.objectViewer
).Outra possibilidade é pedir ao administrador para conceder a você o papel básico de Leitor (
roles/viewer
), além do papel de Leitor de objetos do Storage (roles/storage.objectViewer
).
Esses papéis contêm as permissões necessárias para listar objetos. Para ver as permissões exatas necessárias, expanda a seção Permissões necessárias:
Permissões necessárias
storage.objects.list
storage.objects.getIamPolicy
- Essa permissão só será necessária se você quiser retornar Access Control Lists de objetos
storage.buckets.list
- Essa permissão só será necessária se você quiser usar o console do Google Cloud para executar as tarefas desta página.
Também é possível conseguir essas permissões com outros papéis predefinidos ou personalizados.
Para informações sobre como conceder papéis para buckets, consulte Usar o IAM com buckets.
Listar os objetos em um bucket
Siga estas etapas para listar os objetos em um bucket:
Console
- No Console do Google Cloud, acesse a página Buckets do Cloud Storage.
Na lista de buckets, clique no nome do bucket cujo conteúdo você quer visualizar.
Opcional: use a filtragem e a classificação para limitar e organizar os resultados na sua lista.
Linha de comando
Use o comando gcloud storage ls
com a flag
--recursive
:
gcloud storage ls --recursive gs://BUCKET_NAME/**
Em que:
BUCKET_NAME
é o nome do bucket cujos objetos você quer listar. Por exemplo,my-bucket
.
A resposta terá esta aparência:
gs://my-bucket/cats.jpeg gs://my-bucket/dogs.jpeg gs://my-bucket/thesis.txt ...
Bibliotecas de cliente
C++
Para mais informações, consulte a documentação de referência da API Cloud Storage C++.
Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
A amostra a seguir lista todos os objetos de um bucket:
A amostra a seguir lista os objetos com um prefixo determinado:
C#
Para mais informações, consulte a documentação de referência da API Cloud Storage C#.
Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
A amostra a seguir lista todos os objetos de um bucket:
A amostra a seguir lista os objetos com um prefixo determinado:
Go
Para mais informações, consulte a documentação de referência da API Cloud Storage Go.
Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
A amostra a seguir lista todos os objetos de um bucket:
A amostra a seguir lista os objetos com um prefixo determinado:
Java
Para mais informações, consulte a documentação de referência da API Cloud Storage Java.
Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
A amostra a seguir lista todos os objetos de um bucket:
A amostra a seguir lista os objetos com um prefixo determinado:
Node.js
Para mais informações, consulte a documentação de referência da API Cloud Storage Node.js.
Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
A amostra a seguir lista todos os objetos de um bucket:
A amostra a seguir lista os objetos com um prefixo determinado:
PHP
Para mais informações, consulte a documentação de referência da API Cloud Storage PHP.
Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
A amostra a seguir lista todos os objetos de um bucket:
A amostra a seguir lista os objetos com um prefixo determinado:
Python
Para mais informações, consulte a documentação de referência da API Cloud Storage Python.
Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
A amostra a seguir lista todos os objetos de um bucket:
A amostra a seguir lista os objetos com um prefixo determinado:
Ruby
Para mais informações, consulte a documentação de referência da API Cloud Storage Ruby.
Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
A amostra a seguir lista todos os objetos de um bucket:
A amostra a seguir lista os objetos com um prefixo determinado:
APIs REST
API JSON
Ter a gcloud CLI instalada e inicializadapara gerar um token de acesso para o cabeçalho
Authorization
.Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho
Authorization
.Use
cURL
para chamar a API JSON com uma solicitação para listar objetos:curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o"
Em que
BUCKET_NAME
é o nome do bucket com os objetos que você quer listar. Por exemplo,my-bucket
.Use o parâmetro de consulta
includeFoldersAsPrefixes=True
para retornar pastas gerenciadas como parte dos resultados da lista. Ao usar o parâmetroincludeFoldersAsPrefixes
, o parâmetrodelimiter
precisa ser definido como/
.Para retornar ACLs de objeto, anexe o parâmetro de consulta
projection
com o valorfull
à sua solicitação. As ACLs serão desativadas e não poderão ser retornadas se o acesso uniforme no nível do bucket estiver ativado no bucket.
API XML
Ter a gcloud CLI instalada e inicializadapara gerar um token de acesso para o cabeçalho
Authorization
.Como alternativa, é possível criar um token de acesso usando o OAuth 2.0 Playground e incluí-lo no cabeçalho
Authorization
.Use
cURL
para chamar a API XML com uma solicitação do bucketGET
.curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://storage.googleapis.com/BUCKET_NAME?list-type=2"
Em que
BUCKET_NAME
é o nome do bucket com os objetos que você quer listar. Por exemplo,my-bucket
.É possível usar um parâmetro de string de consulta
prefix=PREFIX
para limitar os resultados a objetos que tenham o prefixo especificado.
Como filtrar objetos
Console
Para filtrar objetos pelo prefixo de nome usando o Console do Google Cloud, use o campo Filtrar objetos e pastas na página Detalhes do bucket.
Consulte Como filtrar e classificar para conferir outras opções de filtragem disponíveis usando o console do Google Cloud.
Linha de comando
Ao listar objetos usando a CLI do Google Cloud, é possível usar caracteres curinga para filtrar objetos que começam com um prefixo especificado ou terminam com um sufixo especificado. Por exemplo, o comando a seguir corresponde
a objetos que começam com image
e terminam em .png
:
gcloud storage ls gs://my-bucket/image*.png
Para mais informações sobre filtragem usando a CLI do Google Cloud, consulte a documentação do gcloud storage ls
.
APIs REST
API JSON
Ao listar objetos usando a API Cloud Storage JSON, use os parâmetros de string de consulta prefix
ou matchGlob
para filtrar os resultados. Para saber como usar esses parâmetros de string de consulta, confira a documentação de referência da API JSON com relação à lista de objetos.
Como fazer a filtragem por prefixo
Use prefix=PREFIX
ou o parâmetro de string de consulta para limitar os resultados a objetos ou pastas gerenciadas que tenham o prefixo especificado. Por exemplo, para listar todos os objetos no bucket my-bucket
com o prefixo folder/subfolder/
, faça uma solicitação de listagem de objetos usando o URL "https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=folder/subfolder/"
:
O uso de prefix
para listar o conteúdo de uma pasta gerenciada é útil quando
você só tem permissão para listar objetos nela,
não no bucket inteiro. Por exemplo, digamos que você tenha o papel do IAM de Leitor de objetos do Storage (roles/storage.objectViewer
) para a pasta gerenciada my-bucket/my-managed-folder-a/
, mas não para a pasta gerenciada my-bucket/my-managed-folder-b/
. Para retornar apenas os
objetos em my-managed-folder-a
, especifique
prefix=my-managed-folder-a/
.
Ao limitar os resultados a uma pasta gerenciada e aos objetos nela, você precisa terminar PREFIX
com /
(por exemplo, prefix=my-managed-folder/
). Caso contrário, os resultados também podem incluir objetos adjacentes à pasta gerenciada. Neste exemplo, você tem um bucket que contém os seguintes objetos:
my-bucket/abc.txt
my-bucket/abc/object.txt
Especificar prefix=abc/
pode retornar os objetos
my-bucket/abc/object.txt
, enquanto especificar prefix=abc
pode retornar
my-bucket/abc.txt
e my-bucket/abc/object.txt
.
Como fazer a filtragem por expressão glob
Use o parâmetro de string de consulta matchGlob=GLOB_PATTERN
a fim de filtrar os resultados apenas para os objetos que correspondem a uma expressão glob específica. Por exemplo, matchGlob=**.jpeg
pode
ser usado para corresponder a todos os objetos que terminam em .jpeg
.
As solicitações que usam o parâmetro matchGlob
falharão se também incluírem um parâmetro delimiter
definido com um valor diferente de /
.
A seguir
- Faça o download de um objeto do seu bucket.
- Visualize e edite metadados de objetos.
- Exclua objetos do bucket.
- Saiba como paginar resultados.