Listando recursos de armazenamento de Blobs

Artigo
06/27/2023

A API do serviço Blob inclui operações para listar os contêineres em uma conta (a operação Listar Contêineres ) e os blobs dentro de um contêiner (a operação Listar Blobs ). Essas operações têm alguns recursos comuns a serem observados.

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

Este tópico inclui os seguintes subtópicos:

Definir o máximo de resultados

Recuperar resultados parciais da lista com marcadores

Filtrar resultados da lista

Percorrer o namespace do blob

Formato de resposta XML

Definir 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 de solicitação.

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

Recuperar resultados parciais da lista com marcadores

Na primeira vez que a operação de listagem é executada em um 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 passado para a chamada subsequente para retornar o próximo conjunto de resultados (e, em seguida, o próximo) até que a lista seja concluída e nenhum marcador seja retornado.

O valor do marcador é incluído no elemento NextMarker da resposta XML. Quando o elemento NextMarker estiver vazio, a lista estará completa. O valor de NextMarker é um valor de cadeia de caracteres opaco para o cliente.

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

Filtrar resultados da lista

A lista de resultados pode ser filtrada especificando uma cadeia de caracteres de prefixo na solicitação usando o parâmetro prefix. Em seguida, a operação de lista retornará as entidades que têm nomes que se iniciam com o prefixo. Se o parâmetro prefix for especificado no URI de solicitação, a resposta XML incluirá um elemento Prefix que contém o caractere ou os caracteres de prefixo. Por exemplo, especificar um prefixo com um valor de "c" retorna <Prefix>``c``</Prefix> dentro do XML de resposta. Para obter um exemplo, consulte a seção Listar contêineres mais adiante neste tópico.

Percorrer o namespace do blob

A operação Listar Blobs tem um parâmetro adicional delimiter que permite que o chamador percorra 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, ela retorna um elemento BlobPrefix. O elemento BlobPrefix é retornado no lugar de todos os blobs cujos nomes começam com a mesma subcadeia de caracteres até o aparecimento do caractere delimitador. O valor do BlobPrefix elemento é substring+delimiter, em que substring é a subcadeia de caracteres comum que inicia um ou mais nomes de blob 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. Desse modo, você pode atravessar uma hierarquia virtual de blobs como se fosse um sistema de arquivos. Para obter um exemplo, consulte Listar blobs com um delimitador mais adiante neste tópico.

Observe que cada BlobPrefix um que é retornado conta para o resultado máximo.

Lembre-se também de que você não poderá listar instantâneos 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 retornará um erro InvalidQueryParameter (HTTP status código 400 – Solicitação Incorreta).

Formato de resposta XML

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

O corpo da resposta inclui os valores de todos os parâmetros que foram 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 obter mais informações sobre DateTime valores, consulte Representação de 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 definido como 3. A NextMarker marca mostra o nome do contêiner que será retornado 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>

Listar blobs e instantâneos

Este exemplo mostra o resultado de uma operação de listagem que retorna blobs e instantâneos 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 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 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 marca , que representa o grupo de blobs que começam com a mesma subcadeia de caracteres, incluindo o delimitador.

Os blobs de exemplo abaixo do contêiner são os seguintes: Os quatro primeiros são retornados na primeira operação de listagem, pois é definido como MaxResults 4. Observe que myfolder/blobA.txt e myfolder/blobB.txt são agrupados no corpo da resposta na BlobPrefix marca 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 solicitação subsequente na 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 retornado é newblob2.txt. O nome do blob é fornecido na NextMarker marca .

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

Tenha em mente 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á um exemplo de resposta 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>

Confira também

Listar contêineres
Listar Blobs
Conceitos do Serviço Blob
Controle de versão para os serviços de Armazenamento do Azure

Listando recursos de armazenamento de Blobs

Definir o máximo de resultados

Recuperar resultados parciais da lista com marcadores

Filtrar resultados da lista

Percorrer o namespace do blob

Formato de resposta XML

Listar contêineres

Listar blobs e instantâneos

Listar blobs com um delimitador

Listar blobs no contêiner raiz

Confira também

Recursos adicionais