Listar Contentores

Artigo
02/03/2024

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 `maxresults`ou 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.

Importante

A Microsoft recomenda a utilização de Microsoft Entra ID com identidades geridas para autorizar pedidos para o Armazenamento do Azure. Microsoft Entra ID fornece segurança superior e facilidade de utilização em comparação com a autorização de Chave Partilhada.

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 estão listadas as ações RBAC necessárias para que um utilizador Microsoft Entra, grupo, identidade gerida ou principal de serviço chame a List Containers operação e a função RBAC do Azure com menos privilégios que inclua esta ação:

Ação RBAC do Azure:Microsoft.Storage/storageAccounts/blobServices/containers/read (no âmbito da conta de armazenamento ou superior)
Função incorporada com menos privilégios:Contribuidor de Dados do Blob de Armazenamento (no âmbito da conta de armazenamento ou superior)

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.

Uma assinatura de acesso partilhado (SAS) fornece acesso delegado seguro aos recursos numa conta de armazenamento. Com uma SAS, tem controlo granular sobre como um cliente pode aceder aos dados. Pode especificar o recurso a que o cliente pode aceder, que permissões têm para esses recursos e quanto tempo a SAS é válida.

A List Containers operação suporta a autorização através de uma SAS de conta.

Quando o acesso à Chave Partilhada não for permitido para a conta de armazenamento, não será permitido um token de SAS de conta num pedido ao Armazenamento de Blobs. Para saber mais, veja Compreender como a desativação da Chave Partilhada afeta os tokens de SAS.

SAS de Conta

Uma SAS de conta é protegida com a chave da conta de armazenamento. Uma conta SAS delega o acesso aos recursos em um ou mais dos serviços de armazenamento. Todas as operações disponíveis através de um serviço ou saS de delegação de utilizador também estão disponíveis através de uma SAS de conta.

A tabela seguinte indica o tipo de recurso assinado e as permissões assinadas a especificar ao delegar o acesso:

Operação	Serviço assinado	Tipo de recurso assinado	Permissão assinada
Listar Contentores	Blob (b)	Serviço (s)	Lista (l)

Para saber mais sobre a SAS da conta, veja Create uma SAS de conta.

A List Containers operação suporta a autorização de Chave Partilhada. A autorização com chaves de conta não é recomendada para a maioria dos cenários, uma vez que é menos segura. A Microsoft recomenda a desativação da autorização de Chave Partilhada para a conta de armazenamento sempre que possível. Para obter mais informações, veja Impedir a autorização com a Chave Partilhada.

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 Create 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

Partilhar via