Partilhar via

Listar Blobs

  • Artigo

A operação List Blobs retorna uma lista dos blobs sob o contêiner especificado.

Solicitar

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

Método Solicitar URI Versão HTTP
GET https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list HTTP/1.1

URI do serviço de armazenamento emulado

Quando você fizer uma solicitação no serviço de armazenamento emulado, especifique o nome do host do emulador e a porta do Armazenamento de Blobs do Azure como 127.0.0.1:10000, seguido pelo nome da conta de armazenamento emulada.

Método Solicitar URI Versão HTTP
GET http://127.0.0.1:10000/devstoreaccount1/mycontainer?restype=container&comp=list HTTP/1.1

Para obter mais informações, consulte Usar emulador Azurite para o desenvolvimento do Armazenamento do Azure local.

Parâmetros de URI

Você pode especificar os seguintes parâmetros adicionais no URI.

Parâmetro Descrição
prefix Opcional. Filtra os resultados para retornar apenas blobs com nomes que começam com o prefixo especificado. Em contas que têm um namespace hierárquico, ocorrerá um erro nos casos em que o nome de um arquivo aparece no meio do caminho do prefixo. Por exemplo, você pode tentar localizar blobs nomeados readmefile.txt usando o caminho do prefixo folder1/folder2/readme/readmefile.txt. Será apresentado um erro se qualquer subpasta contiver um ficheiro denominado readme.
delimiter Opcional. Quando a solicitação inclui esse parâmetro, a operação retorna um elemento BlobPrefix no corpo da resposta. Este elemento atua como um espaço reservado para todos os blobs com nomes que começam com a mesma substring, até a aparência do caractere delimitador. O delimitador pode ser um único caractere ou uma cadeia de caracteres.
marker Opcional. Um valor de cadeia de caracteres que identifica a parte da lista a ser retornada com a próxima operação de lista. A operação retorna um valor de marcador dentro do corpo da resposta se a lista retornada não estiver completa. Em seguida, você pode usar o valor do marcador em uma chamada subsequente para solicitar o próximo conjunto de itens de lista.

O valor do marcador é opaco para o cliente.
maxresults Opcional. Especifica o número máximo de blobs a serem retornados, incluindo todos os elementos BlobPrefix. Se a solicitação não especificar maxresultsou especificar um valor maior que 5.000, o servidor retornará até 5.000 itens. Se houver resultados adicionais a serem retornados, o serviço retornará um token de continuação no elemento de resposta NextMarker. Em certos casos, o serviço pode retornar menos resultados do que o especificado pelo maxresultse também retornar um token de continuação.

Definir maxresults para um valor menor ou igual a zero resulta no código de resposta de erro 400 (Solicitação incorreta).
include={snapshots,metadata,uncommittedblobs,copy,deleted,tags,versions,
deletedwithversions,immutabilitypolicy,legalhold,permissions}		 Opcional. Especifica um ou mais conjuntos de dados a serem incluídos na resposta:

- snapshots: Especifica que os instantâneos devem ser incluídos na enumeração. Os instantâneos são listados do mais antigo para o mais recente na resposta.
- metadata: Especifica que os metadados de blob sejam retornados na resposta.
- uncommittedblobs: Especifica que os blobs para os quais os blocos foram carregados, mas que não foram confirmados usando Put Block List, sejam incluídos na resposta.
- copy: Versão 2012-02-12 e posteriores. Especifica que os metadados relacionados a qualquer operação de Copy Blob atual ou anterior devem ser incluídos na resposta.
- deleted: Versão 2017-07-29 e posterior. Especifica que blobs excluídos suavemente devem ser incluídos na resposta.
- tags: Versão 2019-12-12 e posterior. Especifica que as tags de índice de blob definidas pelo usuário devem ser incluídas na resposta.
- versions: Versão 2019-12-12 e posterior. Especifica que as versões de blobs devem ser incluídas na enumeração.
- deletedwithversions: Versão 2020-10-02 e posterior. Especifica que blobs excluídos com quaisquer versões (ativas ou excluídas) devem ser incluídos na resposta. Os itens que você excluiu permanentemente aparecem na resposta até que sejam processados pela coleta de lixo. Use a tag \<HasVersionsOnly\>e o valor true.
- immutabilitypolicy: Versão 2020-06-12 e posterior. Especifica que a enumeração deve incluir a política de imutabilidade até a data e o modo de política de imutabilidade dos blobs.
- legalhold: Versão 2020-06-12 e posterior. Especifica que a enumeração deve incluir a retenção legal de blobs.
- permissions: Versão 2020-06-12 e posterior. Suportado apenas para contas com um namespace hierárquico habilitado. Se uma solicitação incluir esse parâmetro, o proprietário, o grupo, as permissões e a lista de controle de acesso para os blobs ou diretórios listados serão incluídos na enumeração.

Para especificar mais de uma dessas opções no URI, você deve separar cada opção com uma vírgula codificada por URL ("%82").
showonly={deleted,files,directories} Opcional. Especifica um destes conjuntos de dados a serem retornados na resposta:

- deleted: Opcional. Versão 2020-08-04 e posterior. Somente para contas habilitadas com namespace hierárquico. Quando uma solicitação inclui esse parâmetro, a lista contém apenas blobs excluídos por software. Observe que o fallback de autorização da ACL POSIX não é suportado para listar blobs excluídos suavemente. Se include=deleted também for especificado, a solicitação falhará com Solicitação incorreta (400).
- files: Opcional. Versão 2020-12-06 e posterior. Somente para contas habilitadas com namespace hierárquico. Quando uma solicitação inclui esse parâmetro, a lista contém apenas arquivos.
- directories: Opcional. Versão 2020-12-06 e posterior. Somente para contas habilitadas com namespace hierárquico. Quando uma solicitação inclui esse parâmetro, a lista contém apenas diretórios.
timeout Opcional. O parâmetro timeout é expresso em segundos. Para obter mais informações, consulte Definindo tempos limite para operações de armazenamento de Blob.

Cabeçalhos de 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 Necessário. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure.
Date ou x-ms-date Necessário. Especifica o Tempo Universal Coordenado (UTC) para a solicitação. Para obter mais informações, consulte Autorizar solicitações para o Armazenamento do Azure.
x-ms-version Obrigatório para todos os pedidos autorizados e opcional para pedidos anónimos. Especifica a versão da operação a ser usada para essa 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 de 1 kibibyte (KiB) que é registrado nos logs quando o log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações que o servidor recebe. Para obter mais informações, consulte Monitor Azure Blob Storage.
x-ms-upn Opcional. Válido somente quando um namespace hierárquico está habilitado para a conta e include=permissions é fornecido na solicitação. Se true, os valores de identidade do usuário retornados nos campos <>Proprietário, <Grupo>e <Acl> são transformados de IDs de objeto do Microsoft Entra para nomes principais de usuário. Se false, os valores são retornados como IDs de objeto do Microsoft Entra. O valor padrão é false. Observe que as IDs de objeto de grupo e aplicativo não são traduzidas porque não têm nomes amigáveis exclusivos.

Corpo do pedido

Nenhuma.

Pedido de amostra

Consulte Enumerando recursos de blob para obter uma solicitação de exemplo.

Resposta

A resposta inclui um código de status HTTP, um conjunto de cabeçalhos de resposta e um corpo de resposta em 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 seguintes cabeçalhos. A resposta também pode incluir 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 da resposta Descrição
Content-Type Especifica o formato no qual os resultados são retornados. Atualmente este 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 Blob usada para executar a solicitação. Este cabeçalho é retornado para solicitações feitas usando a versão 2009-09-19 e posterior.

Esse cabeçalho também é retornado para solicitações anônimas, sem uma versão especificada, se o contêiner foi marcado para acesso público usando a versão 2009-09-19 do Armazenamento de Blob.
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 cabeçalho x-ms-client-request-id, se ele estiver presente na solicitação. O valor é, no máximo, 1024 caracteres ASCII visíveis. Se o cabeçalho x-ms-client-request-id não estiver presente na solicitação, esse cabeçalho não estará presente na resposta.

Corpo de resposta

O formato da resposta XML é o seguinte.

Observe que os elementos Prefix, Marker, MaxResultse Delimiter estão presentes somente se tiverem sido especificados no URI da solicitação. O elemento NextMarker tem um valor somente se os resultados da lista não estiverem completos.

Instantâneos, metadados de blob e blobs não confirmados são incluídos na resposta somente se forem especificados com o parâmetro include no URI da solicitação.

Na versão 2009-09-19 e posterior, as propriedades do blob são encapsuladas dentro de um elemento Properties.

A partir da versão 2009-09-19, List Blobs retorna os seguintes elementos renomeados no corpo da resposta:

  • Last-Modified (anteriormente LastModified)

  • Content-Length (anteriormente Size)

  • Content-Type (anteriormente ContentType)

  • Content-Encoding (anteriormente ContentEncoding)

  • Content-Language (anteriormente ContentLanguage)

O elemento Content-MD5 aparece para blobs criados com a versão 2009-09-19 e posterior. Na versão 2012-02-12 e posterior, o Armazenamento de Blob calcula o valor de Content-MD5 quando você carrega um blob usando Put Blob. O Armazenamento de Blobs não calcula isso quando você cria um blob usando Put Block List. Você pode definir explicitamente o valor Content-MD5 ao criar o blob ou chamando o Put Block List ou set Blob Properties operações.

Para versões de 2009-09-19 e posteriores, mas anteriores à versão 2015-02-21, não é possível chamar List Blobs em um contêiner que inclua blobs de acréscimo. O serviço retorna o código de status 409 (Conflito) se o resultado da listagem contiver um blob de acréscimo.

LeaseState e LeaseDuration aparecem apenas na versão 2012-02-12 e posterior.

CopyId, CopyStatus, CopySource, CopyProgress, CopyCompletionTimee CopyStatusDescription só aparecem na versão 2012-02-12 e posterior, quando esta operação inclui o parâmetro include={copy}. Esses elementos não aparecerão se esse blob nunca tiver sido o destino em uma operação Copy Blob. Os elementos não aparecerão se esse blob tiver sido modificado após uma operação de Copy Blob concluída, usando Set Blob Properties, Put Blobou Put Block List. Esses elementos também não aparecem com um blob criado por Copy Blob, antes da versão 2012-02-12.

Na versão 2013-08-15 e posterior, o elemento EnumerationResults contém um atributo ServiceEndpoint que especifica o ponto de extremidade de blob. Esse elemento também contém um campo ContainerName que especifica o nome do contêiner. Nas versões anteriores, esses dois atributos eram combinados no campo ContainerName. Também na versão 2013-08-15 e posterior, o elemento Url em Blob foi removido.

Para a versão 2015-02-21 e posterior, List Blobs retorna blobs de todos os tipos (blobs de bloco, página e acréscimo).

Para a versão 2015-12-11 e posterior, List Blobs retorna o elemento ServerEncrypted. Esse elemento é definido como true se o blob e os metadados do aplicativo estiverem completamente criptografados e false contrário.

Para a versão 2016-05-31 e posterior, List Blobs retorna o elemento IncrementalCopy para blobs de cópia incremental e instantâneos, com o valor definido como true.

Para a versão 2017-04-17 e posterior, List Blobs retorna o elemento AccessTier se uma camada de acesso tiver sido definida explicitamente. Para obter uma lista de camadas de blob de página premium permitidas, consulte Armazenamento premium de alto desempenho e discos gerenciados para VMs. Para contas de Blob Storage ou v2 de uso geral, os valores válidos são Hot, Coole Archive. Se o blob estiver no estado pendente de hidratação, ArchiveStatus elemento será retornado com um dos valores válidos (rehydrate-pending-to-hot, rehydrate-pending-to-coolou rehydrate-pending-to-cold). Para obter informações detalhadas sobre a hierarquização de blob de bloco, consulte Níveis de armazenamento quentes, frescos e arquivados.

Para a versão 2017-04-17 e posterior, List Blobs retorna o elemento AccessTierInferred no Armazenamento de Blobs ou contas v2 de uso geral. Se o blob de bloco não tiver a camada de acesso definida, as informações da camada serão inferidas das propriedades da conta de armazenamento e esse valor será definido como true. Esse cabeçalho estará presente somente se a camada for inferida da propriedade account.

Para a versão 2017-04-17 e posterior, List Blobs retorna o elemento AccessTierChangeTime no Armazenamento de Blobs ou contas v2 de uso geral. Isso será retornado somente se a camada no blob de bloco já tiver sido definida. Para obter mais informações, consulte Representação de valores de data-hora em cabeçalhos.

Para a versão 2017-07-29 e posterior, Deleted, DeletedTimee RemainingRetentionDays aparecem quando esta operação inclui o parâmetro include={deleted}. Esses elementos não aparecerão se esse blob não tiver sido excluído. Esses elementos aparecem para blobs ou instantâneos que são excluídos com a operação DELETE, quando o recurso de exclusão suave foi habilitado. O elemento Deleted é definido como true para blobs e instantâneos excluídos suavemente. Deleted-Time corresponde ao momento em que o blob foi excluído. RemainingRetentionDays indica o número de dias após os quais um blob excluído suavemente é excluído permanentemente.

Para a versão 2017-11-09 e posterior, Creation-Time retorna o momento em que esse blob foi criado.

Para a versão 2019-02-02 e posterior, List Blobs retorna o elemento CustomerProvidedKeySha256 se o blob for criptografado com uma chave fornecida pelo cliente. O valor será definido como o hash SHA-256 da chave usada para criptografar o blob. Além disso, se a operação incluir o parâmetro include={metadata} e houver metadados de aplicativo presentes em um blob criptografado com uma chave fornecida pelo cliente, o elemento Metadata terá um atributo Encrypted="true". Esse atributo indica que o blob tem metadados que não podem ser descriptografados como parte da operação List Blobs. Para acessar os metadados desses blobs, chame Obter Propriedades de Blob ou Obter Metadados de Blob com a chave fornecida pelo cliente.

Para a versão 2019-02-02 e posterior, List Blobs retorna o elemento EncryptionScope se o blob estiver criptografado com um escopo de criptografia. O valor será definido como o nome do escopo de criptografia usado para criptografar o blob. Se a operação incluir o parâmetro include={metadata}, os metadados do aplicativo no blob serão descriptografados de forma transparente e estarão disponíveis no elemento Metadata.

Para a versão 2019-12-12 e posterior, List Blobs retorna o elemento RehydratePriority em contas de Blob Storage ou v2 de uso geral, se o objeto estiver no estado rehydrate pending. Os valores válidos são High e Standard.

Para a versão 2019-12-12 e posterior, List Blobs retorna o elemento VersionId para blobs e versões de blob geradas, quando o controle de versão está habilitado na conta.

Para a versão 2019-12-12 e posterior, List Blobs retorna o elemento IsCurrentVersion para a versão atual do blob. O valor é definido como true. Esse elemento permite diferenciar a versão atual das versões somente leitura geradas automaticamente.

Para a versão 2019-12-12 e posterior, List Blobs retorna o elemento TagCount para blobs com quaisquer tags. O elemento Tags aparece somente quando essa operação inclui o parâmetro include={tags}. Esses elementos não aparecem se não houver tags no blob.

Para a versão 2019-12-12 e posterior, List Blobs retorna o elemento Sealed para blobs de acréscimo. O elemento Sealed aparece somente quando o blob de apêndice foi selado. Esses elementos não aparecerão se o blob de apêndice não estiver lacrado.

Para a versão 2020-02-10 e posterior, List Blobs retorna o elemento LastAccessTime. O elemento mostra quando os dados do blob foram acessados pela última vez, de acordo com a política de rastreamento do último tempo de acesso da conta de armazenamento. O elemento não será retornado se a conta de armazenamento não tiver essa política ou se a política estiver desabilitada. Para obter informações sobre como definir a política de controle do último tempo de acesso da conta, consulte o Blob Service API. O elemento LastAccessTime não rastreia a última vez em que os metadados do blob são acessados.

Para a versão 2020-06-12 e posterior, List Blobs retorna os elementos ImmutabilityPolicyUntilDate e ImmutabilityPolicyMode, quando esta operação inclui o parâmetro include={immutabilitypolicy}.

Para a versão 2020-06-12 e posterior, List Blobs retorna o elemento LegalHold, quando esta operação inclui o parâmetro include={legalhold}.

Para a versão 2020-06-12 e posterior, para contas com um namespace hierárquico habilitado, List Blobs retorna os elementos Owner, Group, Permissionse Acl. A solicitação deve conter o parâmetro include={permissions}. Observe que o elemento Acl é uma lista combinada de listas de acesso e controle de acesso padrão que foram definidas no arquivo ou diretório.

Para a versão 2020-06-12 e posterior, para contas com um namespace hierárquico habilitado, List Blobs com um delimitador retorna o elemento Properties no elemento BlobPrefix. Isso corresponde às propriedades no diretório.

Para a versão 2020-08-04 e posterior, para contas com um namespace hierárquico habilitado, List Blobs retorna o elemento DeletionId para blobs excluídos. DeletionId é um identificador de 64 bits não assinado. O elemento identifica exclusivamente um caminho excluído suavemente, para distingui-lo de outros blobs excluídos com o mesmo caminho.

Para a versão 2020-10-02 e posterior, para contas com um namespace hierárquico habilitado, List Blobs retorna o elemento de propriedade ResourceType para o caminho. Isso pode ser file ou directory.

Para a versão 2021-02-12 e posterior, List Blobs codificará percentualmente (por RFC 2396) todos os BlobName ou BlobPrefixName valores de elementos. Especificamente, ele fará isso para os valores que contêm caracteres que não são válidos em XML (U + FFFE ou U + FFFF). Se codificado, o elemento Name incluirá um atributo Encoded=true. Observe que isso ocorre apenas para os valores de elemento Name que contêm os caracteres inválidos em XML, não para os elementos Name restantes na resposta.

Para a versão 2021-06-08 e posterior, para contas com um namespace hierárquico habilitado, List Blobs retorna o elemento Placeholder properties. Ele retorna esse elemento no elemento BlobPrefix para diretórios de espaço reservado, ao listar blobs excluídos com um delimitador. Esses diretórios de espaço reservado existem para facilitar a navegação para blobs excluídos por software.

Para a versão 2021-06-08 e posterior, para contas com um namespace hierárquico habilitado, List Blobs retorna o elemento EncryptionContext. Se o valor da propriedade de contexto de criptografia estiver definido, ele retornará o valor definido.

Para a versão 2020-02-10 e posterior, para contas com um namespace hierárquico habilitado, List Blobs retorna o elemento Expiry-Time para blobs excluídos. Expiry-Time é o momento em que o arquivo expirará e é retornado para o arquivo se a expiração estiver definida no mesmo.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="http://myaccount.blob.core.windows.net/"  ContainerName="mycontainer">  
  <Prefix>string-value</Prefix>  
  <Marker>string-value</Marker>  
  <MaxResults>int-value</MaxResults>  
  <Delimiter>string-value</Delimiter>  
  <Blobs>  
    <Blob>  
      <Name>blob-name</name>  
      <Snapshot>date-time-value</Snapshot>  
      <VersionId>date-time-vlue</VersionId>
      <IsCurrentVersion>true</IsCurrentVersion>
      <Deleted>true</Deleted>
      <Properties> 
        <Creation-Time>date-time-value</Creation-Time>
        <Last-Modified>date-time-value</Last-Modified>  
        <Etag>etag</Etag>
        <Owner>owner user id</Owner>
        <Group>owning group id</Group>
        <Permissions>permission string</Permissions>
        <Acl>access control list</Acl>
        <ResourceType>file | directory</ResourceType>
        <Placeholder>true</Placeholder>
        <Content-Length>size-in-bytes</Content-Length>  
        <Content-Type>blob-content-type</Content-Type>  
        <Content-Encoding />  
        <Content-Language />  
        <Content-MD5 />  
        <Cache-Control />  
        <x-ms-blob-sequence-number>sequence-number</x-ms-blob-sequence-number>  
        <BlobType>BlockBlob|PageBlob|AppendBlob</BlobType>  
        <AccessTier>tier</AccessTier>  
        <LeaseStatus>locked|unlocked</LeaseStatus>  
        <LeaseState>available | leased | expired | breaking | broken</LeaseState>  
        <LeaseDuration>infinite | fixed</LeaseDuration>  
        <CopyId>id</CopyId>  
        <CopyStatus>pending | success | aborted | failed </CopyStatus>  
        <CopySource>source url</CopySource>  
        <CopyProgress>bytes copied/bytes total</CopyProgress>  
        <CopyCompletionTime>datetime</CopyCompletionTime>  
        <CopyStatusDescription>error string</CopyStatusDescription>  
        <ServerEncrypted>true</ServerEncrypted> 
        <CustomerProvidedKeySha256>encryption-key-sha256</CustomerProvidedKeySha256>
        <EncryptionContext>encryption-context<EncryptionContext>
        <EncryptionScope>encryption-scope-name</EncryptionScope>
        <IncrementalCopy>true</IncrementalCopy>
        <AccessTierInferred>true</AccessTierInferred>
        <AccessTierChangeTime>datetime</AccessTierChangeTime>
        <DeletedTime>datetime</DeletedTime>
        <RemainingRetentionDays>no-of-days</RemainingRetentionDays>
        <TagCount>number of tags between 1 to 10</TagCount>
        <RehydratePriority>rehydrate priority</RehydratePriority>
        <Expiry-Time>date-time-value</Expiry-Time>
      </Properties>  
      <Metadata>     
        <Name>value</Name>  
      </Metadata>  
      <Tags>
          <TagSet>
              <Tag>
                  <Key>TagName</Key>
                  <Value>TagValue</Value>
              </Tag>
          </TagSet>
      </Tags>
      <OrMetadata />
    </Blob>  
    <BlobPrefix>  
      <Name>blob-prefix</Name>  
    </BlobPrefix>  
  </Blobs>  
  <NextMarker />  
</EnumerationResults>

Resposta da amostra

Consulte Enumerando recursos de blob para obter uma resposta de exemplo.

Autorização

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

Importante

A Microsoft recomenda o uso do Microsoft Entra ID com identidades gerenciadas para autorizar solicitações ao Armazenamento do Azure. O Microsoft Entra ID oferece 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 da ID do Microsoft Entra para autorizar solicitações de dados de blob. Com o Microsoft Entra ID, você pode usar o controle de acesso baseado em função do Azure (Azure RBAC) 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 pelo Microsoft Entra ID para retornar um token OAuth 2.0. O token pode ser usado para autorizar uma solicitação no serviço Blob.

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

Permissões

Abaixo estão listadas a ação RBAC necessária para que um usuário, grupo, identidade gerenciada ou entidade de serviço do Microsoft Entra chame a operação List Blobs e a função interna menos privilegiada do RBAC do Azure que inclui essa ação:

Se especificar include=tags:

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

Comentários

Propriedades de blob na resposta

Se você solicitou que blobs não confirmados fossem incluídos na enumeração, observe que algumas propriedades não são definidas até que o blob seja confirmado. Algumas propriedades podem não ser retornadas na resposta.

O elemento x-ms-blob-sequence-number só é retornado para blobs de página.

O elemento OrMetadata só é retornado para blobs de bloco.

Para blobs de página, o valor retornado no elemento Content-Length corresponde ao valor do cabeçalho x-ms-blob-content-length do blob.

O elemento Content-MD5 aparece no corpo da resposta, somente se tiver sido definido no blob usando a versão 2009-09-19 ou posterior. Você pode definir a propriedade Content-MD5 quando o blob é criado ou chamando set Blob Properties. Na versão 2012-02-12 e posterior, Put Blob define o valor MD5 de um blob de bloco, mesmo quando a solicitação de Put Blob não inclui um cabeçalho MD5.

Metadados na resposta

O elemento Metadata estará presente somente se o parâmetro include=metadata tiver sido especificado no URI. Dentro do elemento Metadata, o valor de cada par nome-valor é listado dentro de um elemento correspondente ao nome do par.

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 desta versão, todos os nomes de metadados devem aderir às convenções de nomenclatura para identificadores C#.

Se um par nome-valor de metadados violar essas restrições de nomenclatura, o corpo da resposta indicará o nome problemático dentro de um elemento x-ms-invalid-name. O fragmento XML a seguir mostra isso:

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

Tags na resposta

O elemento Tags estará presente somente se o parâmetro include=tags tiver sido especificado no URI e se houver tags no blob. Dentro do elemento TagSet, até 10 elementos Tag são retornados, cada um contendo o key e value das tags de índice de blob definidas pelo usuário. A ordenação das tags não é garantida na resposta.

Os elementos Tags e TagCount não serão retornados se não houver tags no blob.

O serviço de armazenamento mantém uma forte consistência entre um blob e suas tags, mas o índice secundário acaba sendo consistente. As tags podem ser visíveis em uma resposta a List Blobs antes de serem visíveis para Find Blobs by Tags operações.

Instantâneos na resposta

Os instantâneos são listados na resposta somente se o parâmetro include=snapshots tiver sido especificado no URI. Os instantâneos listados na resposta não incluem o elemento LeaseStatus, porque os instantâneos não podem ter concessões ativas.

Usando a versão de serviço 2021-06-08 e superior, você pode chamar List Blobs com um delimitador e incluir instantâneos na enumeração. Para versões de serviço anteriores a 2021-06-08, uma solicitação que inclui ambos retorna um erro InvalidQueryParameter (código de status HTTP 400 – Solicitação incorreta).

Blobs não confirmados na resposta

Os blobs não confirmados são listados na resposta somente se o parâmetro include=uncommittedblobs tiver sido especificado no URI. Os blobs não confirmados listados na resposta não incluem nenhum dos seguintes elementos:

  • Last-Modified

  • Etag

  • Content-Type

  • Content-Encoding

  • Content-Language

  • Content-MD5

  • Cache-Control

  • Metadata

Blobs excluídos na resposta

Os blobs excluídos serão listados na resposta somente se o parâmetro include=deleted tiver sido especificado no URI. Os blobs excluídos listados na resposta não incluem os elementos Lease, porque os blobs excluídos não podem ter concessões ativas.

Os instantâneos excluídos são incluídos na resposta da lista se include=deleted,snapshot foi especificado no URI.

Metadados de replicação de objeto na resposta

O elemento OrMetadata está presente quando uma política de replicação de objeto foi avaliada em um blob e a chamada de List Blobs foi feita usando a versão 2019-12-12 ou posterior. Dentro do elemento OrMetadata, o valor de cada par nome-valor é listado dentro de um elemento correspondente ao nome do par. O formato do nome é or-{policy-id}_{rule-id}, onde {policy-id} é um GUID que representa o identificador da política de replicação de objeto na conta de armazenamento. {rule-id} é um GUID que representa o identificador de regra no contêiner de armazenamento. Os valores válidos são complete ou failed.

  
…  
<OrMetadata>  
  <or-e524bba7-4323-4b93-91f8-d09d5d0b7057_d86c51de-ef02-4264-bdcf-dcd389a6c7ac>complete</or-e524bba7-4323-4b93-91f8-d09d5d0b7057_d86c51de-ef02-4264-bdcf-dcd389a6c7ac>  
  <or-2b302b5d-fcd5-44d6-a5ed-455bf27e17ea_4a398ff5-2a89-4090-879b-10248f23428e>failed</or-2b302b5d-fcd5-44d6-a5ed-455bf27e17ea_4a398ff5-2a89-4090-879b-10248f23428e>  
</OrMetadata>  
…

Política de imutabilidade na resposta

Os elementos ImmutabilityPolicyUntilDate e ImmutabilityPolicyMode estarão presentes somente se o parâmetro include=immutabilitypolicy tiver sido especificado no URI.

<Properties> 
   <ImmutabilityPolicyUntilDate>date-time-value</ImmutabilityPolicyUntilDate>   
   <ImmutabilityPolicyMode>unlocked | locked </ImmutabilityPolicyMode>  
</Properties>

O elemento LegalHold estará presente somente se o parâmetro include=legalhold tiver sido especificado no URI.

<Properties> 
  <LegalHold>true | false </LegalHold>  
</Properties>

Retornando conjuntos de resultados usando um valor de marcador

Se você especificar um valor para o parâmetro maxresults e o número de blobs a serem retornados exceder esse valor ou exceder o valor padrão para maxresults, o corpo da resposta conterá um elemento NextMarker. Este elemento indica o próximo blob a ser retornado em uma solicitação subsequente. Em certos casos, o serviço pode retornar o elemento NextMarker mesmo que o número de resultados retornados seja menor do que o valor de maxresults.

Para retornar o próximo conjunto de itens, especifique o valor de NextMarker como o parâmetro de marcador no URI para a solicitação subsequente. Note que o valor de NextMarker deve ser tratado como opaco.

Usando um delimitador para atravessar o namespace blob

O parâmetro delimiter permite que o chamador percorra o namespace blob usando um delimitador configurado pelo usuário. Dessa forma, você pode percorrer uma hierarquia virtual de blobs como se fosse um sistema de arquivos. O delimitador pode ser um único caractere ou uma cadeia de caracteres.

Quando a solicitação inclui esse parâmetro, a operação retorna um elemento BlobPrefix. O elemento BlobPrefix é retornado no lugar de todos os blobs com nomes que começam com a mesma substring, até a aparência do caractere delimitador. O valor do elemento BlobPrefix é substring+delimiter, onde substring é a substring comum que inicia um ou mais nomes de blob e delimitador é o valor do parâmetro delimiter.

Você pode usar o valor de BlobPrefix para fazer uma chamada subsequente para listar os blobs que começam com esse prefixo. Para fazer isso, especifique o valor de BlobPrefix para o parâmetro prefix no URI da solicitação.

Observe que cada elemento BlobPrefix retornado conta para o resultado máximo, assim como cada elemento Blob.

Os blobs são listados em ordem alfabética no corpo da resposta, com letras maiúsculas listadas primeiro.

Erros de cópia na Descrição do Status da Cópia

CopyStatusDescription contém mais informações sobre o Copy Blob falha.

  • Quando uma tentativa de cópia falha, CopyStatus é definido como pending se o Armazenamento de Blob ainda estiver tentando novamente a operação. O texto CopyStatusDescription descreve a falha que pode ter ocorrido durante a última tentativa de cópia.

  • Quando CopyStatus está definido como failed, o texto CopyStatusDescription descreve o erro que causou a falha da operação de cópia.

A tabela a seguir descreve os campos de cada CopyStatusDescription valor.

Componente Descrição
Código de status HTTP Inteiro padrão de três dígitos especificando a falha.
Código de erro Palavra-chave que descreve o erro. Ele é fornecido pelo Azure no elemento><ErrorCode. Se nenhum elemento <ErrorCode> for exibido, o serviço retornará uma palavra-chave que contém texto de erro padrão associado ao código de status HTTP de três dígitos na especificação HTTP. Para obter mais informações, consulte códigos de erro comuns da API REST.
Informação Descrição detalhada da falha, entre aspas.

A tabela a seguir descreve os valores de CopyStatus e CopyStatusDescription de cenários de falha comuns.

Importante

O texto da descrição mostrado aqui pode ser alterado sem aviso, mesmo sem uma alteração de versão. Não confie na correspondência exata deste texto.

Cenário Valor de status da cópia Valor da descrição do status da cópia
Operação de cópia concluída com êxito. sucesso vazio
O usuário anulou a operação de cópia antes que ela fosse concluída. abortado vazio
Ocorreu uma falha ao ler a partir do blob de origem durante uma operação de cópia. A operação será repetida. pendente 502 BadGateway "Encontrou um erro retryable ao ler a fonte. Vai tentar novamente. Tempo de falha: <tempo>"
Ocorreu uma falha ao gravar no blob de destino de uma operação de cópia. A operação será repetida. pendente 500 InternalServerError "Encontrou um erro retryable. Vai tentar novamente. Tempo de falha: <tempo>"
Ocorreu uma falha irrecuperável ao ler a partir do blob de origem de uma operação de cópia. falhou 404 ResourceNotFound "Falha na cópia ao ler a fonte." Quando o serviço relata esse erro subjacente, ele retorna ResourceNotFound no elemento><ErrorCode. Se nenhum elemento <ErrorCode> aparecer na resposta, uma representação de cadeia de caracteres padrão do status HTTP, como NotFound, será exibida.
O período de tempo limite que limita todas as operações de cópia decorrido. (Atualmente, o período de tempo limite é de duas semanas.) falhou 500 OperationCancelled "A cópia excedeu o tempo máximo permitido."
A operação de cópia falhou com muita frequência ao ler a partir da fonte e não atingiu uma proporção mínima de tentativas para sucessos. (Este tempo limite impede a repetição de uma fonte muito pobre durante duas semanas antes de falhar). falhou 500 OperationCancelled "A cópia falhou ao ler a fonte."

Faturação

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

Funcionamento Tipo de conta de armazenamento Categoria de faturação
Listar Blobs Blob de bloco premium
Padrão de uso geral v2
Padrão de uso geral v1		 Listar e criar operações de contêiner

Para saber mais sobre os preços para a categoria de cobrança especificada, consulte de preços do armazenamento de Blob do Azure .

Ver também

Códigos de status e de erro
códigos de erro de armazenamento de Blob