Listar Blobs

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

Pedir

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

URI do serviço de armazenamento emulado

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

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

Parâmetros de URI

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

Cabeçalhos de solicitação

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

Corpo da solicitação

Nenhum.

Solicitação de exemplo

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 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 Status e códigos de erro.

Cabeçalhos de resposta

A resposta dessa operação inclui os cabeçalhos a seguir. 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 de protocolo HTTP/1.1 .

Corpo da resposta

O formato da resposta XML é o seguinte.

Observe que os elementos Prefix, Marker, MaxResultse Delimiter só estarão presentes se forem especificados no URI da solicitação. O elemento NextMarker tem um valor somente se os resultados da lista não estiverem concluídos.

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 em um elemento Properties.

A partir da versão 2009-09-19, List Blobs retorna os seguintes elementos renomeado 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 Blobs calcula o valor Content-MD5 ao carregar um blob usando Colocar Blob. O Armazenamento de Blobs não calcula isso quando você cria um blob usando Colocar Lista de Blocos. Você pode definir explicitamente o valor de ao criar o blob ou chamando as operações de Lista de Blocos ou Definir Propriedades de Blob.

Para versões de 2009-09-19 e posteriores, mas antes da versão 2015-02-21, você não pode chamar List Blobs em um contêiner que inclui blobs de acréscimo. O serviço retornará 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 essa 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 de 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 Copiar 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. Em versões anteriores, esses dois atributos foram 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 será definido como true se os metadados do blob e do aplicativo estiverem completamente criptografados e false caso contrário.

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

Para a versão 2017-04-17 e posterior, List Blobs retornará o elemento AccessTier se uma camada de acesso tiver sido definida explicitamente. Para obter uma lista das camadas de blob de páginas premium permitidas, consulte armazenamento premium de alto desempenho e discos gerenciados para VMs. Para contas do Armazenamento de Blobs ou de uso geral v2, os valores válidos são Hot, Coole Archive. Se o blob estiver no estado pendente de reidratar, 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 camada de blob de blocos, consulte camadas de armazenamento frequentes, esporádicas e de arquivos.

Para a versão 2017-04-17 e posterior, List Blobs retorna o elemento AccessTierInferred em contas do Armazenamento de Blobs ou de uso geral v2. Se o blob de blocos 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 só estará presente se a camada for inferida da propriedade da conta.

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

Para a versão 2017-07-29 e posterior, Deleted, DeletedTimee RemainingRetentionDays aparecem quando essa 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 excluídos com a operação de DELETE, quando o recurso de exclusão reversível foi habilitado. O elemento Deleted é definido como true para blobs e instantâneos que são excluídos suavemente. Deleted-Time corresponde à hora em que o blob foi excluído. RemainingRetentionDays indica o número de dias após o qual um blob de exclusão reversível é excluído permanentemente.

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

Para a versão 2019-02-02 e posterior, List Blobs retornará 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 de 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 retornará o elemento EncryptionScope se o blob for 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 disponíveis no elemento Metadata.

Para a versão 2019-12-12 e posterior, List Blobs retornará o elemento RehydratePriority no Armazenamento de Blobs ou contas 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 geradas automaticamente somente leitura.

Para a versão 2019-12-12 e posterior, List Blobs retorna o elemento TagCount para blobs com marcas. O elemento Tags aparece somente quando essa operação inclui o parâmetro include={tags}. Esses elementos não aparecerão se não houver marcas 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 acréscimo foi lacrado. Esses elementos não aparecerão se o blob de acréscimo 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 controle de tempo de acesso da última conta de armazenamento. O elemento não será retornado se a conta de armazenamento não tiver essa política ou a política estiver desabilitada. Para obter informações sobre como definir a política de controle de tempo de acesso da última conta, consulte a API do Serviço de Blob . O elemento LastAccessTime não acompanha 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 essa operação inclui o parâmetro include={immutabilitypolicy}.

Para a versão 2020-06-12 e posterior, List Blobs retorna o elemento LegalHold, quando essa 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 sem sinal de 64 bits. O elemento identifica exclusivamente um caminho de exclusão reversível, 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á percentual (por RFC 2396) todos os valores de elemento BlobName ou BlobPrefixName. 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 os elementos de 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 de propriedades Placeholder. 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 suavemente.

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 for 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 é a hora em que o arquivo expirará e será 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 de exemplo

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 de List Blobs, conforme descrito abaixo.

Observações

Propriedades de blob na resposta

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

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

O elemento OrMetadata é retornado apenas para blobs de blocos.

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 ele 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 Definir Propriedades de Blob. Na versão 2012-02-12 e posterior, Put Blob define o valor MD5 de um blob de blocos, mesmo quando a solicitação Put Blob não inclui um cabeçalho MD5.

Metadados na resposta

O elemento Metadata só estará presente 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 dessa 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 em um elemento x-ms-invalid-name. 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>  
…  
  

Marcas na resposta

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

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

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

Instantâneos na resposta

Os instantâneos serã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, pois os instantâneos não podem ter concessões ativas.

Usando o serviço versã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 ambas retorna um erro InvalidQueryParameter (código de status HTTP 400 – Solicitação Incorreta).

Blobs não confirmados na resposta

Blobs não confirmados são listados na resposta somente se o parâmetro include=uncommittedblobs foi especificado no URI. 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

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

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 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}, em que {policy-id} é um GUID que representa o identificador de 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 só estarão presentes se o parâmetro include=immutabilitypolicy tiver sido especificado no URI.

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

Retenção legal na resposta

O elemento LegalHold só estará presente 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. Esse elemento indica o próximo blob a ser retornado em uma solicitação subsequente. Em determinados casos, o serviço pode retornar o elemento NextMarker mesmo que o número de resultados retornados seja menor 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. Observe que o valor de NextMarker deve ser tratado como opaco.

Usando um delimitador para percorrer o namespace de blob

O parâmetro delimiter permite que o chamador percorra o namespace de 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 subcadeia de caracteres, até a aparência do caractere delimitador. O valor do elemento BlobPrefix é substring+delimitador, em que subcadeia de caracteres é a subcadeia de caracteres 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. Faça isso especificando 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 faz.

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

Copiar erros na Descrição do Status de Cópia

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

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

• Quando CopyStatus é 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 valor CopyStatusDescription.

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

Faturamento

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 solicitações List Blobs com base no tipo de conta de armazenamento:

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

Consulte também

status e códigos de erro
códigos de erro do Armazenamento de Blobs