Listar Blobs

Artigo
02/07/2024

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 Prefixelementos , Marker, MaxResultse 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 (anteriormente LastModified)
Content-Length (anteriormente Size)
Content-Type (anteriormente ContentType)
Content-Encoding (anteriormente ContentEncoding)
Content-Language (anteriormente ContentLanguage)

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 Blobou 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, Coole 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-coolou 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, DeletedTimee 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 Ownerelementos , Group, Permissionse 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 filedirectory.

Para a versão 2021-02-12 e posterior, List Blobs o codificará por percentagem (por RFC 2396) todos os BlobName valores ou BlobPrefixName 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.

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

A List Blobs operação suporta três tipos de assinaturas de acesso partilhado: SAS de delegação de utilizador,SAS de serviço e SAS de conta.

Como melhor prática de segurança, recomendamos que utilize Microsoft Entra credenciais em vez da chave da conta de armazenamento, que podem ser mais facilmente comprometidas. Se a estrutura da aplicação exigir assinaturas de acesso partilhado, utilize Microsoft Entra credenciais para criar uma SAS de delegação de utilizador, sempre que possível.

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

SAS de delegação de utilizadores

Uma SAS de delegação de utilizador é protegida com credenciais de Microsoft Entra e também pelas permissões especificadas para a SAS.

Chamar a List Blobs operação com um token de SAS delegado a um recurso de contentor requer a permissão Lista (l) como parte do token SAS de delegação de utilizador.

Para saber mais sobre a SAS de delegação de utilizador, veja Criar uma SAS de delegação de utilizador.

SAS de Serviço

Uma SAS de serviço é protegida com a chave da conta de armazenamento. Um serviço SAS delega o acesso a um recurso num único serviço de Armazenamento do Azure, como o armazenamento de blobs.

Chamar a List Blobs operação com um token de SAS delegado a um recurso de contentor requer a permissão Lista (l) como parte do token saS do serviço.

Para saber mais sobre a SAS do serviço, veja Criar uma SAS de serviço.

SAS de Conta

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

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

Operação	Serviço assinado	Tipo de recurso assinado	Permissão assinada
Listar Blobs	Blob (b)	Contentor (c)	Lista (l)

Para saber mais sobre a SAS da conta, consulte Criar uma SAS de conta.

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 como pending se o Armazenamento de Blobs ainda estiver a tentar novamente a operação. O CopyStatusDescription texto descreve a falha que pode ter ocorrido durante a última tentativa de cópia.
Quando CopyStatus está definido como failed, o CopyStatusDescription 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