Listar chaves de objeto programaticamente - Amazon Simple Storage Service

Listar chaves de objeto programaticamente

No Amazon S3, as chaves podem ser listadas por prefixo. Você pode escolher um prefixo comum para os nomes das chaves relacionadas e marcar essas chaves com um caractere especial que delimite a hierarquia. Em seguida, você pode usar a operação de lista para selecionar e procurar chaves hierarquicamente. Isso é semelhante à forma como arquivos são armazenados em diretórios em um sistema de arquivos.

O Amazon S3 expõe uma operação de lista que permite a enumeração das chaves contidas em um bucket. As chaves são selecionadas para a listagem pelo bucket e pelo prefixo. Por exemplo, considere um bucket chamado “dictionary” que contém uma chave para cada palavra inglesa. Você pode fazer uma chamada para listar todas as chaves no bucket iniciadas com a letra “q”. Os resultados da lista são obtidos sempre em ordem binária UTF-8.

As operações de lista SOAP e REST retornam um documento XML que contém nomes de chaves correspondentes e informações sobre o objeto identificado em cada chave.

nota

O suporte a SOAP via HTTP está obsoleto, mas o SOAP continua disponível via HTTPS. Os novos recursos do Amazon S3 não são compatíveis com SOAP. Em vez de SOAP, recomendamos usar a API REST ou os AWS SDKs.

Grupos de chaves que compartilham um prefixo terminado por um delimitador especial podem ser rolados para acima pelo prefixo comum para fins de listagem. Isso permite que aplicativos organizem e naveguem por suas chaves hierarquicamente, de maneira muito similar a como você organizaria seus arquivos em diretórios em um sistema de arquivos.

Por exemplo, para estender o bucket de dicionário para conter mais do que apenas palavras inglesas, você poderia formar chaves prefixando cada palavra com seu idioma e um delimitador, tal como "French/logical". Usando esse esquema de nomeação e o recurso hierárquico de listagem, você poderia recuperar uma lista somente de palavras francesas. Você também poderia pesquisar a parte superior da lista de idiomas sem ter que iterar com todas as chaves de iteração lexicográficas. Para obter mais informações sobre esse aspecto de listagem, consulte Organizar objetos usando prefixos.

API REST

Se a sua aplicação exigir, você pode enviar solicitações REST diretamente. Você pode enviar uma solicitação GET para retornar alguns ou todos os objetos em um bucket ou pode usar critérios de seleção para obter um subconjunto de objetos em um bucket. Para obter mais informações, consulte GET Bucket (listar objetos) versão 2 na Referência da API do Amazon Simple Storage Service.

Implementação eficiente de lista

A performance da lista não é substancialmente afetada pelo número total de chaves no bucket. Também não é afetada pela presença ou ausência dos argumentos prefix, marker, maxkeys ou delimiter.

Iterar em resultados de várias páginas

Como os buckets podem conter um número praticamente ilimitado de chaves, os resultados completos de uma consulta de lista podem ser muito extensos. Para gerenciar grandes conjuntos de resultados, a API do Amazon S3 é compatível com a paginação para separá-los em várias respostas. Cada resposta de chaves de lista retorna uma página com até 1.000 chaves com um indicador apontando se a resposta está truncada. Você envia uma série de solicitações de chaves de lista até receber todas elas. AWS As bibliotecas wrapper do SDK fornecem a mesma paginação.

Exemplos

Os exemplos de código a seguir mostram como usar o ListObjects.

CLI
AWS CLI

O seguinte exemplo usa o comando list-objects para exibir os nomes de todos os objetos presentes no bucket especificado:

aws s3api list-objects --bucket text-content --query 'Contents[].{Key: Key, Size: Size}'

O exemplo usa o argumento --query para filtrar a saída de list-objects até encontrar o valor e o tamanho da chave de cada objeto

Para obter mais informações sobre objetos, consulte Working with Amazon S3 Buckets no Guia do desenvolvedor do Amazon S3.

  • Para obter detalhes da API, consulte ListObjects na Referência de comandos da AWS CLI.

PowerShell
Tools for PowerShell

Exemplo 1: este comando recupera as informações sobre todos os itens no bucket “test-files”.

Get-S3Object -BucketName test-files

Exemplo 2: este comando recupera as informações sobre o item “sample.txt” do bucket “test-files”.

Get-S3Object -BucketName test-files -Key sample.txt

Exemplo 3: este comando recupera as informações sobre todos os itens com prefixo “sample” do bucket “test-files”.

Get-S3Object -BucketName test-files -KeyPrefix sample
  • Consulte detalhes da API em ListObjects em AWS Tools for PowerShell Cmdlet Reference.