Listagem de recursos de armazenamento de Blob

A API do serviço Blob inclui operações para listar os contêineres dentro de uma conta (operação Listar Contêineres ) e os blobs dentro de um contêiner (a operação Listar Blobs ). Essas operações têm algumas características comuns que merecem ser mencionadas.

Uma operação de listagem retorna uma resposta que contém toda ou parte da lista solicitada. A operação retorna entidades em ordem alfabética.

Este tópico contém os seguintes subtópicos:

Defina o máximo de resultados

Recuperar resultados parciais da lista com marcadores

Resultados da lista de filtros

Percorra o namespace do blob

Formato de resposta XML

Formato de resposta do Apache Arrow

Defina o máximo de resultados

Para especificar o número máximo de resultados a serem retornados em uma única chamada para uma operação de listagem, especifique um valor para o maxresults parâmetro no URI da solicitação.

Se o número máximo de resultados não for especificado na solicitação ou for maior que 5.000, o servidor retorna até o máximo de 5.000 itens. Se você especificar um número máximo de resultados igual ou menor que zero, o serviço retorna o código de status 400 (Solicitação Ruim).

Recuperar resultados parciais da lista com marcadores

Na primeira vez que a operação de listagem é realizada contra um determinado recurso, a resposta pode conter todos os resultados, ou pode conter um subconjunto dos resultados e um valor de marcador. O valor do marcador pode ser passado para a chamada subsequente para retornar o próximo conjunto de resultados (e depois o próximo) até que a lista esteja completa e nenhum marcador seja retornado.

O valor do marcador é retornado como NextMarker. Em uma resposta XML, NextMarker é um elemento no corpo da resposta. Em uma resposta de Blocos da Lista de Setas Apache , NextMarker há um campo nos metadados do esquema. Quando NextMarker está vazio, a listagem está completa. O valor de NextMarker é um valor de string que é opaco para o cliente.

Para retornar o próximo conjunto de resultados em uma operação subsequente, passe o valor retornado NextMarker como o marker parâmetro no URI da solicitação.

Resultados da lista de filtros

A lista de resultados pode ser filtrada especificando uma string de prefixo na solicitação usando o prefix parâmetro. A operação de lista então retorna as entidades que têm nomes que começam com esse prefixo. Se o prefix parâmetro for especificado no URI da requisição, o XML da resposta inclui um Prefix elemento contendo o caractere prefixo ou caracteres. Por exemplo, especificar um prefixo com o valor "c" retorna <Prefix>``c``</Prefix> dentro do XML de resposta. Para um exemplo, veja a seção Listar contêineres mais adiante neste tópico.

Percorra o namespace do blob

A operação List Blobs possui um parâmetro adicional delimiter que permite ao chamador percorrer o namespace do blob usando um delimitador configurado pelo usuário. O delimitador pode ser um único caractere ou uma cadeia de caracteres. Quando a solicitação inclui esse parâmetro, a operação retorna um BlobPrefix elemento. O BlobPrefix elemento é retornado no lugar de todas as manchas com nomes que começam com a mesma substring até o aparecimento do caractere delimitador. O valor do BlobPrefix elemento é substring+delimitador, onde substring é a substring comum que inicia um ou mais nomes de blobs, e delimitador é o valor do parâmetro delimitador .

Você pode usar o valor de BlobPrefix para fazer uma chamada subsequente para listar os blobs que começam com esse prefixo. Especifique o valor de BlobPrefix para solicitações subsequentes. Dessa forma, você pode percorrer uma hierarquia virtual de blobs como se fosse um sistema de arquivos. Para um exemplo, veja Listar blobs com um delimitador mais adiante neste tópico.

Note que cada BlobPrefix retorno conta para o resultado máximo.

Também tenha em mente que você não pode listar snapshots de blob se incluir um delimitador com a solicitação. Se você especificar um valor para o delimiter parâmetro e também definir o include=snapshots parâmetro, o serviço Blob retorna um erro InvalidQueryParameter (código de status HTTP 400 – Solicitação Inválida).

Formato de resposta XML

A saída da lista é um documento XML cujo formato é semelhante ao mostrado nos exemplos de código mais adiante neste tópico.

O corpo da resposta inclui os valores de todos os parâmetros especificados no URI da solicitação como elementos dentro do corpo da resposta.

O DateTime valor retornado no Last-Modified elemento está no formato RFC 1123. Para mais informações sobre DateTime valores, veja Representação dos valores de data/hora em cabeçalhos.

Listar contêineres

Este exemplo mostra o resultado de uma operação de listagem que retorna dois contêineres. O URI da solicitação é o seguinte:

GET https://myaccount.blob.core.windows.net/?comp=list&prefix=c&maxresults=3&include=metadata

O prefixo "c" foi especificado para filtrar a lista. O número máximo de resultados a serem retornados foi fixado em 3. A NextMarker tag mostra o nome do contêiner que será devolvido em uma operação de listagem subsequente.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults AccountName="https://myaccount.blob.core.windows.net/">  
  <Prefix>c</Prefix>  
  <MaxResults>3</MaxResults>  
  <Containers>  
    <Container>  
      <Name>container1</Name>  
      <Url>https://myaccount.blob.core.windows.net/container1</Url>  
      <Properties>  
        <Last-Modified>Sun, 27 Sep 2009 18:09:03 GMT</Last-Modified>  
        <Etag>0x8CAE7D0C4AF4487</Etag>  
      </Properties>  
      <Metadata>  
        <Color>orange</Color>  
        <ContainerNumber>01</ContainerNumber>  
        <SomeMetadataName>SomeMetadataValue</SomeMetadataName>  
      </Metadata>  
    </Container>  
    <Container>  
      <Name>container2</Name>  
      <Url>https://myaccount.blob.core.windows.net/container2</Url>  
      <Properties>  
        <Last-Modified>Sun, 27 Sep 2009 17:26:40 GMT</Last-Modified>  
        <Etag>0x8CAE7CAD8C24928</Etag>  
      </Properties>  
      <Metadata>  
        <Color>pink</Color>  
        <ContainerNumber>02</ContainerNumber>  
        <SomeMetadataName>SomeMetadataValue</SomeMetadataName>  
      </Metadata>  
    </Container>  
    <Container>  
      <Name>container3</Name>  
      <Url>https://myaccount.blob.core.windows.net/container3</Url>  
      <Properties>  
        <Last-Modified>Sun, 27 Sep 2009 17:26:40 GMT</Last-Modified>  
        <Etag>0x8CAE7CAD8EAC0BB</Etag>  
      </Properties>  
      <Metadata>  
        <Color>brown</Color>  
        <ContainerNumber>03</ContainerNumber>  
        <SomeMetadataName>SomeMetadataValue</SomeMetadataName>  
      </Metadata>  
    </Container>  
  </Containers>  
  <NextMarker>container4</NextMarker>  
</EnumerationResults>

Lista de blobs e snapshots

Este exemplo mostra o resultado de uma operação de listagem que retorna blobs e snapshots em um contêiner chamado mycontainer. O URI da solicitação é o seguinte:

GET https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list&include=snapshots&include=metadata

A resposta inclui tanto os blobs quanto os snapshots:

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ContainerName="https://myaccount.blob.core.windows.net/mycontainer">  
  <Blobs>  
    <Blob>  
      <Name>blob1.txt</Name>  
      <Url>https://myaccount.blob.core.windows.net/mycontainer/blob1.txt</Url>  
      <Properties>  
        <Last-Modified>Wed, 09 Sep 2009 09:20:02 GMT</Last-Modified>  
        <Etag>0x8CBFF45D8A29A19</Etag>  
        <Content-Length>100</Content-Length>  
        <Content-Type>text/html</Content-Type>  
        <Content-Encoding />  
        <Content-Language>en-US</Content-Language>  
        <Content-MD5 />  
        <Cache-Control>no-cache</Cache-Control>  
        <BlobType>BlockBlob</BlobType>  
        <LeaseStatus>unlocked</LeaseStatus>  
      </Properties>  
      <Metadata>  
        <Color>blue</Color>  
        <BlobNumber>01</BlobNumber>  
        <SomeMetadataName>SomeMetadataValue</SomeMetadataName>  
      </Metadata>  
    </Blob>  
    <Blob>  
      <Name>blob2.txt</Name>  
      <Snapshot>2009-09-09T09:20:03.0427659Z</Snapshot>  
      <Url>https://myaccount.blob.core.windows.net/mycontainer/blob2.txt?snapshot=2009-09-09T09%3a20%3a03.0427659Z</Url>  
      <Properties>  
        <Last-Modified>Wed, 09 Sep 2009 09:20:02 GMT</Last-Modified>  
        <Etag>0x8CBFF45D8B4C212</Etag>  
        <Content-Length>5000</Content-Length>  
        <Content-Type>application/octet-stream</Content-Type>  
        <Content-Encoding>gzip</Content-Encoding>  
        <Content-Language />  
        <Content-MD5 />  
        <Cache-Control />  
        <BlobType>BlockBlob</BlobType>  
      </Properties>  
      <Metadata>  
        <Color>green</Color>  
        <BlobNumber>02</BlobNumber>  
        <SomeMetadataName>SomeMetadataValue</SomeMetadataName>  
        <x-ms-invalid-name>nasdf$@#$$</x-ms-invalid-name>  
      </Metadata>  
    </Blob>  
    <Blob>  
      <Name>blob2.txt</Name>  
      <Snapshot>2009-09-09T09:20:03.1587543Z</Snapshot>  
      <Url>https://myaccount.blob.core.windows.net/mycontainer/blob2.txt?snapshot=2009-09-09T09%3a20%3a03.1587543Z</Url>  
      <Properties>  
        <Last-Modified>Wed, 09 Sep 2009 09:20:02 GMT</Last-Modified>  
        <Etag>0x8CBFF45D8B4C212</Etag>  
        <Content-Length>5000</Content-Length>  
        <Content-Type>application/octet-stream</Content-Type>  
        <Content-Encoding>gzip</Content-Encoding>  
        <Content-Language />  
        <Content-MD5 />  
        <Cache-Control />  
        <BlobType>BlockBlob</BlobType>  
      </Properties>  
      <Metadata>  
        <Color>green</Color>  
        <BlobNumber>02</BlobNumber>  
        <SomeMetadataName>SomeMetadataValue</SomeMetadataName>  
      </Metadata>  
    </Blob>  
    <Blob>  
      <Name>blob2.txt</Name>  
      <Url>https://myaccount.blob.core.windows.net/mycontainer/blob2.txt</Url>  
      <Properties>  
        <Last-Modified>Wed, 09 Sep 2009 09:20:02 GMT</Last-Modified>  
        <Etag>0x8CBFF45D8B4C212</Etag>  
        <Content-Length>5000</Content-Length>  
        <Content-Type>application/octet-stream</Content-Type>  
        <Content-Encoding>gzip</Content-Encoding>  
        <Content-Language />  
        <Content-MD5 />  
        <Cache-Control />  
        <BlobType>BlockBlob</BlobType>  
        <LeaseStatus>unlocked</LeaseStatus>  
      </Properties>  
      <Metadata>  
        <Color>green</Color>  
        <BlobNumber>02</BlobNumber>  
        <SomeMetadataName>SomeMetadataValue</SomeMetadataName>  
      </Metadata>  
    </Blob>  
    <Blob>  
      <Name>blob3.txt</Name>  
      <Url>https://myaccount.blob.core.windows.net/mycontainer/blob3.txt</Url>  
      <Properties>  
        <Last-Modified>Wed, 09 Sep 2009 09:20:03 GMT</Last-Modified>  
        <Etag>0x8CBFF45D911FADF</Etag>  
        <Content-Length>16384</Content-Length>  
        <Content-Type>image/jpeg</Content-Type>  
        <Content-Encoding />  
        <Content-Language />  
        <Content-MD5 />  
        <Cache-Control />  
        <x-ms-blob-sequence-number>3</x-ms-blob-sequence-number>  
        <BlobType>PageBlob</BlobType>  
        <LeaseStatus>locked</LeaseStatus>  
      </Properties>  
      <Metadata>  
        <Color>yellow</Color>  
        <BlobNumber>03</BlobNumber>  
        <SomeMetadataName>SomeMetadataValue</SomeMetadataName>  
      </Metadata>  
    </Blob>  
  </Blobs>  
  <NextMarker />   
</EnumerationResults>

Listar blobs com um delimitador

Este exemplo mostra o resultado de uma operação de listagem que retorna blobs abaixo de um contêiner chamado mycontainer. O URI da solicitação é o seguinte:

GET https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list&delimiter=/&maxresults=4

Nesse caso, o delimiter parâmetro é especificado como /. O corpo da resposta inclui a BlobPrefix tag, que representa o grupo de manchas que começam com a mesma substring, incluindo o delimitador.

As amostras de bolhas abaixo do recipiente são as seguintes. Os quatro primeiros são retornados na primeira operação de listagem, porque MaxResults está definido como 4. Note que myfolder/blobA.txt e myfolder/blobB.txt estão agrupados no corpo da resposta na BlobPrefix tag e contam como um único blob em termos do número de entidades retornadas. Para retornar os blobs que começam com esse prefixo, faça uma requisição subsequente na qual o parâmetro prefixo é definido como myfolder/.

  • blob1.txt

  • blob2.txt

  • minha/blobA.txt

  • minha/blobB.txt

  • newblob1.txt

  • newblob2.txt

A próxima mancha a ser retornada é newblob2.txt. O nome do blob é fornecido na NextMarker tag.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ContainerName="https://myaccount.blob.core.windows.net/mycontainer">  
  <MaxResults>4</MaxResults>  
  <Blobs>  
    <Blob>  
      <Name>blob1.txt</Name>  
      <Url>https://myaccount.blob.core.windows.net/mycontainer/blob1.txt</Url>  
      <Properties>  
        <Last-Modified>Sun, 27 Sep 2009 18:41:57 GMT</Last-Modified>  
        <Etag>0x8CAE7D55D050B8B</Etag>  
        <Content-Length>8</Content-Length>  
        <Content-Type>text/html</Content-Type>  
        <Content-Encoding />  
        <Content-Language>en-US</Content-Language>  
        <Content-MD5 />  
        <Cache-Control>no-cache</Cache-Control>  
        <BlobType>BlockBlob</BlobType>  
        <LeaseStatus>unlocked</LeaseStatus>  
      <Properties>  
    </Blob>  
    <Blob>  
      <Name>blob2.txt</Name>  
      <Url>https://myaccount.blob.core.windows.net/mycontainer/blob2.txt</Url>  
      <Properties>  
        <Last-Modified>Sun, 27 Sep 2009 12:18:50 GMT</Last-Modified>  
        <Etag>0x8CAE7D55CF6C339</Etag>  
        <Content-Length>100</Content-Length>  
        <Content-Type>text/html</Content-Type>  
        <Content-Encoding />  
        <Content-Language>en-US</Content-Language>  
        <Content-MD5 />  
        <Cache-Control>no-cache</Cache-Control>  
        <BlobType>BlockBlob</BlobType>  
        <LeaseStatus>unlocked</LeaseStatus>  
      </Properties>  
    </Blob>  
    <BlobPrefix>  
      <Name>myfolder/</Name>  
    </BlobPrefix>  
    <Blob>  
      <Name>newblob1.txt</Name>  
      <Url>https://myaccount.blob.core.windows.net/mycontainer/newblob1.txt</Url>  
      <Properties>  
        <Last-Modified>Sun, 27 Sep 2009 16:31:57 GMT</Last-Modified>  
        <Etag>0x8CAE7D55CF6C339</Etag>  
        <Content-Length>25</Content-Length>  
        <Content-Type>text/html</Content-Type>  
        <Content-Encoding />  
        <Content-Language>en-US</Content-Language>  
        <Content-MD5 />  
        <Cache-Control>no-cache</Cache-Control>  
        <BlobType>BlockBlob</BlobType>  
        <LeaseStatus>unlocked</LeaseStatus>  
      </Properties>  
    </Blob>  
  </Blobs>  
  <NextMarker>newblob2.txt</NextMarker>  
</EnumerationResults>

Liste blobs no contêiner raiz

Para listar blobs no contêiner raiz, você pode usar a seguinte URL:

https://myaccount.blob.core.windows.net/$root?restype=container&comp=list&maxresults=10

Lembre-se de que, quando você lista os blobs no contêiner raiz, o corpo da resposta XML não inclui uma referência explícita ao contêiner raiz no campo do URL blob. Aqui está uma resposta de exemplo que lista blobs no contêiner raiz:

  
<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ContainerName="https://myaccount.blob.core.windows.net/%24root">  
  <MaxResults>10</MaxResults>  
  <Blobs>  
    <Blob>  
      <Name>rootblob1.txt</Name>  
      <Url>https://myaccount.blob.core.windows.net/rootblob1.txt</Url>  
      <Properties>  
        <Last-Modified>Sun, 27 Sep 2009 18:41:48 GMT</Last-Modified>  
        <Etag>0x8CAE7D55D050B8B</Etag>  
        <Content-Length>25</Content-Length>  
        <Content-Type>text/html</Content-Type>  
        <Content-Encoding />  
        <Content-Language>en-US</Content-Language>  
        <Content-MD5 />  
        <Cache-Control>no-cache</Cache-Control>  
        <BlobType>BlockBlob</BlobType>  
        <LeaseStatus>unlocked</LeaseStatus>  
      </Properties>  
   </Blob>  
    <Blob>  
      <Name>rootblob2.txt</Name>  
      <Url>https://myaccount.blob.core.windows.net/rootblob2.txt</Url>  
      <Properties>  
        <Last-Modified>Sun, 27 Sep 2009 18:45:57 GMT</Last-Modified>  
        <Etag>0x8CAE7D55CF6C339</Etag>  
        <Content-Length>14</Content-Length>  
        <Content-Type>text/plain; charset=UTF-8</Content-Type>  
        <Content-Encoding />  
        <Content-Language>en-US</Content-Language>  
        <Content-MD5 />  
        <Cache-Control>no-cache</Cache-Control>  
        <BlobType>BlockBlob</BlobType>  
        <LeaseStatus>unlocked</LeaseStatus>  
      </Properties>  
    </Blob>  
  </Blobs>  
</EnumerationResults>

Formato de resposta do Apache Arrow

A partir da versão 2026-06-06, a operação List Blobs também pode retornar resultados no formato Apache Arrow . A operação List Containers não suporta o Apache Arrow no momento.

Note

O suporte ao Apache Arrow para List Blobs está atualmente em pré-visualização pública.

A saída da lista é um fluxo binário Apache Arrow. Cada exemplo neste tópico mostra o lote de registros como uma tabela na qual cada linha é um prefixo de blob ou blob e cada coluna é um campo. Campos de carimbos de data, como Last-Modified, são mostrados aqui no formato ISO 8601. Cada tabela é seguida pelos NumberOfRecords valores e NextMarker dos metadados do esquema.

Listar blobs e snapshots no formato Apache Arrow

Este exemplo mostra o resultado de uma operação de listagem que retorna blobs e snapshots em um contêiner chamado mycontainer. O URI da solicitação é o seguinte:

GET https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list&include=snapshots&include=metadata

A resposta inclui tanto os blobs quanto os snapshots:

Name ResourceType Snapshot Last-Modified Etag Content-Length Content-Type Content-Encoding Content-Language Cache-Control x-ms-blob-sequence-number BlobType LeaseStatus Metadata
blob1.txt blob nulo 2009-09-09T09:20:02Z 0x8CBFF45D8A29A19 100 text/html nulo en-US no-cache nulo BlockBlob desbloqueado {Cor: azul, NúmeroMancha: 01, NomeSomeMetadata: SomeMetadataValue}
blob2.txt blob 2009-09-09T09:20:03.0427659Z 2009-09-09T09:20:02Z 0x8CBFF45D8B4C212 5.000 application/octet-stream gzip nulo nulo nulo BlockBlob nulo {Cor: verde, NúmeroMancha: 02, SomeMetadataName: SomeMetadataValue, x-ms-invalid-name: nasdf$@#$$}
blob2.txt blob 2009-09-09T09:20:03.1587543Z 2009-09-09T09:20:02Z 0x8CBFF45D8B4C212 5.000 application/octet-stream gzip nulo nulo nulo BlockBlob nulo {Cor: verde, NúmeroMancha: 02, SomeMetadataName: SomeMetadataValue}
blob2.txt blob nulo 2009-09-09T09:20:02Z 0x8CBFF45D8B4C212 5.000 application/octet-stream gzip nulo nulo nulo BlockBlob desbloqueado {Cor: verde, NúmeroMancha: 02, SomeMetadataName: SomeMetadataValue}
blob3.txt blob nulo 2009-09-09T09:20:03Z 0x8CBFF45D911FADF 16384 image/jpeg nulo nulo nulo 3 PageBlob bloqueado {Cor: amarelo, NúmeroMancha: 03, NomeSomeMetadata: SomeMetadataValue}

Os metadados do esquema contêm NumberOfRecords = 5 e NextMarker = vazia, o que indica que a listagem está completa.

Lista de blobs com um delimitador no formato Apache Arrow

Este exemplo mostra o resultado de uma operação de listagem que retorna blobs abaixo de um contêiner chamado mycontainer. O URI da solicitação é o seguinte:

GET https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list&delimiter=/&maxresults=4

Nesse caso, o delimiter parâmetro é especificado como /. O corpo da resposta inclui um registro com ResourceType definido como blobprefix, que representa o grupo de manchas que começam com a mesma substring, incluindo o delimitador.

As amostras de bolhas abaixo do recipiente são as seguintes. Os quatro primeiros são retornados na primeira operação de listagem, porque MaxResults está definido como 4. Note que myfolder/blobA.txt e myfolder/blobB.txt estão agrupados no corpo da resposta no blobprefix registro e contam como um único blob em termos do número de entidades retornadas. Para retornar os blobs que começam com esse prefixo, faça uma requisição subsequente na qual o parâmetro prefixo é definido como myfolder/.

  • blob1.txt

  • blob2.txt

  • minha/blobA.txt

  • minha/blobB.txt

  • newblob1.txt

  • newblob2.txt

newblob2.txt será o próximo blob retornado quando opaqueString for passado como marker parâmetro em uma requisição subsequente.

Name ResourceType Last-Modified Etag Content-Length Content-Type Content-Language Cache-Control BlobType LeaseStatus
blob1.txt blob 2009-09-27T18:41:57Z 0x8CAE7D55D050B8B 8 text/html en-US no-cache BlockBlob desbloqueado
blob2.txt blob 2009-09-27T12:18:50Z 0x8CAE7D55CF6C339 100 text/html en-US no-cache BlockBlob desbloqueado
minhapasta/ blobprefix nulo nulo nulo nulo nulo nulo nulo nulo
newblob1.txt blob 2009-09-27T16:31:57Z 0x8CAE7D55CF6C339 25 text/html en-US no-cache BlockBlob desbloqueado

Os metadados do esquema contêm NumberOfRecords = 4 e NextMarker = opaqueString.

Consulte também

Listar contêineres
Listar Blobs
Conceitos de serviço blob
Versioning for the Armazenamento do Azure services

  • Last updated on