Listar recursos de armazenamento de Blobs

  • Artigo

A API do serviço Blob inclui operações para listar os contentores numa conta (a operação Contentores de Lista ) e os blobs num contentor (a operação Listar Blobs ). Estas operações têm algumas funcionalidades comuns que vale a pena observar.

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

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

Definir os resultados máximos

Obter resultados parciais da lista com marcadores

Filtrar resultados da lista

Percorrer o espaço de nomes do blob

Formato de resposta XML

Definir os resultados máximos

Para especificar o número máximo de resultados a devolver numa única chamada para 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 5000, o servidor devolve até ao máximo de 5000 itens. Se especificar um número máximo de resultados inferiores ou iguais a zero, o serviço devolve o código de estado 400 (Pedido Incorreto).

Obter resultados parciais da lista com marcadores

Na primeira vez que a operação de listagem é efetuada num recurso específico, 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 transmitido para a chamada subsequente para devolver o próximo conjunto de resultados (e, em seguida, o seguinte) até que a lista esteja concluída e não seja devolvido nenhum marcador.

O valor do marcador está incluído no NextMarker elemento da resposta XML. Quando o NextMarker elemento está vazio, a listagem é concluída. 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, transmita o valor devolvido na NextMarker etiqueta como o marker parâmetro no URI do pedido.

Filtrar resultados da lista

A lista de resultados pode ser filtrada ao especificar uma cadeia de prefixo no pedido com o prefix parâmetro . Em seguida, a operação de lista devolve 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 que contém o caráter de prefixo ou carateres. Por exemplo, especificar um prefixo com um valor de "c" devolve <Prefix>``c``</Prefix> dentro do XML de resposta. Por exemplo, veja a secção Listar contentores mais adiante neste tópico.

Percorrer o espaço de nomes do blob

A operação Blobs de Lista tem um parâmetro adicional delimiter que permite ao autor da chamada percorrer o espaço de nomes do blob com um delimitador configurado pelo utilizador. 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 inicia um ou mais nomes de blobs e o delimitador é o valor do parâmetro delimitador .

Pode utilizar o valor de BlobPrefix para fazer uma chamada subsequente para listar os blobs que começam com este prefixo. Especifique o valor de BlobPrefix para pedidos subsequentes. Desta forma, pode percorrer uma hierarquia virtual de blobs como se fosse um sistema de ficheiros. Por exemplo, veja Listar blobs com um delimitador mais adiante neste tópico.

Tenha em atenção que cada um BlobPrefix dos que são devolvidos conta para o resultado máximo.

Tenha também em atenção que não pode listar instantâneos de blobs se incluir um delimitador com o 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 Incorreto).

Formato de resposta XML

O resultado da lista é um documento XML cujo formato é semelhante ao apresentado nos exemplos de código posteriormente neste tópico.

O corpo da resposta inclui os valores de todos os parâmetros que foram especificados no URI do pedido como elementos no corpo da resposta.

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

Listar contentores

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 definido como 3. A NextMarker etiqueta mostra o nome do contentor 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>

Listar blobs e instantâneos

Este exemplo mostra o resultado de uma operação de listagem que devolve blobs e instantâneos num contentor com o nome 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 os blobs e os instantâneos:

<?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 abaixo de um contentor com o nome 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 blobs que começa com a mesma subcadeia, incluindo o delimitador.

Os blobs de exemplo abaixo do contentor são os seguintes. Os primeiros quatro são devolvidos na primeira operação de listagem, porque MaxResults está definido como 4. Tenha em atenção que myfolder/blobA.txt e myfolder/blobB.txt estão agrupados no corpo de 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 no qual o parâmetro de prefixo está definido como myfolder/.

  • blob1.txt

  • blob2.txt

  • myfolder/blobA.txt

  • myfolder/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>

Listar blobs no contentor de raiz

Para listar blobs no contentor de raiz, pode utilizar o seguinte URL:

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

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

Ver também

Listar Contentores
Listar Blobs
Conceitos do serviço Blob
Controlo de versões dos serviços de Armazenamento do Azure