Listagem de recursos de armazenamento de Blob

A API do serviço Blob inclui operações para listar os contentores dentro de uma conta (a operação List Containers ) e os blobs dentro de um contentor (a operação List Blobs ). Estas operações têm algumas características comuns dignas de nota.

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

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

Definir resultados máximos

Recuperar resultados parciais da lista com marcadores

Resultados da lista de filtros

Atravessar o espaço de nomes do blob

Formato de resposta XML

Formato de resposta Apache Arrow

Definir resultados máximos

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

Se o número máximo de resultados não for especificado no pedido ou se for superior a 5.000, o servidor devolve até um máximo de 5.000 itens. Se especificar um número máximo de resultados igual ou inferior a zero, o serviço devolve o código de estado 400 (Pedido Mau).

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 seguinte para devolver o próximo conjunto de resultados (e depois o seguinte) até que a lista esteja completa e nenhum marcador seja devolvido.

O valor do marcador é devolvido como NextMarker. Numa resposta XML, NextMarker é um elemento no corpo da resposta. Numa resposta Apache Arrow List Blobs, NextMarker existe um campo nos metadados do esquema. Quando NextMarker está vazio, a listagem está completa. O valor de NextMarker é um valor de cadeia que é opaco para o cliente.

Para devolver o próximo conjunto de resultados numa operação subsequente, passe o valor devolvido como NextMarkermarker parâmetro no URI do pedido.

Resultados da lista de filtros

A lista de resultados pode ser filtrada especificando uma cadeia de prefixos no pedido usando o prefix parâmetro. A operação de lista devolve então as entidades que têm nomes que começam com esse prefixo. Se o prefix parâmetro for especificado no URI do pedido, o XML de resposta inclui um Prefix elemento contendo o carácter 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 secção Listar contentores mais adiante neste tópico.

Atravessar o espaço de nomes do blob

A operação List Blobs tem um parâmetro adicional delimiter que permite ao chamador percorrer o espaço de nomes do blob usando um delimitador configurado pelo utilizador. O delimitador pode ser um único caractere ou uma cadeia de caracteres. Quando a solicitação inclui esse parâmetro, a operação retorna um elemento BlobPrefix. O BlobPrefix elemento é devolvido no lugar de todas as manchas com nomes que começam com a mesma substring até à aparição do carácter 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 pedidos 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 um que é devolvido conta para o resultado máximo.

Também tenha em mente que não pode listar snapshots de blob se incluir um delimitador no pedido. Se especificar um valor para o delimiter parâmetro e também definir o include=snapshots parâmetro, o serviço Blob devolve um erro InvalidQueryParameter (código de estado HTTP 400 – Pedido Mau).

Formato de resposta XML

A saída da lista é um documento XML cujo formato é semelhante aos mostrados 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 do pedido como elementos dentro do corpo da resposta.

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

Listar contêineres

Este exemplo mostra o resultado de uma operação de listagem que devolve dois contentores. O URI do pedido é 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 devolver foi fixado em 3. A NextMarker etiqueta mostra o nome do recipiente que será devolvido numa 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>

Listas de blobs e instantâneos

Este exemplo mostra o resultado de uma operação de listagem que devolve blobs e snapshots num contentor chamado mycontainer. O URI do pedido é o seguinte:

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

A resposta inclui tanto os blobs como 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 devolve blobs por baixo de um contentor chamado mycontainer. O URI do pedido é o seguinte:

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

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

As amostras por baixo do recipiente são as seguintes. Os primeiros quatro são devolvidos na primeira operação de listagem, porque MaxResults está definido para 4. Note que myfolder/blobA.txt e myfolder/blobB.txt estão agrupados no corpo da resposta na BlobPrefix etiqueta e contam como um único blob em termos do número de entidades devolvidas. Para devolver os blobs que começam com este prefixo, faça um pedido subsequente em que o parâmetro do prefixo seja definido como myfolder/.

  • blob1.txt

  • blob2.txt

  • a minha pasta/blobA.txt

  • a minha pasta/blobB.txt

  • newblob1.txt

  • newblob2.txt

O próximo blob a ser devolvido é newblob2.txt. O nome do blob é fornecido na NextMarker etiqueta.

<?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>

Lista blobs no contentor raiz

Para listar blobs no contentor raiz, pode usar a seguinte URL:

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

Tenha em mente que, quando lista os blobs no contentor raiz, o corpo da resposta XML não inclui uma referência explícita ao contentor raiz no campo do URL blob. Aqui está uma resposta de exemplo que lista blobs no contentor 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 Apache Arrow

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

Note

O suporte do 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 registos como uma tabela em que cada linha é um prefixo de blob ou blob e cada coluna é um campo. Campos de carimbo temporal, como Last-Modified, são apresentados aqui no formato ISO 8601. Cada tabela é seguida pelos NumberOfRecords valores e NextMarker dos metadados do esquema.

Lista de blobs e snapshots no formato Apache Arrow

Este exemplo mostra o resultado de uma operação de listagem que devolve blobs e snapshots num contentor chamado mycontainer. O URI do pedido é o seguinte:

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

A resposta inclui tanto os blobs como 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 null 2009-09-09T09:20:02Z 0x8CBFF45D8A29A19 100 texto/HTML null en-US no-cache null BlockBlob desbloqueado {Cor: azul, NúmeroMancha: 01, SomeMetadataName: SomeMetadataValue}
blob2.txt blob 2009-09-09T09:20:03.0427659Z 2009-09-09T09:20:02Z 0x8CBFF45D8B4C212 5000 application/octet-stream gzip null null null BlockBlob null {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 5000 application/octet-stream gzip null null null BlockBlob null {Cor: verde, NúmeroDeMancha: 02, NomeSomeMetaData: SomeMetadataValue}
blob2.txt blob null 2009-09-09T09:20:02Z 0x8CBFF45D8B4C212 5000 application/octet-stream gzip null null null BlockBlob desbloqueado {Cor: verde, NúmeroDeMancha: 02, NomeSomeMetaData: SomeMetadataValue}
blob3.txt blob null 2009-09-09T09:20:03Z 0x8CBFF45D911FADF 16384 image/jpeg null null null 3 PageBlob bloqueado {Cor: amarelo, NúmeroMancha: 03, SomeMetaDataName: SomeMetadataValue}

Os metadados do esquema contêm NumberOfRecords = 5 e NextMarker = vazio, 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 devolve blobs por baixo de um contentor chamado mycontainer. O URI do pedido é o seguinte:

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

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

As amostras por baixo do recipiente são as seguintes. Os primeiros quatro são devolvidos na primeira operação de listagem, porque MaxResults está definido para 4. Note que myfolder/blobA.txt e myfolder/blobB.txt estão agrupados no corpo da resposta no blobprefix registo e contam como um único blob em termos do número de entidades devolvidas. Para devolver os blobs que começam com este prefixo, faça um pedido subsequente em que o parâmetro do prefixo seja definido como myfolder/.

  • blob1.txt

  • blob2.txt

  • a minha pasta/blobA.txt

  • a minha pasta/blobB.txt

  • newblob1.txt

  • newblob2.txt

newblob2.txt será o próximo blob devolvido quando opaqueString for passado como marker parâmetro num pedido 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 texto/HTML en-US no-cache BlockBlob desbloqueado
blob2.txt blob 2009-09-27T12:18:50Z 0x8CAE7D55CF6C339 100 texto/HTML en-US no-cache BlockBlob desbloqueado
A Minha Pasta/ blobprefix null null null null null null null null
newblob1.txt blob 2009-09-27T16:31:57Z 0x8CAE7D55CF6C339 25 texto/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 Objetos
Conceitos de serviço blob
Versioning for the Armazenamento do Azure services

  • Last updated on