Listar Contentores

  • Artigo

A List Containers operação devolve uma lista dos contentores na conta de armazenamento especificada.

Pedir

Pode construir o pedido da List Containers seguinte forma. É recomendado HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento.

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

Tenha em atenção que o URI tem de incluir sempre a barra (/) para separar o nome do anfitrião das partes de caminho e consulta do URI. No caso da List Containers operação, a parte do caminho do URI está vazia.

Pedido de serviço de armazenamento emulado

Quando fizer um pedido contra o serviço de armazenamento emulado, especifique o nome do anfitrião do emulador e Armazenamento de Blobs do Azure porta como 127.0.0.1:10000, seguido do nome da conta de armazenamento emulada.

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

Tenha em atenção que o armazenamento emulado só suporta tamanhos de blobs até 2 GiB.

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

Parâmetros URI

Pode especificar os seguintes parâmetros adicionais no URI do pedido.

Parâmetro Description
prefix Opcional. Filtra os resultados para devolver apenas contentores com um nome que começa com o prefixo especificado.
marker Opcional. Um valor de cadeia que identifica a parte da lista de contentores a devolver com a próxima operação de listagem. A operação devolve o NextMarker valor no corpo da resposta, se a operação de listagem não devolver todos os contentores restantes para serem listados com a página atual. Pode utilizar o NextMarker valor como o valor do marker parâmetro numa chamada subsequente para pedir a página seguinte dos itens de lista.

O valor do marcador é opaco para o cliente.
maxresults Opcional. Especifica o número máximo de contentores a devolver. Se o pedido não especificar maxresultsou especificar um valor superior a 5000, o servidor devolverá até 5000 itens.

Tenha em atenção que, se a operação de listagem atravessar um limite de partição, o serviço devolverá um token de continuação para obter o resto dos resultados. Por este motivo, é possível que o serviço devolva menos resultados do que o especificado por maxresults, ou do que a predefinição de 5000.

Se o parâmetro estiver definido como um valor inferior ou igual a zero, o servidor devolve o código de estado 400 (Pedido Incorreto).
include={metadata,deleted,system} Opcional. Especifica um ou mais conjuntos de dados a incluir na resposta:

-metadata: tenha em atenção que os metadados pedidos com este parâmetro têm de ser armazenados de acordo com as restrições de nomenclatura impostas pela versão 2009-09-19 do Armazenamento de Blobs. A partir desta versão, todos os nomes de metadados têm de cumprir as convenções de nomenclatura dos identificadores C#.
-deleted: Versão 2019-12-12 e posterior. Especifica que os contentores eliminados de forma recuperável devem ser incluídos na resposta.
-system: Versão 2020-10-02 e posterior. Especifica se os contentores do sistema devem ser incluídos na resposta. A inclusão desta opção irá listar contentores de sistema, como $logs e $changefeed. Tenha em atenção que os contentores de sistema específicos devolvidos variam consoante as funcionalidades de serviço que estão ativadas na conta de armazenamento.
timeout Opcional. O timeout parâmetro é expresso em segundos. Para obter mais informações, veja Definir tempos limite para operações de Armazenamento de Blobs.

Cabeçalhos do pedido

A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.

Cabeçalho do pedido Description
Authorization Obrigatório. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
Date ou x-ms-date Obrigatório. Especifica a Hora Universal Coordenada (UTC) do pedido. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure.
x-ms-version Necessário para todos os pedidos autorizados. Especifica a versão da operação a utilizar para este pedido. Para obter mais informações, veja Controlo de versões dos serviços de Armazenamento do Azure.
x-ms-client-request-id Opcional. Fornece um valor opaco gerado pelo cliente com um limite de carateres de 1 kibibyte (KiB) que é registado nos registos quando o registo é configurado. Recomendamos vivamente que utilize este cabeçalho para correlacionar as atividades do lado do cliente com os pedidos que o servidor recebe. Para obter mais informações, veja Monitorizar Armazenamento de Blobs do Azure.

Corpo do pedido

Nenhum.

Resposta

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

Código de estado

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

Cabeçalhos de resposta

A resposta para esta operação inclui os seguintes cabeçalhos. 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 no qual os resultados são devolvidos. Atualmente, este valor é application/xml.
x-ms-request-id Este cabeçalho identifica exclusivamente o pedido que foi feito e pode ser utilizado para resolver o pedido. Para obter mais informações, veja Resolver problemas de operações da API.
x-ms-version Indica a versão do Armazenamento de Blobs utilizada para executar o pedido. Este cabeçalho é devolvido para pedidos feitos na versão 2009-09-19 e posterior.
Date Um valor de data/hora UTC que indica a hora em que a resposta foi iniciada. O serviço gera este valor.
x-ms-client-request-id Pode utilizar este cabeçalho para resolver problemas de pedidos e respostas correspondentes. O valor deste cabeçalho é igual ao valor do x-ms-client-request-id cabeçalho, se estiver presente no pedido. O valor é, no máximo, 1024 carateres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente no pedido, este 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, LeaseStatee LeaseDuration só aparecem na versão 2012-02-12 e posterior.

A partir da versão 2013-08-15, o AccountName atributo do EnumerationResults elemento foi mudado para ServiceEndpoint. O URL elemento também foi removido do Container elemento . Para versões anteriores a 2013-08-15, o URL do contentor, conforme especificado pelo URL campo, não inclui o restype=container parâmetro . Se utilizar este valor para fazer pedidos subsequentes relativamente aos contentores enumerados, confirme que acrescenta este parâmetro para indicar que o tipo de recurso é um contentor.

Os Prefixelementos , Markere MaxResults só estão presentes se os especificar no URI. O NextMarker elemento só tem um valor se os resultados da lista não estiverem concluídos.

O Metadata elemento só está presente se especificar o include=metadata parâmetro no URI. Metadata No elemento , o valor de cada par nome-valor é listado dentro de 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 indica o nome problemático dentro de um x-ms-invalid-name elemento. O fragmento XML seguinte 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 contentor são fornecidas na PublicAccess propriedade . Indica se os dados no contentor podem ser acedidos publicamente e o nível de acesso. Valores possíveis incluem:

  • container: indica acesso de leitura público completo para dados de contentores e blobs. Os clientes podem enumerar blobs no contentor através de um pedido anónimo, mas não podem enumerar contentores na conta de armazenamento.
  • blob: indica o acesso de leitura público para blobs. Os dados de blobs neste contentor podem ser lidos através de um pedido anónimo, mas os dados de contentor não estão disponíveis. Os clientes não podem enumerar blobs no contentor através de um pedido anónimo.

Se esta propriedade não for especificada na <properties> secção , o contentor é privado para o proprietário da conta.

HasImmutabilityPolicy e HasLegalHold só aparecem na versão 2017-11-09 e posterior. HasImmutabilityPolicy é true se o contentor tiver uma política de imutabilidade definida, caso false contrário. HasLegalHold se true o contentor tiver uma ou mais retenções legais, caso false contrário.

Nota

A partir da versão 2009-09-19, o corpo de resposta de List Containers devolve a hora da última modificação do contentor, num elemento chamado Last-Modified. Em versões anteriores, este elemento tinha o nome LastModified.

Os Versionelementos , Deleted, DeletedTimee RemainingRetentiondays só aparecem na versão 2019-12-12 e posterior se especificar o deleted valor para o parâmetro includede consulta . Estes elementos só aparecem se o contentor for eliminado de forma recuperável e for elegível para ser restaurado. Os Versionelementos , Deleted, DeletedTimee RemainingRetentiondays só aparecem na versão 2019-12-12 e posterior se o valor eliminado for especificado para o include parâmetro de consulta e se o contentor for eliminado de forma recuperável e elegível para ser restaurado.

Autorização

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

O Armazenamento do Azure suporta a utilização de Microsoft Entra ID para autorizar pedidos a dados de blobs. Com Microsoft Entra ID, pode utilizar o controlo de acesso baseado em funções do Azure (RBAC do Azure) para conceder permissões a um principal de segurança. O principal de segurança pode ser um utilizador, grupo, principal de serviço de aplicação ou identidade gerida do Azure. O principal de segurança é autenticado por Microsoft Entra ID para devolver um token OAuth 2.0. Em seguida, o token pode ser utilizado para autorizar um pedido contra o serviço Blob.

Para saber mais sobre a autorização através de Microsoft Entra ID, veja Autorizar o acesso a blobs com Microsoft Entra ID.

Permissões

Abaixo encontra-se a ação RBAC necessária para um utilizador, grupo ou principal de serviço Microsoft Entra chamar a List Containers operação e a função RBAC do Azure com menos privilégios que inclui esta ação:

Para saber mais sobre como atribuir funções com o RBAC do Azure, veja Atribuir uma função do Azure para acesso a dados de blobs.

Observações

Se especificar um valor para o maxresults parâmetro e o número de contentores a devolver exceder este valor ou exceder o valor predefinido para maxresults, o corpo da resposta irá conter o NextMarker elemento . (Isto também é referido como um token de continuação).

NextMarker indica o contentor seguinte a devolver num pedido subsequente. Para devolver o próximo conjunto de itens, especifique o valor de NextMarker para o marker parâmetro no URI para o pedido subsequente. Tenha em atenção que o valor de NextMarker deve ser tratado como opaco.

Se a operação de listagem atravessar um limite de partição, o serviço devolverá um valor para o NextMarker elemento para obter o resto dos resultados da partição seguinte. Uma operação de listagem que abrange mais do que uma partição resulta na devolução de um conjunto mais pequeno de itens do que o especificado por maxresultsou do que a predefinição de 5000. A sua aplicação deve sempre verificar a presença do NextMarker elemento quando executa uma operação de listagem e processá-lo em conformidade.

Os contentores são listados por ordem alfabética no corpo da resposta.

A List Containers operação excede o limite de tempo após 30 segundos.

Faturação

Os pedidos de preços podem ter origem em clientes que utilizam APIs de Armazenamento de Blobs, diretamente através da API REST do Armazenamento de Blobs ou a partir de uma biblioteca de cliente do Armazenamento do Azure. Estes pedidos acumulam custos por transação. O tipo de transação afeta a forma como a conta é cobrada. Por exemplo, as transações de leitura acumulam-se numa categoria de faturação diferente das transações de escrita. A tabela seguinte mostra a categoria de faturação dos List Containers pedidos com base no tipo de conta de armazenamento:

Operação Tipo de conta de armazenamento Categoria de faturação
Listar Contentores Blob de blocos Premium
Standard para fins gerais v2
Standard para fins gerais v1		 Listar e Criar Operações de contentor

Para saber mais sobre os preços da categoria de faturação especificada, veja Preços do Armazenamento de Blobs do Azure.

Pedido e resposta de exemplo

O URI de exemplo seguinte pede a lista de contentores para uma conta, definindo os resultados máximos a devolver para a operação inicial para três.

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

O pedido é enviado 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=

O código de estado e os cabeçalhos de resposta são devolvidos 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

O XML de resposta para este pedido é o seguinte. Tenha em atenção que o NextMarker elemento segue o conjunto de contentores e inclui o nome do contentor seguinte a ser devolvido.

<?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 de lista subsequente especifica o marcador no URI do pedido, da seguinte forma. O próximo conjunto de resultados é devolvido, começando pelo contentor especificado pelo marcador.

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

Ver também

Autorizar pedidos para o Armazenamento do Azure
Códigos de estado e de erro
Códigos de erro do Armazenamento de Blobs
Enumerar recursos de blobs
Utilizar o emulador do Armazenamento do Azure para desenvolvimento e teste
Definir tempos limite para operações de Armazenamento de Blobs