Listar Blobs
A List Blobs
operação devolve uma lista dos blobs no contentor especificado.
Pedir
Pode construir o pedido da List Blobs
seguinte forma. É recomendado HTTPS. Substitua myaccount pelo nome da sua conta de armazenamento.
Método | URI do pedido | Versão HTTP |
---|---|---|
GET |
https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list |
HTTP/1.1 |
URI do serviço de armazenamento emulado
Quando fizer um pedido relativamente ao serviço de armazenamento emulado, especifique o nome do anfitrião do emulador e Armazenamento de Blobs do Azure porta como 127.0.0.1:10000
, seguido do nome da conta de armazenamento emulada.
Método | URI do pedido | Versão HTTP |
---|---|---|
GET |
http://127.0.0.1:10000/devstoreaccount1/mycontainer?restype=container&comp=list |
HTTP/1.1 |
Para obter mais informações, veja Use Azurite emulator for local Azure Storage development (Utilizar o emulador do Azurite para o desenvolvimento do Armazenamento do Azure local).
Parâmetros do URI
Pode especificar os seguintes parâmetros adicionais no URI.
Parâmetro | Description |
---|---|
prefix |
Opcional. Filtra os resultados para devolver apenas blobs com nomes que começam com o prefixo especificado. Nas contas que têm um espaço de nomes hierárquico, ocorrerá um erro nos casos em que o nome de um ficheiro aparece no meio do caminho do prefixo. Por exemplo, pode tentar localizar blobs com o nome readmefile.txt através do caminho folder1/folder2/readme/readmefile.txt do prefixo . Será apresentado um erro se alguma subpasta contiver um ficheiro com o nome readme . |
delimiter |
Opcional. Quando o pedido inclui este parâmetro, a operação devolve um BlobPrefix elemento no corpo da resposta. Este elemento funciona como um marcador de posição para todos os blobs com nomes que começam com a mesma subcadeia, até ao aspeto do caráter delimitador. O delimitador pode ser um único caráter ou uma cadeia. |
marker |
Opcional. Um valor de cadeia que identifica a parte da lista a ser devolvida com a próxima operação de lista. A operação devolve um valor de marcador no corpo da resposta se a lista devolvida não tiver sido concluída. Em seguida, pode utilizar o valor do marcador numa chamada subsequente para pedir 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 devolver, incluindo todos os BlobPrefix elementos. Se o pedido não especificar maxresults ou especificar um valor superior a 5000, o servidor devolverá até 5000 itens. Se existirem resultados adicionais a devolver, o serviço devolve um token de continuação no NextMarker elemento de resposta. Em determinados casos, o serviço pode devolver menos resultados do que os especificados por maxresults e também devolver um token de continuação.Definir maxresults para um valor menor ou igual a zero resulta no código de resposta de erro 400 (Pedido Incorreto). |
include={snapshots,metadata,uncommittedblobs,copy,deleted,tags,versions, deletedwithversions,immutabilitypolicy,legalhold,permissions} |
Opcional. Especifica um ou mais conjuntos de dados a incluir 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 do blob são devolvidos na resposta.- uncommittedblobs : especifica que os blobs para os quais os blocos foram carregados, mas que não foram consolidados através da opção Colocar Lista de Blocos, serão incluídos na resposta.- copy : Versão 2012-02-12 e posterior. Especifica que os metadados relacionados com qualquer operação atual ou anterior Copy Blob devem ser incluídos na resposta.- deleted : Versão 2017-07-29 e posterior. Especifica que os blobs eliminados de forma recuperável devem ser incluídos na resposta. - tags : Versão 2019-12-12 e posterior. Especifica que as etiquetas de índice de blobs definidas pelo utilizador devem ser incluídas na resposta. - versions : Versão 2019-12-12 e posterior. Especifica que as versões dos blobs devem ser incluídas na enumeração.- deletedwithversions : Versão 2020-10-02 e posterior. Especifica que os blobs eliminados com quaisquer versões (ativas ou eliminadas) devem ser incluídos na resposta. Os itens que eliminou permanentemente aparecem na resposta até serem processados pela libertação da memória. Utilize a etiqueta \<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é à 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 espaço de nomes hierárquico ativado. Se um pedido incluir este parâmetro, o proprietário, o grupo, as permissões e a lista de controlo de acesso dos blobs ou diretórios listados serão incluídos na enumeração. Para especificar mais do que uma destas opções no URI, tem de separar cada opção com uma vírgula codificada por URL ("%82"). |
showonly={deleted,files,directories} |
Opcional. Especifica um destes conjuntos de dados a devolver na resposta: - deleted : opcional. Versão 2020-08-04 e posterior. Apenas para contas ativadas com espaço de nomes hierárquico. Quando um pedido inclui este parâmetro, a lista contém apenas blobs eliminados de forma recuperável. Tenha em atenção que a contingência da autorização da ACL POSIX não é suportada para listar blobs eliminados de forma recuperável. Se include=deleted também for especificado, o pedido falha com Pedido Incorreto (400).- files : opcional. Versão 2020-12-06 e posterior. Apenas para contas ativadas com espaço de nomes hierárquico. Quando um pedido inclui este parâmetro, a lista contém apenas ficheiros. - directories : opcional. Versão 2020-12-06 e posterior. Apenas para contas ativadas com espaço de nomes hierárquico. Quando um pedido inclui este parâmetro, a lista contém apenas diretórios. |
timeout |
Opcional. O timeout parâmetro é expresso em segundos. Para obter mais informações, veja Setting timeouts for Blob Storage operations (Definir tempos limite para operações de Armazenamento de Blobs). |
Cabeçalhos do pedido
A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.
Cabeçalho do pedido | Description |
---|---|
Authorization |
Obrigatório. Especifica o esquema de autorização, o nome da conta e a assinatura. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure. |
Date ou x-ms-date |
Obrigatório. Especifica a Hora Universal Coordenada (UTC) do pedido. Para obter mais informações, veja Autorizar pedidos para o Armazenamento do Azure. |
x-ms-version |
Necessário para todos os pedidos autorizados e opcional para pedidos anónimos. Especifica a versão da operação a utilizar para este pedido. Para obter mais informações, veja Controlo de versões dos serviços de Armazenamento do Azure. |
x-ms-client-request-id |
Opcional. Fornece um valor opaco gerado pelo cliente com um limite de carateres de 1 kibibyte (KiB) que é registado nos registos quando o registo é configurado. Recomendamos vivamente que utilize este cabeçalho para correlacionar as atividades do lado do cliente com os pedidos que o servidor recebe. Para obter mais informações, veja Monitorizar Armazenamento de Blobs do Azure. |
x-ms-upn |
Opcional. Válido apenas quando um espaço de nomes hierárquico está ativado para a conta e include=permissions é fornecido no pedido. Se true , os valores de identidade de utilizador devolvidos nos <campos Proprietário>, <Grupo> e <Acl> são transformados de Microsoft Entra IDs de objeto para nomes principais de utilizador. Se false , os valores são devolvidos como Microsoft Entra IDs de objeto. O valor predefinido é false . Tenha em atenção que os IDs de objetos de grupo e de aplicação não são traduzidos porque não têm nomes amigáveis exclusivos. |
Corpo do pedido
Nenhum.
Pedido de exemplo
Veja Enumerar recursos de blobs para um pedido de exemplo.
Resposta
A resposta inclui um código de estado HTTP, um conjunto de cabeçalhos de resposta e um corpo de resposta no formato XML.
Código de estado
Uma operação bem-sucedida devolve o código de estado 200 (OK). Para obter informações sobre códigos de estado, veja Códigos de estado e de erro.
Cabeçalhos de resposta
A resposta para esta operação inclui os seguintes cabeçalhos. A resposta também 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 no qual os resultados são devolvidos. Atualmente, este valor é application/xml . |
x-ms-request-id |
Este cabeçalho identifica exclusivamente o pedido que foi feito e pode ser utilizado para resolver o pedido. Para obter mais informações, veja Resolver problemas de operações da API. |
x-ms-version |
Indica a versão do Armazenamento de Blobs utilizada para executar o pedido. Este cabeçalho é devolvido para pedidos feitos com a versão 2009-09-19 e posterior. Este cabeçalho também é devolvido para pedidos anónimos, sem uma versão especificada, se o contentor foi marcado para acesso público com 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 este valor. |
x-ms-client-request-id |
Pode utilizar este cabeçalho para resolver problemas de pedidos e respostas correspondentes. O valor deste cabeçalho é igual ao valor do x-ms-client-request-id cabeçalho, se estiver presente no pedido. O valor é, no máximo, 1024 carateres ASCII visíveis. Se o x-ms-client-request-id cabeçalho não estiver presente no pedido, este cabeçalho não estará presente na resposta. |
Corpo da resposta
O formato da resposta XML é o seguinte.
Tenha em atenção que os Prefix
elementos , Marker
, MaxResults
e Delimiter
só estão presentes se tiverem sido especificados no URI do pedido. O NextMarker
elemento só tem um valor se os resultados da lista não estiverem concluídos.
Instantâneos, metadados de blobs e blobs não comprometidos só são incluídos na resposta se forem especificados com o include
parâmetro no URI do pedido.
Na versão 2009-09-19 e posterior, as propriedades do blob são encapsuladas num Properties
elemento.
A partir da versão 2009-09-19, List Blobs
devolve os seguintes elementos com o nome mudado no corpo da 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 carrega um blob com o Put Blob. O Armazenamento de Blobs não calcula isto quando cria um blob com a Lista de Blocos Put. Pode definir explicitamente o Content-MD5
valor ao criar o blob ou ao chamar as operações Colocar Lista de Blocos ou Definir Propriedades do Blob .
Para versões de 2009-09-19 e posteriores, mas antes da versão 2015-02-21, não pode chamar List Blobs
num contentor que inclua blobs de acréscimo. O serviço devolve o código de estado 409 (Conflito) se o resultado da listagem contiver um blob de acréscimo.
LeaseState
e LeaseDuration
aparecer apenas na versão 2012-02-12 e posterior.
CopyId
, CopyStatus
, CopySource
, CopyProgress
, CopyCompletionTime
, e CopyStatusDescription
só aparecem na versão 2012-02-12 e posterior, quando esta operação inclui o include={copy}
parâmetro. Estes elementos não aparecem se este blob nunca tiver sido o destino de uma Copy Blob
operação. Os elementos não aparecem se este blob tiver sido modificado após uma operação concluída Copy Blob
, utilizando Set Blob Properties
, Put Blob
ou Put Block List
. Estes elementos também não aparecem com um blob criado pelo Copy 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 final do blob. Este elemento também contém um ContainerName
campo que especifica o nome do contentor. Em versões anteriores, estes dois atributos foram combinados em conjunto no ContainerName
campo. Também na versão 2013-08-15 e posterior, o Url
elemento abaixo Blob
foi removido.
Para a versão 2015-02-21 e posterior, List Blobs
devolve blobs de todos os tipos (blobs de bloco, página e acréscimo).
Para a versão 2015-12-11 e posterior, List Blobs
devolve o ServerEncrypted
elemento. Este elemento está definido para true
se os metadados do blob e da aplicação estiverem completamente encriptados, caso false
contrário.
Para a versão 2016-05-31 e posterior, List Blobs
devolve o IncrementalCopy
elemento 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
devolve o AccessTier
elemento se uma camada de acesso tiver sido explicitamente definida. Para obter uma lista dos escalões de blobs de página premium permitidos, veja Armazenamento premium de alto desempenho e discos geridos para VMs. Para o Armazenamento de Blobs ou contas v2 para fins gerais, os valores válidos são Hot
, Cool
e Archive
. Se o blob estiver no estado de reidratar pendente, o ArchiveStatus
elemento é devolvido 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 a camada de blobs de blocos, veja Camadas de armazenamento frequente, esporádico e de arquivo.
Para a versão 2017-04-17 e posterior, List Blobs
devolve o AccessTierInferred
elemento nas contas de Armazenamento de Blobs ou para fins gerais v2. Se o blob de blocos não tiver a camada de acesso definida, as informações da camada são inferidas a partir das propriedades da conta de armazenamento e este valor está definido como true
. Este cabeçalho só está presente se o escalão for inferido a partir da propriedade da conta.
Para a versão 2017-04-17 e posterior, List Blobs
devolve o AccessTierChangeTime
elemento nas contas de Armazenamento de Blobs ou para fins gerais v2. Esta opção só é devolvida se a camada no blob de blocos alguma vez tiver sido definida. Para obter mais informações, veja Representação dos valores de data/hora nos cabeçalhos.
Para a versão 2017-07-29 e posterior, Deleted
, DeletedTime
e RemainingRetentionDays
aparece quando esta operação inclui o include={deleted}
parâmetro. Estes elementos não aparecem se este blob não tiver sido eliminado. Estes elementos são apresentados para blobs ou instantâneos que são eliminados com a DELETE
operação, quando a funcionalidade de eliminação recuperável foi ativada. O Deleted
elemento está definido como true
para blobs e instantâneos que são eliminados de forma recuperável. Deleted-Time
corresponde à hora em que o blob foi eliminado. RemainingRetentionDays
indica o número de dias após o qual um blob eliminado de forma recuperável é eliminado permanentemente.
Para a versão 2017-11-09 e posterior, Creation-Time
devolve o momento em que este blob foi criado.
Para a versão 2019-02-02 e posterior, List Blobs
devolve o CustomerProvidedKeySha256
elemento se o blob estiver encriptado com uma chave fornecida pelo cliente. O valor será definido como o hash SHA-256 da chave utilizada para encriptar o blob. Além disso, se a operação incluir o include={metadata}
parâmetro e existirem metadados de aplicação presentes num blob encriptado com uma chave fornecida pelo cliente, o Metadata
elemento terá um Encrypted="true"
atributo. Este atributo indica que o blob tem metadados que não podem ser desencriptados como parte da List Blobs
operação. Para aceder aos metadados destes blobs, chame Obter Propriedades do Blob ou Obter Metadados de Blobs com a chave fornecida pelo cliente.
Para a versão 2019-02-02 e posterior, List Blobs
devolve o EncryptionScope
elemento se o blob estiver encriptado com um âmbito de encriptação. O valor será definido como o nome do âmbito de encriptação utilizado para encriptar o blob. Se a operação incluir o include={metadata}
parâmetro, os metadados da aplicação no blob são desencriptados de forma transparente e estão disponíveis no Metadata
elemento.
Para a versão 2019-12-12 e posterior, List Blobs
devolve o RehydratePriority
elemento em Armazenamento de Blobs ou contas v2 para fins gerais, 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
devolve o VersionId
elemento para blobs e versões de blobs geradas, quando o controlo de versões está ativado na conta.
Para a versão 2019-12-12 e posterior, List Blobs
devolve o IsCurrentVersion
elemento para a versão atual do blob. O valor está definido como true
. Este elemento permite-lhe diferenciar a versão atual das versões geradas automaticamente só de leitura.
Para a versão 2019-12-12 e posterior, List Blobs
devolve o TagCount
elemento para blobs com quaisquer etiquetas. O Tags
elemento só aparece quando esta operação inclui o include={tags}
parâmetro. Estes elementos não aparecem se não existirem etiquetas no blob.
Para a versão 2019-12-12 e posterior, List Blobs
devolve o Sealed
elemento para blobs de acréscimo. O Sealed
elemento só aparece quando o blob de acréscimo foi selado. Estes elementos não aparecem se o blob de acréscimo não estiver selado.
Para a versão 2020-02-10 e posterior, List Blobs
devolve o LastAccessTime
elemento. O elemento mostra quando os dados do blob foram acedidos pela última vez, de acordo com a última política de controlo de tempo de acesso da conta de armazenamento. O elemento não é devolvido se a conta de armazenamento não tiver esta política ou se a política estiver desativada. Para obter informações sobre como definir a última política de controlo de tempo de acesso da conta, veja a API do Serviço de Blobs. O LastAccessTime
elemento não controla a última vez que os metadados do blob são acedidos.
Para a versão 2020-06-12 e posterior, List Blobs
devolve os ImmutabilityPolicyUntilDate
elementos e ImmutabilityPolicyMode
, quando esta operação inclui o include={immutabilitypolicy}
parâmetro.
Para a versão 2020-06-12 e posterior, List Blobs
devolve o LegalHold
elemento, quando esta operação inclui o include={legalhold}
parâmetro.
Para a versão 2020-06-12 e posterior, para contas com um espaço de nomes hierárquico ativado, List Blobs
devolve os Owner
elementos , Group
, Permissions
e Acl
. O pedido tem de conter o include={permissions}
parâmetro . Tenha em atenção que o Acl
elemento é uma lista combinada de listas de acesso e controlo de acesso predefinidas que foram definidas no ficheiro ou diretório.
Para a versão 2020-06-12 e posterior, para contas com um espaço de nomes hierárquico ativado, List Blobs
com um delimitador devolve o Properties
elemento no BlobPrefix
elemento. Isto corresponde às propriedades no diretório.
Para a versão 2020-08-04 e posterior, para contas com um espaço de nomes hierárquico ativado, List Blobs
devolve o DeletionId
elemento para blobs eliminados. DeletionId
é um identificador de 64 bits não assinado. O elemento identifica exclusivamente um caminho eliminado de forma recuperável, para o distinguir de outros blobs eliminados com o mesmo caminho.
Para a versão 2020-10-02 e posterior, para contas com um espaço de nomes hierárquico ativado, List Blobs
devolve o ResourceType
elemento de propriedade do caminho. Isto pode ser ou file
directory
.
Para a versão 2021-02-12 e posterior, List Blobs
o codificará por percentagem (por RFC 2396) todos os Blob
Name
valores ou BlobPrefix
Name
valores de elementos. Especificamente, irá fazê-lo para os valores que contêm carateres que não são válidos em XML (U+FFFE ou U+FFFF). Se codificado, o Name
elemento incluirá um Encoded=true
atributo. Tenha em atenção que isto só ocorre para os valores dos Name
elementos que contêm os carateres inválidos no XML e não para os restantes Name
elementos na resposta.
Para a versão 2021-06-08 e posterior, para contas com um espaço de nomes hierárquico ativado, List Blobs
devolve o Placeholder
elemento de propriedades. Devolve este elemento no elemento para diretórios BlobPrefix
de marcadores de posição ao listar blobs eliminados com um delimitador. Estes diretórios de marcadores de posição existem para facilitar a navegação para blobs eliminados de forma recuperável.
Para a versão 2021-06-08 e posterior, para contas com um espaço de nomes hierárquico ativado, List Blobs
devolve o EncryptionContext
elemento. Se o valor da propriedade de contexto de encriptação estiver definido, devolverá o valor definido.
Para a versão 2020-02-10 e posterior, para contas com um espaço de nomes hierárquico ativado, List Blobs
devolve o Expiry-Time
elemento para blobs eliminados. Expiry-Time
é a hora em que o ficheiro expira e é devolvido para o ficheiro se a expiração estiver 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 amostra
Veja Enumerar recursos de blobs 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. Pode autorizar a List Blobs
operação conforme descrito abaixo.
O Armazenamento do Azure suporta a utilização de Microsoft Entra ID para autorizar pedidos para dados de blobs. Com Microsoft Entra ID, pode utilizar o controlo de acesso baseado em funções do Azure (RBAC do Azure) para conceder permissões a um principal de segurança. O principal de segurança pode ser um utilizador, grupo, principal de serviço de aplicação ou identidade gerida do Azure. O principal de segurança é autenticado por Microsoft Entra ID para devolver um token OAuth 2.0. Em seguida, o token pode ser utilizado para autorizar um pedido contra o serviço Blob.
Para saber mais sobre a autorização através de Microsoft Entra ID, veja Autorizar o acesso a blobs com Microsoft Entra ID.
Permissões
Abaixo estão listadas as ações RBAC necessárias para que um utilizador, grupo ou principal de serviço Microsoft Entra chame a List Blobs
operação e a função RBAC do Azure com menos privilégios que inclua esta ação:
- Ação RBAC do Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
- Função incorporada com menos privilégios:Leitor deDados de Blobs de Armazenamento
Para saber mais sobre como atribuir funções com o RBAC do Azure, veja Atribuir uma função do Azure para acesso a dados de blobs.
Observações
Propriedades do blob na resposta
Se tiver pedido que os blobs não comprometidos fossem incluídos na enumeração, tenha em atenção que algumas propriedades não estão definidas até que o blob seja consolidado. Algumas propriedades podem não ser devolvidas na resposta.
O x-ms-blob-sequence-number
elemento só é devolvido para blobs de páginas.
O OrMetadata
elemento só é devolvido para blobs de blocos.
Para os blobs de páginas, o valor devolvido no Content-Length
elemento corresponde ao valor do cabeçalho do x-ms-blob-content-length
blob.
O Content-MD5
elemento aparece no corpo da resposta, apenas se tiver sido definido no blob com a versão 2009-09-19 ou posterior. Pode definir a Content-MD5
propriedade quando o blob é criado ou ao chamar Definir Propriedades do Blob. Na versão 2012-02-12 e posterior, Put Blob
define o valor MD5 de um blob de blocos, mesmo quando o Put Blob
pedido não inclui um cabeçalho MD5.
Metadados na resposta
O Metadata
elemento só está presente se o include=metadata
parâmetro tiver sido especificado no URI. Dentro do Metadata
elemento, o valor de cada par nome-valor é listado num elemento correspondente ao nome do par.
Tenha em atenção que os metadados pedidos com este parâmetro têm de ser armazenados de acordo com as restrições de nomenclatura impostas pela versão 2009-09-19 do Armazenamento de Blobs. A partir desta versão, todos os nomes de metadados têm de cumprir as convenções de nomenclatura dos identificadores C#.
Se um par nome-valor de metadados violar estas restrições de nomenclatura, o corpo da resposta indica o nome problemático dentro de um x-ms-invalid-name
elemento. O fragmento XML seguinte mostra o seguinte:
…
<Metadata>
<MyMetadata1>first value</MyMetadata1>
<MyMetadata2>second value</MyMetadata2>
<x-ms-invalid-name>invalid-metadata-name</x-ms-invalid-name>
</Metadata>
…
Etiquetas na resposta
O Tags
elemento só está presente se o include=tags
parâmetro tiver sido especificado no URI e se existirem etiquetas no blob. Dentro do TagSet
elemento, são devolvidos até 10 Tag
elementos, cada um com as key
etiquetas de value
índice de blobs definidas pelo utilizador. A ordenação de etiquetas não é garantida na resposta.
Os Tags
elementos e TagCount
não são devolvidos se não existirem etiquetas no blob.
O serviço de armazenamento mantém uma forte consistência entre um blob e as respetivas etiquetas, mas o índice secundário é eventualmente consistente. As etiquetas podem ser visíveis numa resposta a List Blobs
antes de serem visíveis para Find Blobs by Tags
as operações.
Instantâneos na resposta
Os instantâneos são listados na resposta apenas se o include=snapshots
parâmetro tiver sido especificado no URI. Os instantâneos listados na resposta não incluem o elemento, porque os LeaseStatus
instantâneos não podem ter concessões ativas.
Ao utilizar a versão de serviço 2021-06-08 e superior, pode ligar List Blobs
com um delimitador e incluir instantâneos na enumeração. Para versões de serviço anteriores a 2021-06-08, um pedido que inclui ambos devolve um erro InvalidQueryParameter (código de estado HTTP 400 – Pedido Incorreto).
Blobs não comprometidos na resposta
Os blobs não comprometidos são listados na resposta apenas se o include=uncommittedblobs
parâmetro tiver sido especificado no URI. Os blobs não comprometidos 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 eliminados na resposta
Os blobs eliminados são listados na resposta apenas se o include=deleted
parâmetro tiver sido especificado no URI. Os blobs eliminados listados na resposta não incluem os elementos concessão , uma vez que os blobs eliminados não podem ter concessões ativas.
Os instantâneos eliminados são incluídos na resposta da lista se include=deleted,snapshot
tiver sido especificado no URI.
Metadados de replicação de objetos na resposta
O OrMetadata
elemento está presente quando uma política de replicação de objetos foi avaliada num blob e a List Blobs
chamada foi efetuada com a versão 2019-12-12 ou posterior. Dentro do OrMetadata
elemento, o valor de cada par nome-valor é listado num 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 objetos na conta de armazenamento. {rule-id}
é um GUID que representa o identificador de regras no contentor 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
só estão presentes se o include=immutabilitypolicy
parâmetro tiver sido especificado no URI.
<Properties>
<ImmutabilityPolicyUntilDate>date-time-value</ImmutabilityPolicyUntilDate>
<ImmutabilityPolicyMode>unlocked | locked </ImmutabilityPolicyMode>
</Properties>
Suspensão legal na resposta
O LegalHold
elemento só está presente se o include=legalhold
parâmetro tiver sido especificado no URI.
<Properties>
<LegalHold>true | false </LegalHold>
</Properties>
Devolver conjuntos de resultados com um valor de marcador
Se especificar um valor para o maxresults
parâmetro e o número de blobs a devolver exceder este valor ou exceder o valor predefinido para maxresults
, o corpo da resposta contém um NextMarker
elemento. Este elemento indica o próximo blob a devolver num pedido subsequente. Em determinados casos, o serviço pode devolver o NextMarker
elemento, mesmo que o número de resultados devolvidos seja inferior ao valor de maxresults
.
Para devolver o próximo conjunto de itens, especifique o valor de como o parâmetro de NextMarker
marcador no URI para o pedido subsequente. Tenha em atenção que o valor de NextMarker
deve ser tratado como opaco.
Utilizar um delimitador para percorrer o espaço de nomes do blob
O delimiter
parâmetro permite que o autor da chamada percorra o espaço de nomes do blob com um delimitador configurado pelo utilizador. Desta forma, pode percorrer uma hierarquia virtual de blobs como se fosse um sistema de ficheiros. O delimitador pode ser um único caráter ou uma cadeia.
Quando o pedido inclui este parâmetro, a operação devolve um BlobPrefix
elemento. O BlobPrefix
elemento é devolvido em vez de todos os blobs com nomes que começam com a mesma subcadeia, até ao aspeto do caráter delimitador. O valor do BlobPrefix
elemento é subcadeia+delimitador, em que a subcadeia é a subcadeia comum que começa um ou mais nomes de blobs e o delimitador é o valor do delimiter
parâmetro.
Pode utilizar o valor de BlobPrefix
para fazer uma chamada subsequente para listar os blobs que começam com este prefixo. Para tal, especifique o valor de BlobPrefix
para o prefix
parâmetro no URI do pedido.
Tenha em atenção que cada BlobPrefix
elemento devolvido conta para o resultado máximo, tal como cada Blob
elemento.
Os blobs são listados por ordem alfabética no corpo da resposta, com letras maiúsculas listadas primeiro.
Erros de cópia na Descrição do Estado da Cópia
CopyStatusDescription
contém mais informações sobre a Copy Blob
falha.
Quando uma tentativa de cópia falha,
CopyStatus
está definida comopending
se o Armazenamento de Blobs ainda estiver a tentar novamente a operação. OCopyStatusDescription
texto descreve a falha que pode ter ocorrido durante a última tentativa de cópia.Quando
CopyStatus
está definido comofailed
, oCopyStatusDescription
texto descreve o erro que causou a falha da operação de cópia.
A tabela seguinte descreve os campos de cada CopyStatusDescription
valor.
Componente | Descrição |
---|---|
Código de estado de HTTP | Número inteiro padrão de três dígitos que especifica a falha. |
Código de erro | Palavra-chave que descreve o erro. É fornecido pelo Azure no <elemento ErrorCode> . Se não for apresentado nenhum <elemento ErrorCode> , o serviço devolve uma palavra-chave que contém texto de erro padrão associado ao código de estado HTTP de três dígitos na especificação HTTP. Para obter mais informações, veja Códigos de erro comuns da API REST. |
Informações | Descrição detalhada da falha, em aspas. |
A tabela seguinte descreve os CopyStatus
valores e CopyStatusDescription
dos cenários comuns de falha.
Importante
O texto de descrição apresentado aqui pode ser alterado sem aviso, mesmo sem uma alteração de versão. Não dependa da correspondência deste texto exato.
Scenario | Valor Copiar Estado | Copiar valor de Descrição do Estado |
---|---|---|
A operação de cópia foi concluída com êxito. | exito | vazio |
O utilizador abortou a operação de cópia antes de ser 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á tentada novamente. | pendente | 502 BadGateway "Detetou um erro de repetição ao ler a origem. Tentará novamente. Hora da falha: <hora>" |
Ocorreu uma falha ao escrever no blob de destino de uma operação de cópia. A operação será tentada novamente. | pendente | 500 InternalServerError "Foi encontrado um erro retráctil. Tentará novamente. Hora da falha: <hora>" |
Ocorreu uma falha irrecuperável ao ler a partir do blob de origem de uma operação de cópia. | falhou | 404 ResourceNotFound "A cópia falhou ao ler a origem". Quando o serviço comunica este erro subjacente, este regressa ResourceNotFound no <elemento ErrorCode> . Se não for apresentado nenhum <elemento ErrorCode> na resposta, é apresentada uma representação de cadeia padrão do estado HTTP, como NotFound , . |
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 demasiada frequência ao ler a partir da origem e não cumpriu um rácio mínimo de tentativas para êxitos. (Este tempo limite impede a repetição de uma origem muito fraca ao longo de duas semanas antes de falhar). | falhou | 500 OperationCancelled "A cópia falhou ao ler a origem". |
Faturação
Os pedidos de preços podem ter origem em clientes que utilizam APIs de Armazenamento de Blobs, diretamente através da API REST do Armazenamento de Blobs ou a partir de uma biblioteca de cliente do Armazenamento do Azure. Estes pedidos acumulam custos por transação. O tipo de transação afeta a forma como a conta é cobrada. Por exemplo, as transações de leitura acumulam-se numa categoria de faturação diferente das transações de escrita. A tabela seguinte mostra a categoria de faturação dos List Blobs
pedidos com base no tipo de conta de armazenamento:
Operação | Tipo de conta de armazenamento | Categoria de faturação |
---|---|---|
Listar Blobs | Blob de bloco premium Standard para fins gerais v2 Standard para fins gerais v1 |
Listar e Criar Operações de contentor |
Para saber mais sobre os preços da categoria de faturação especificada, veja Armazenamento de Blobs do Azure Preços.
Ver também
Códigos de estado e de erro
Códigos de erro do Armazenamento de Blobs