Compartilhar via

Listar contêineres

  • Artigo

A List Containers operação retorna uma lista dos contêineres na conta de armazenamento especificada.

Solicitação

Você pode construir a solicitação da List Containers seguinte maneira. HTTPS é recomendado. Substitua myaccount pelo nome da sua conta de armazenamento.

Método URI da solicitação Versão HTTP
GET https://myaccount.blob.core.windows.net/?comp=list HTTP/1.1

Observe que o URI sempre deve incluir a barra (/) para separar o nome do host do caminho e as partes de consulta do URI. No caso da operação List Containers, a parte do caminho do URI fica vazia.

Solicitação de serviço de armazenamento emulado

Ao fazer uma solicitação no serviço de armazenamento emulado, especifique o nome do host do emulador e Armazenamento de Blobs do Azure porta como 127.0.0.1:10000, seguido pelo nome da conta de armazenamento emulado.

Método URI da solicitação Versão HTTP
GET http://127.0.0.1:10000/devstoreaccount1?comp=list HTTP/1.1

Observe que o armazenamento emulado só dá suporte a tamanhos de blob de até 2 GiB.

Para obter mais informações, consulte Usar o emulador do Azurite para desenvolvimento local do Armazenamento do Azure e Diferenças entre o emulador de armazenamento e os serviços de Armazenamento do Azure.

Parâmetros do URI

Você pode especificar os seguintes parâmetros adicionais no URI de solicitação.

Parâmetro Descrição
prefix Opcional. Filtra os resultados para retornar somente contêineres com um nome que começa com o prefixo especificado.
marker Opcional. Um valor de cadeia de caracteres que identifica a parte da lista de contêineres a ser retornada com a próxima operação de listagem. A operação retornará o NextMarker valor dentro do corpo da resposta, se a operação de listagem não retornar todos os contêineres restantes a serem listados com a página atual. Você pode usar o NextMarker valor como o valor do marker parâmetro em uma chamada subsequente para solicitar a próxima página de itens de lista.

O valor do marcador é opaco ao cliente.
maxresults Opcional. Especifica o número máximo de contêineres a serem retornados. Se a solicitação não especificar maxresultsou especificar um valor maior que 5000, o servidor retornará até 5.000 itens.

Observe que, se a operação de listagem cruzar um limite de partição, o serviço retornará um token de continuação para recuperar o restante dos resultados. Por esse motivo, é possível que o serviço retorne menos resultados do que o especificado por maxresultsou o padrão de 5000.

Se o parâmetro for definido como um valor menor ou igual a zero, o servidor retornará status código 400 (Solicitação Incorreta).
include={metadata,deleted,system} Opcional. Especifica um ou mais conjuntos de dados a serem incluídos na resposta:

- metadata: observe que os metadados solicitados com esse parâmetro devem ser armazenados de acordo com as restrições de nomenclatura impostas pela versão 2009-09-19 do Armazenamento de Blobs. A partir dessa versão, todos os nomes de metadados devem aderir às convenções de nomenclatura para identificadores C#.
- deleted: versão 2019-12-12 e posterior. Especifica que contêineres excluídos temporariamente devem ser incluídos na resposta.
- system: versão 2020-10-02 e posterior. Especifica se os contêineres do sistema devem ser incluídos na resposta. A inclusão dessa opção listará contêineres do sistema, como $logs e $changefeed. Observe que os contêineres específicos do sistema retornados variarão, com base em quais recursos de serviço estão habilitados na conta de armazenamento.
timeout Opcional. O parâmetro timeout é expresso em segundos. Para obter mais informações, consulte Configurando tempos limite para operações de Armazenamento de Blobs.

Cabeçalhos da solicitação

A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais.

Cabeçalho da solicitação Descrição
Authorization Obrigatórios. Especifica o esquema de autorização, o nome da conta e a assinatura. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
Date ou x-ms-date Obrigatórios. Especifica o UTC (Tempo Universal Coordenado) para a solicitação. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure.
x-ms-version Necessário para todas as solicitações autorizadas. Especifica a versão da operação a ser usada para esta solicitação. Para obter mais informações, consulte Controle de versão para os Serviços de Armazenamento do Azure.
x-ms-client-request-id Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres KiB (1 kibibyte) que é registrado nos logs quando o registro em log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações recebidas pelo servidor. Para obter mais informações, consulte Monitorar Armazenamento de Blobs do Azure.

Corpo da solicitação

Nenhum.

Resposta

A resposta inclui um código de status HTTP, um conjunto de cabeçalhos de resposta e um corpo de resposta no formato XML.

Código de status

Uma operação bem-sucedida retorna o código de status 200 (OK). Para obter informações sobre códigos de status, consulte Códigos de status e de erro.

Cabeçalhos de resposta

A resposta para esta operação inclui os cabeçalhos a seguir. A resposta também inclui cabeçalhos HTTP padrão adicionais. Todos os cabeçalhos padrão estão em conformidade com a especificação do protocolo HTTP/1.1.

Cabeçalho de resposta Descrição
Content-Type Cabeçalho HTTP/1.1 padrão. Especifica o formato em que os resultados são retornados. Atualmente, esse valor é application/xml.
x-ms-request-id Esse cabeçalho identifica exclusivamente a solicitação que foi feita e pode ser usado para solucionar problemas da solicitação. Para obter mais informações, consulte Solução de problemas de operações de API.
x-ms-version Indica a versão do Armazenamento de Blobs usada para executar a solicitação. Esse cabeçalho é retornado para solicitações feitas na versão 2009-09-19 e mais recente.
Date Um valor de data/hora UTC que indica a hora em que a resposta foi iniciada. O serviço gera esse valor.
x-ms-client-request-id Você pode usar esse cabeçalho para solucionar problemas de solicitações e respostas correspondentes. O valor desse cabeçalho é igual ao valor do x-ms-client-request-id cabeçalho, se ele estiver presente na solicitação. O valor é no máximo 1024 caracteres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente na solicitação, esse cabeçalho não estará presente na resposta.

Corpo da resposta

O formato do corpo da resposta é o seguinte.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.blob.core.windows.net">  
  <Prefix>string-value</Prefix>  
  <Marker>string-value</Marker>  
  <MaxResults>int-value</MaxResults>  
  <Containers>  
    <Container>  
      <Name>container-name</Name>  
      <Version>container-version</Version>
      <Deleted>true</Deleted>
      <Properties>  
        <Last-Modified>date/time-value</Last-Modified>  
        <Etag>etag</Etag>  
        <LeaseStatus>locked | unlocked</LeaseStatus>  
        <LeaseState>available | leased | expired | breaking | broken</LeaseState>  
        <LeaseDuration>infinite | fixed</LeaseDuration> 
        <PublicAccess>container | blob</PublicAccess>
        <HasImmutabilityPolicy>true | false</HasImmutabilityPolicy>
        <HasLegalHold>true | false</HasLegalHold>
        <DeletedTime>datetime</DeletedTime>
        <RemainingRetentionDays>no-of-days</RemainingRetentionDays>
      </Properties>  
      <Metadata>  
        <metadata-name>value</metadata-name>  
      </Metadata>  
    </Container>  
  </Containers>  
  <NextMarker>marker-value</NextMarker>  
</EnumerationResults>

LeaseStatus, LeaseState e LeaseDuration aparecem somente na versão 2012-02-12 e mais recentes.

A partir da versão 2013-08-15, o atributo AccountName para o elemento EnumerationResults foi renomeado para ServiceEndpoint. O elemento URL também foi removido do elemento Container. Para versões anteriores a 2013-08-15, a URL do contêiner, conforme especificado pelo URL campo, não inclui o restype=container parâmetro . Se você usar esse valor para fazer solicitações subsequentes nos contêineres enumerados, acrescente esse parâmetro para indicar que o tipo de recurso é um contêiner.

Os Prefixelementos , Markere MaxResults só estarão presentes se você especificá-los no URI. O NextMarker elemento terá um valor somente se os resultados da lista não estiverem concluídos.

O Metadata elemento estará presente somente se você especificar o include=metadata parâmetro no URI. No elemento Metadata, o valor de cada par de nome-valor é listado em um elemento correspondente ao nome do par.

Se um par nome-valor de metadados violar as restrições de nomenclatura impostas pela versão 2009-09-19, o corpo da resposta indicará o nome problemático dentro de um x-ms-invalid-name elemento. O seguinte fragmento XML mostra o seguinte:

  
<Metadata>  
  <MyMetadata1>first value</MyMetadata1>  
  <MyMetadata2>second value</MyMetadata2>  
  <x-ms-invalid-name>invalid-metadata-name</x-ms-invalid-name>  
</Metadata>

A partir da versão 2016-05-31, as permissões públicas do contêiner são fornecidas na PublicAccess propriedade . Indica se os dados no contêiner podem ser acessados publicamente e o nível de acesso. Os valores possíveis incluem:

  • container: indica acesso de leitura público completo para dados de contêiner e blob. Os clientes podem enumerar blobs dentro do contêiner por meio de solicitação anônima, mas não podem enumerar contêineres dentro da conta de armazenamento.
  • blob: indica o acesso de leitura público para blobs. Os dados de blob dentro desse contêiner podem ser lidos por meio de solicitação anônima, mas os dados do contêiner não estão disponíveis. Os clientes não podem enumerar blobs dentro do contêiner por meio de solicitação anônima.

Se essa propriedade não for especificada na <properties> seção, o contêiner será privado para o proprietário da conta.

HasImmutabilityPolicy e HasLegalHold aparecem apenas na versão 2017-11-09 e posterior. HasImmutabilityPolicy é true se o contêiner tiver uma política de imutabilidade definida nele e false , caso contrário, . HasLegalHold é true se o contêiner tiver uma ou mais retenções legais sobre ele e false , caso contrário, .

Observação

A partir da versão 2009-09-19, o corpo da resposta para List Containers retorna a última hora modificada do contêiner, em um elemento chamado Last-Modified. Em versões anteriores, esse elemento era denominado LastModified.

Os Versionelementos , Deleted, DeletedTimee RemainingRetentiondays só aparecem na versão 2019-12-12 e posterior se você especificar o deleted valor para o parâmetro includede consulta . Esses elementos só aparecerão se o contêiner for excluído temporariamente e estiver qualificado para ser restaurado. Os Versionelementos , Deleted, DeletedTimee RemainingRetentiondays só aparecerão na versão 2019-12-12 e posterior se o valor excluído for especificado para o include parâmetro de consulta e se o contêiner for excluído e qualificado para ser restaurado.

Autorização

A autorização é necessária ao chamar qualquer operação de acesso a dados no Armazenamento do Azure. Você pode autorizar a List Containers operação, conforme descrito abaixo.

Importante

A Microsoft recomenda usar Microsoft Entra ID com identidades gerenciadas para autorizar solicitações ao Armazenamento do Azure. Microsoft Entra ID fornece segurança superior e facilidade de uso em comparação com a autorização de Chave Compartilhada.

O Armazenamento do Azure dá suporte ao uso de Microsoft Entra ID para autorizar solicitações para dados de blob. Com Microsoft Entra ID, você pode usar o RBAC (controle de acesso baseado em função) do Azure para conceder permissões a uma entidade de segurança. A entidade de segurança pode ser um usuário, grupo, entidade de serviço de aplicativo ou identidade gerenciada do Azure. A entidade de segurança é autenticada por Microsoft Entra ID para retornar um token OAuth 2.0. Em seguida, o token pode ser usado para autorizar uma solicitação no serviço de Blob.

Para saber mais sobre a autorização usando Microsoft Entra ID, consulte Autorizar o acesso a blobs usando Microsoft Entra ID.

Permissões

Veja abaixo a ação RBAC necessária para um usuário Microsoft Entra, grupo, identidade gerenciada ou entidade de serviço para chamar a List Containers operação e a função RBAC interna do Azure com menos privilégios que inclui esta ação:

Para saber mais sobre como atribuir funções usando o RBAC do Azure, confira Atribuir uma função do Azure para acesso aos dados de blob.

Comentários

Se você especificar um valor para o maxresults parâmetro e o número de contêineres a serem retornados exceder esse valor ou exceder o valor padrão para maxresults, o corpo da resposta conterá o NextMarker elemento . (Isso também é chamado de token de continuação).

NextMarker indica o próximo contêiner a ser retornado em uma solicitação subsequente. Para retornar o próximo conjunto de itens, especifique o valor de NextMarker para o marker parâmetro no URI para a solicitação subsequente. Observe que o valor de NextMarker deve ser tratado como opaco.

Se a operação de listagem cruzar um limite de partição, o serviço retornará um valor para o NextMarker elemento para recuperar o restante dos resultados da próxima partição. Uma operação de listagem que abrange mais de uma partição resulta em um conjunto menor de itens sendo retornados do que o especificado por maxresultsou o padrão de 5000. Seu aplicativo deve sempre marcar para a presença do NextMarker elemento quando você executa uma operação de listagem e maniê-lo adequadamente.

Os contêineres são listados em ordem alfabética no corpo da resposta.

A operação List Containers expira depois de 30 segundos.

Cobrança

As solicitações de preços podem ser originadas de clientes que usam APIs de Armazenamento de Blobs, diretamente por meio da API REST do Armazenamento de Blobs ou de uma biblioteca de clientes do Armazenamento do Azure. Essas solicitações acumulam encargos por transação. O tipo de transação afeta a forma como a conta é cobrada. Por exemplo, as transações de leitura se acumulam em uma categoria de cobrança diferente das transações de gravação. A tabela a seguir mostra a categoria de cobrança para List Containers solicitações com base no tipo de conta de armazenamento:

Operação Tipo de conta de armazenamento Categoria de cobrança
Listar contêineres Blob de blocos Premium
Uso geral v2 Standard
Uso geral v1 Standard		 Listar e Create operações de contêiner

Para saber mais sobre os preços para a categoria de cobrança especificada, consulte Armazenamento de Blobs do Azure Preços.

Exemplo de solicitação e resposta

O URI de exemplo a seguir solicita a lista de contêineres para uma conta, definindo os resultados máximos a serem retornados para a operação inicial como três.

GET https://myaccount.blob.core.windows.net/?comp=list&maxresults=3 HTTP/1.1

A solicitação é enviada com estes cabeçalhos:

x-ms-version: 2016-05-31  
x-ms-date: Wed, 26 Oct 2016 22:08:44 GMT  
Authorization: SharedKey myaccount:CY1OP3O3jGFpYFbTCBimLn0Xov0vt0khH/D5Gy0fXvg=

Os cabeçalhos de código de status e de resposta são retornados da seguinte forma:

HTTP/1.1 200 OK  
Transfer-Encoding: chunked  
Content-Type: application/xml  
Date: Wed, 26 Oct 2016 22:08:54 GMT  
x-ms-version: 2016-05-31  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

A resposta XML para essa solicitação é a seguinte. Observe que o NextMarker elemento segue o conjunto de contêineres e inclui o nome do próximo contêiner a ser retornado.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.blob.core.windows.net/">  
  <MaxResults>3</MaxResults>  
  <Containers>  
    <Container>  
      <Name>audio</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7C6B1B2</Etag> 
        <PublicAccess>container</PublicAccess> 
      </Properties>  
    </Container>  
    <Container>  
      <Name>images</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7C1EEEC</Etag>  
      </Properties>  
    </Container>  
    <Container>  
      <Name>textfiles</Name>  
      <Properties>  
        <Last-Modified>Wed, 26 Oct 2016 20:39:39 GMT</Last-Modified>  
        <Etag>0x8CACB9BD7BACAC3</Etag>  
      </Properties>  
    </Container>  
  </Containers>  
  <NextMarker>video</NextMarker>  
</EnumerationResults>

A operação subsequente da lista especifica o marcador no URI de solicitação, da seguinte forma. O próximo conjunto de resultados é retornado, começando com o contêiner especificado pelo marcador.

https://myaccount.blob.core.windows.net/?comp=list&maxresults=3&marker=video

Confira também

Autorizar solicitações para o Armazenamento do Azure
Status e códigos de erro
Códigos de erro do Armazenamento de Blobs
Enumerando recursos de blob
Usando o emulador de Armazenamento do Azure para desenvolvimento e teste
Definindo tempos limite para operações de Armazenamento de Blobs