Listar Blobs
A List Blobs
operação retorna uma lista dos blobs no contêiner especificado.
Solicitação
Você pode construir a solicitação da List Blobs
seguinte maneira. HTTPS é recomendado. Substitua myaccount pelo nome da sua conta de armazenamento.
Método | URI da solicitação | Versão HTTP |
---|---|---|
GET |
https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list |
HTTP/1.1 |
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 Armazenamento de Blobs do Azure porta como 127.0.0.1:10000
, seguido pelo nome da conta de armazenamento emulado.
Método | URI da solicitação | Versão HTTP |
---|---|---|
GET |
http://127.0.0.1:10000/devstoreaccount1/mycontainer?restype=container&comp=list |
HTTP/1.1 |
Para obter mais informações, consulte Usar o emulador do Azurite para desenvolvimento local do Armazenamento do Azure.
Parâmetros do 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 folder1/folder2/readme/readmefile.txt de prefixo . Um erro será exibido se qualquer subpasta contiver um arquivo chamado readme . |
delimiter |
Opcional. Quando a solicitação inclui esse parâmetro, a operação retorna um BlobPrefix elemento no corpo da resposta. Esse elemento atua como um espaço reservado para todos os blobs com nomes que começam com a mesma subcadeia de caracteres, 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 na lista. A operação retornará um valor de marcador dentro do corpo de 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 ao cliente. |
maxresults |
Opcional. Especifica o número máximo de blobs a ser retornado, inclusive todos os elementos BlobPrefix . Se a solicitação não especificar maxresults ou 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 NextMarker elemento de resposta. Em determinados casos, o serviço pode retornar menos resultados do que o especificado por maxresults e também retornar um token de continuação.A configuração de maxresults com um valor menor ou igual a zero resulta em um 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 ao mais novo na resposta.- metadata : especifica que os metadados de blob sejam retornados na resposta.- uncommittedblobs : especifica que os blobs para os quais 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 posterior. Especifica que os metadados relacionados a qualquer operação atual ou anterior de Copy Blob devem ser incluídos na resposta.- deleted : versão 2017-07-29 e posterior. Especifica que os blobs excluídos temporariamente devem ser incluídos na resposta. - tags : versão 2019-12-12 e posterior. Especifica que as marcas 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 excluídos permanentemente aparecem na resposta até que sejam processados pela coleta de lixo. Use a marca \<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. Com suporte 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 na URL ("%82"). |
showonly={deleted,files,directories} |
Opcional. Especifica um desses 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 de forma reversível. Observe que não há suporte para fallback de autorização de ACL POSIX para listar blobs excluídos suavemente. Se include=deleted também for especificado, a solicitação falhará com a Solicitação Inválida (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 Configurando tempos limite para operações de Armazenamento de Blobs. |
Cabeçalhos da solicitação
A tabela a seguir descreve os cabeçalhos de solicitação obrigatórios e opcionais.
Cabeçalho da solicitação | Descrição |
---|---|
Authorization |
Obrigatórios. Especifica o esquema de autorização, o nome da conta e a assinatura. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure. |
Date ou x-ms-date |
Obrigatórios. Especifica o UTC (Tempo Universal Coordenado) para a solicitação. Para saber mais, confira Autorizar solicitações para o Armazenamento do Azure. |
x-ms-version |
Necessário para todas as solicitações autorizadas e opcional para solicitações anônimas. Especifica a versão da operação a ser usada para esta solicitação. Para obter mais informações, consulte Controle de versão para os Serviços de Armazenamento do Azure. |
x-ms-client-request-id |
Opcional. Fornece um valor opaco gerado pelo cliente com um limite de caracteres KiB (1 kibibyte) que é registrado nos logs quando o registro em log é configurado. É altamente recomendável que você use esse cabeçalho para correlacionar atividades do lado do cliente com solicitações recebidas pelo servidor. Para obter mais informações, consulte Monitorar Armazenamento de Blobs do Azure. |
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> serão transformados de IDs de objeto Microsoft Entra para nomes de entidade de usuário. Se false , os valores serão retornados como Microsoft Entra IDs de objeto. O valor padrão é false . Observe que as IDs de objeto de grupo e aplicativo não são convertidas porque não têm nomes amigáveis exclusivos. |
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 Códigos de status e de erro.
Cabeçalhos de resposta
A resposta para esta operação inclui os cabeçalhos a seguir. A resposta também 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 de resposta | Descrição |
---|---|
Content-Type |
Especifica o formato em que os resultados são retornados. Atualmente, esse valor é application/xml . |
x-ms-request-id |
Esse cabeçalho identifica exclusivamente a solicitação que foi feita e pode ser usado para solucionar problemas da solicitação. Para obter mais informações, consulte Solução de problemas de operações de API. |
x-ms-version |
Indica a versão do Armazenamento de Blobs usada para executar a solicitação. Esse cabeçalho é retornado para solicitações feitas usando a versão 2009-09-19 e posterior. Esse cabeçalho também será retornado para solicitações anônimas, sem uma versão especificada, se o contêiner tiver sido marcado para acesso público usando a versão 2009-09-19 do Armazenamento de Blobs. |
Date |
Um valor de data/hora UTC que indica a hora em que a resposta foi iniciada. O serviço gera esse valor. |
x-ms-client-request-id |
Você pode usar esse cabeçalho para solucionar problemas de solicitações e respostas correspondentes. O valor desse cabeçalho é igual ao valor do x-ms-client-request-id cabeçalho, se ele estiver presente na solicitação. O valor é no máximo 1024 caracteres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente na solicitação, esse cabeçalho não estará presente na resposta. |
Corpo da resposta
O formato da resposta XML é mostrado a seguir.
Observe que os elementos Prefix
, Marker
, MaxResults
e Delimiter
somente estarão presentes se tiverem sido especificados no URI de solicitação. O NextMarker
elemento terá um valor somente se os resultados da lista não estiverem concluídos.
Os instantâneos, os metadados de blob, e os blobs não confirmadas serão incluídos na resposta somente se forem especificados com o parâmetro include
no URI de solicitação.
Na versão 2009-09-19 e posterior, as propriedades do blob são encapsuladas dentro de um Properties
elemento .
A partir da versão 2009-09-19, List Blobs
retorna os seguintes elementos renomeados no corpo de resposta:
Last-Modified
(anteriormenteLastModified
)Content-Length
(anteriormenteSize
)Content-Type
(anteriormenteContentType
)Content-Encoding
(anteriormenteContentEncoding
)Content-Language
(anteriormenteContentLanguage
)
O Content-MD5
elemento 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 Content-MD5
valor quando você carrega 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 Content-MD5
valor ao criar o blob ou chamando as operações Colocar 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 inclua blobs de acréscimo. O serviço retornará status código 409 (Conflito) se o resultado da listagem contiver um blob de acréscimo.
LeaseState
e LeaseDuration
aparecem somente na versão 2012-02-12 e posterior.
CopyId
, CopyStatus
, CopySource
, CopyProgress
, CopyCompletionTime
e CopyStatusDescription
aparecem somente na versão 2012-02-12 e mais recentes, 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 Copy Blob
operação. Os elementos não aparecerão se esse blob tiver sido modificado após uma operação concluída Copy Blob
, usando Set Blob Properties
, Put Blob
ou 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 EnumerationResults
elemento contém um ServiceEndpoint
atributo que especifica o ponto de extremidade do blob. Esse elemento também contém um ContainerName
campo que especifica o nome do contêiner. Em versões anteriores, esses dois atributos foram combinados no ContainerName
campo . Também na versão 2013-08-15 e posterior, o Url
elemento 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 ServerEncrypted
elemento . Esse elemento será definido true
como se os metadados do blob e do aplicativo forem completamente criptografados e false
de outra forma.
Para a versão 2016-05-31 e posterior, List Blobs
retorna o IncrementalCopy
elemento 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
retorna o AccessTier
elemento se uma camada de acesso tiver sido definida explicitamente. Para obter uma lista de 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
, Cool
e Archive
. Se o blob estiver no estado pendente de reidratação, ArchiveStatus
o elemento será retornado com um dos valores válidos (rehydrate-pending-to-hot
, rehydrate-pending-to-cool
ou rehydrate-pending-to-cold
). Para obter informações detalhadas sobre camadas 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 AccessTierInferred
elemento 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 de 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 da conta.
Para a versão 2017-04-17 e posterior, List Blobs
retorna o AccessTierChangeTime
elemento 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
, DeletedTime
e RemainingRetentionDays
aparecem quando essa operação inclui o include={deleted}
parâmetro . 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 DELETE
operação, quando o recurso de exclusão reversível foi habilitado. O Deleted
elemento é definido true
como para blobs e instantâneos que são excluídos temporariamente. Deleted-Time
corresponde à hora em que o blob foi excluído. RemainingRetentionDays
indica o número de dias após os quais um blob excluído temporariamente é 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
retorna o CustomerProvidedKeySha256
elemento 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 include={metadata}
parâmetro e houver metadados de aplicativo presentes em um blob criptografado com uma chave fornecida pelo cliente, o Metadata
elemento terá um Encrypted="true"
atributo. Esse atributo indica que o blob tem metadados que não podem ser descriptografados como parte da List Blobs
operação. Para acessar os metadados desses blobs, chame Obter Propriedades do 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 EncryptionScope
elemento 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 include={metadata}
parâmetro , os metadados do aplicativo no blob serão descriptografados de forma transparente e disponíveis no Metadata
elemento .
Para a versão 2019-12-12 e posterior, List Blobs
retorna o RehydratePriority
elemento em contas de Armazenamento de Blobs ou de uso geral v2, se o objeto estiver no rehydrate pending
estado. Os valores válidos são High
e Standard
.
Para a versão 2019-12-12 e posterior, List Blobs
retorna o VersionId
elemento 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 IsCurrentVersion
elemento 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 e geradas automaticamente.
Para a versão 2019-12-12 e posterior, List Blobs
retorna o TagCount
elemento para blobs com quaisquer marcas. O Tags
elemento aparece somente quando essa operação inclui o include={tags}
parâmetro . 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 Sealed
elemento para blobs de acréscimo. O Sealed
elemento aparece somente quando o blob de acréscimo foi selado. Esses elementos não aparecerão se o blob de acréscimo não estiver selado.
Para a versão 2020-02-10 e posterior, List Blobs
retorna o LastAccessTime
elemento . 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 LastAccessTime
elemento 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 ImmutabilityPolicyUntilDate
elementos e ImmutabilityPolicyMode
, quando essa operação inclui o include={immutabilitypolicy}
parâmetro .
Para a versão 2020-06-12 e posterior, List Blobs
retorna o LegalHold
elemento quando essa operação inclui o include={legalhold}
parâmetro .
Para a versão 2020-06-12 e posterior, para contas com um namespace hierárquico habilitado, List Blobs
retorna os Owner
elementos , Group
, e .Acl
Permissions
A solicitação deve conter o include={permissions}
parâmetro . Observe que o Acl
elemento é 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 Properties
elemento no BlobPrefix
elemento . 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 DeletionId
elemento 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 ResourceType
elemento de propriedade do caminho. Isso pode ser file
ou directory
.
Para a versão 2021-02-12 e posterior, List Blobs
codificará por cento (por RFC 2396) todos osName
Blob
valores de elemento ou BlobPrefix
Name
. 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 Name
elemento incluirá um Encoded=true
atributo . Observe que isso ocorre apenas para os valores de Name
elemento que contêm os caracteres inválidos em XML, não os elementos restantes Name
na resposta.
Para a versão 2021-06-08 e posterior, para contas com um namespace hierárquico habilitado, List Blobs
retorna o Placeholder
elemento properties. Ele retorna esse elemento no elemento para diretórios BlobPrefix
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 temporariamente.
Para a versão 2021-06-08 e posterior, para contas com um namespace hierárquico habilitado, List Blobs
retorna o EncryptionContext
elemento . 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 Expiry-Time
elemento para blobs excluídos. Expiry-Time
é a hora em que o arquivo expirará e será retornado para o arquivo se a expiração for definida na mesma.
<?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 List Blobs
operação, conforme descrito abaixo.
O Armazenamento do Azure dá suporte ao uso de Microsoft Entra ID para autorizar solicitações para dados de blob. Com Microsoft Entra ID, você pode usar o RBAC (controle de acesso baseado em função) do Azure para conceder permissões a uma entidade de segurança. A entidade de segurança pode ser um usuário, grupo, entidade de serviço de aplicativo ou identidade gerenciada do Azure. A entidade de segurança é autenticada por Microsoft Entra ID para retornar um token OAuth 2.0. Em seguida, o token pode ser usado para autorizar uma solicitação no serviço de Blob.
Para saber mais sobre a autorização usando Microsoft Entra ID, consulte Autorizar o acesso a blobs usando Microsoft Entra ID.
Permissões
Veja abaixo a ação RBAC necessária para que um usuário, grupo ou entidade de serviço Microsoft Entra chame a List Blobs
operação e a função RBAC interna do Azure com menos privilégios que inclua esta ação:
- Ação RBAC do Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
- Função interna com privilégios mínimos:Leitor de Dados do Blob de Armazenamento
Para saber mais sobre como atribuir funções usando o RBAC do Azure, confira Atribuir uma função do Azure para acesso aos dados de blob.
Comentários
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 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
somente é retornado para blobs de página.
O OrMetadata
elemento só é retornado 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 Content-MD5
elemento 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 Content-MD5
propriedade 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
estará presente apenas se o parâmetro include=metadata
tiver sido especificado no URI. No elemento Metadata
, o valor de cada par de nome-valor é listado em 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 dentro de um x-ms-invalid-name
elemento. O fragmento XML a seguir 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 Tags
elemento estará presente somente se o include=tags
parâmetro tiver sido especificado no URI e se houver marcas no blob. Dentro do TagSet
elemento , até 10 Tag
elementos são retornados, cada um contendo o key
e value
as marcas de índice de blob definidas pelo usuário. A ordenação de marcas não é garantida na resposta.
Os Tags
elementos 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 Find Blobs by Tags
as operações.
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 LeaseStatus
elemento , pois 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 ambas retorna um erro InvalidQueryParameter (HTTP status código 400 – Solicitação Incorreta).
Blobs não confirmados na resposta
Os blobs não confirmados serã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 include=deleted
parâmetro tiver sido especificado no URI. Os blobs excluídos listados na resposta não incluem os elementos Lease , pois os blobs excluídos não podem ter concessões ativas.
Os instantâneos excluídos serão incluídos na resposta da lista se include=deleted,snapshot
tiver sido especificado no URI.
Metadados de replicação de objeto na resposta
O OrMetadata
elemento está presente quando uma política de replicação de objeto foi avaliada em um blob e a chamada foi feita usando a List Blobs
versão 2019-12-12 ou posterior. No elemento OrMetadata
, o valor de cada par de nome-valor é listado em um elemento correspondente ao nome do par. O formato do nome é or-{policy-id}_{rule-id}
, em {policy-id}
que é 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 ImmutabilityPolicyUntilDate
elementos e ImmutabilityPolicyMode
estarão presentes somente se o include=immutabilitypolicy
parâmetro tiver sido especificado no URI.
<Properties>
<ImmutabilityPolicyUntilDate>date-time-value</ImmutabilityPolicyUntilDate>
<ImmutabilityPolicyMode>unlocked | locked </ImmutabilityPolicyMode>
</Properties>
Retenção legal na resposta
O elemento LegalHold
estará presente apenas 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 maxresults
parâmetro 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 NextMarker
elemento . Esse elemento indica o próximo blob a ser retornado em uma solicitação subsequente. Em determinados casos, o serviço pode retornar o NextMarker
elemento 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 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 do blob usando um delimitador configurado pelo usuário. Desse modo, você pode atravessar 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, ela retorna um elemento BlobPrefix
. O BlobPrefix
elemento é 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 BlobPrefix
elemento é substring+delimiter, em que substring é a subcadeia de caracteres comum que inicia um ou mais nomes de blob e delimitador é o valor do delimiter
parâmetro .
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 prefix
parâmetro no URI de 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 de resposta, com as letras maiúsculas primeiro.
Copiar erros na Descrição do Status da Cópia
CopyStatusDescription
contém mais informações sobre a falha Copy Blob
.
Quando uma tentativa de cópia falhar,
CopyStatus
será definidopending
como se o Armazenamento de Blobs ainda estiver repetindo a operação. OCopyStatusDescription
texto descreve a falha que pode ter ocorrido durante a última tentativa de cópia.Quando
CopyStatus
é definido comofailed
, o textoCopyStatusDescription
descreve o erro que causou a falha na 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 do erro | Palavra-chave que descreve o erro. Ele é fornecido pelo Azure no <elemento ErrorCode> . Se nenhum <elemento ErrorCode> for exibido, o serviço retornará um palavra-chave que contém o texto de erro padrão associado ao código de status HTTP de três dígitos na especificação HTTP. Para saber mais, confira Códigos de erro comuns da API REST. |
Informações | Descrição detalhada da falha, entre aspas. |
A tabela a seguir descreve os valores CopyStatus
e CopyStatusDescription
de cenários de falha comuns.
Importante
O texto de descrição mostrado aqui pode ser alterado sem aviso, mesmo sem uma alteração de versão. Não confie em corresponder a esse texto exato.
Cenário | Valor do Status de Cópia | Valor da Descrição do Status de Cópia |
---|---|---|
Operação de cópia concluída com êxito. | sucesso | vazio |
O usuário anulou a operação de cópia antes de ser concluída. | aborted | vazio |
Ocorreu uma falha ao ler do blob de origem durante uma operação de cópia. A operação será repetida. | pending | 502 BadGateway "Encontrado um erro reproduzível ao ler a origem. Uma nova tentativa será realizada. Hora da falha: <tempo>" |
Ocorreu uma falha ao gravar no blob de destino de uma operação de cópia. A operação será repetida. | pending | 500 InternalServerError "Encontrado um erro reproduzível. Uma nova tentativa será realizada. Hora da falha: <tempo>" |
Falha irrecuperável durante a leitura do blob de origem de uma operação de cópia. | falhou | 404 ResourceNotFound "Falha na cópia ao ler a origem". 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 tempo limite que limita todas as operações de cópia expirou. (Atualmente, o período de tempo limite é de duas semanas.) | falhou | 500 OperationCancelled "A cópia excedeu o tempo máximo permitido.” |
Ocorreram falhas muito frequentes na leitura da origem, e uma proporção mínima de tentativas e êxitos não foi atendida. (Esse tempo limite impede a repetição de uma fonte muito ruim ao longo de duas semanas antes de falhar). | falhou | 500 OperationCancelled "Falha na cópia durante a leitura da origem.” |
Cobrança
As solicitações de preços podem ser originadas de clientes que usam APIs de Armazenamento de Blobs, diretamente por meio da API REST do Armazenamento de Blobs ou de uma biblioteca de clientes do Armazenamento do Azure. Essas solicitações acumulam encargos por transação. O tipo de transação afeta a forma como a conta é cobrada. Por exemplo, as transações de leitura se acumulam em uma categoria de cobrança diferente das transações de gravação. A tabela a seguir mostra a categoria de cobrança para List Blobs
solicitações com base no tipo de conta de armazenamento:
Operação | Tipo de conta de armazenamento | Categoria de cobrança |
---|---|---|
Listar Blobs | Blob de blocos Premium Uso geral v2 Standard Uso geral v1 Standard |
Listar e criar operações de contêiner |
Para saber mais sobre os preços da categoria de cobrança especificada, confira Preços Armazenamento de Blobs do Azure.
Confira também
Status e códigos de erro
Códigos de erro do Armazenamento de Blobs