Listado de recursos de almacenamiento de Blob

La API de servicios Blob incluye operaciones para listar los contenedores dentro de una cuenta (la operación Listar Contenedores ) y los blobs dentro de un contenedor (la operación Listar Blobs ). Estas operaciones tienen algunas características comunes que merecen ser mencionadas.

Una operación de listado devuelve una respuesta que contiene total o parte de la lista solicitada. La operación devuelve las entidades en orden alfabético.

Este tema contiene los siguientes subtemas:

Establecer resultados máximos

Recuperar resultados parciales de la lista con marcadores

Resultados de listas de filtros

Atraviesa el espacio de nombres del blob

Formato de respuesta XML

Formato de respuesta Apache Arrow

Establecer resultados máximos

Para especificar el número máximo de resultados que se deben devolver en una sola llamada a una operación de listado, especifique un valor para el maxresults parámetro en el URI de la solicitud.

Si no se especifica el número máximo de resultados en la solicitud o si es superior a 5.000, el servidor devuelve hasta un máximo de 5.000 elementos. Si especificas un número máximo de resultados igual o menor que cero, el servicio devuelve el código de estado 400 (Solicitud mala).

Recuperar resultados parciales de la lista con marcadores

La primera vez que se realiza la operación de listado contra un recurso concreto, la respuesta puede contener todos los resultados, o puede contener un subconjunto de los resultados y un valor de marcador. El valor del marcador puede pasarse a la llamada siguiente para devolver el siguiente conjunto de resultados (y luego el siguiente) hasta que la lista esté completa y no se devolva ningún marcador.

El valor del marcador se devuelve como NextMarker. En una respuesta XML, NextMarker es un elemento del cuerpo de la respuesta. En una respuesta de Apache Arrow List Blobs, NextMarker es un campo en los metadatos del esquema. Cuando NextMarker está vacío, el anuncio está completo. El valor de NextMarker es un valor de cadena que es opaco para el cliente.

Para devolver el siguiente conjunto de resultados en una operación posterior, pasa el valor devuelto como NextMarkermarker parámetro en el URI de la solicitud.

Resultados de listas de filtros

La lista de resultados puede filtrarse especificando una cadena de prefijo en la solicitud usando el prefix parámetro. La operación de lista devuelve entonces las entidades que tienen nombres que comienzan con ese prefijo. Si el prefix parámetro se especifica en el URI de la solicitud, el XML de respuesta incluye un Prefix elemento que contiene el carácter prefijo o caracteres. Por ejemplo, especificar un prefijo con el valor "c" devuelve <Prefix>``c``</Prefix> dentro del XML de respuesta. Por ejemplo, consulta la sección de Contenedores de lista más adelante en este tema.

Atraviesa el espacio de nombres del blob

La operación List Blobs tiene un parámetro adicional delimiter que permite al llamador recorrer el espacio de nombres del blob utilizando un delimitador configurado por el usuario. El delimitador puede ser un solo carácter o una cadena. Cuando la solicitud incluye este parámetro, la operación devuelve un elemento BlobPrefix. El BlobPrefix elemento se devuelve en lugar de todas las manchas con nombres que comienzan con la misma subcadena hasta la aparición del carácter delimitador. El valor del BlobPrefix elemento es subcadena+delimitador, donde subcadena es la subcadena común que comienza uno o más nombres de blobs, y delimitador es el valor del parámetro delimitador .

Puede usar el valor de BlobPrefix para realizar una llamada posterior para enumerar los blobs que comienzan por este prefijo. Especifica el valor de BlobPrefix para solicitudes posteriores. De este modo, puede atravesar una jerarquía virtual de blobs como si fuera un sistema de archivos. Por ejemplo, véase Listar blobs con un delimitador más adelante en este tema.

Ten en cuenta que cada BlobPrefix respuesta que se devuelve cuenta para el resultado máximo.

También ten en cuenta que no puedes listar snapshots de blob si incluyes un delimitador con la petición. Si especificas un valor para el delimiter parámetro y también lo include=snapshots estableces, el servicio Blob devuelve un error InvalidQueryParameter (código de estado HTTP 400 – Solicitud incorrecta).

Formato de respuesta XML

La salida de la lista es un documento XML cuyo formato es similar a los mostrados en los ejemplos de código más adelante en este tema.

El cuerpo de respuesta incluye los valores de todos los parámetros especificados en el URI de la solicitud como elementos dentro del cuerpo de respuesta.

El DateTime valor que se devuelve en el Last-Modified elemento está en formato RFC 1123. Para más información sobre DateTime valores, véase Representación de valores de fecha/hora en cabeceras.

Enumerar contenedores

Este ejemplo muestra el resultado de una operación de listado que devuelve dos contenedores. El URI de la solicitud es el siguiente:

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

El prefijo "c" se especificó para filtrar la lista. El número máximo de resultados que se devolvieron se fijó en 3. La NextMarker etiqueta muestra el nombre del contenedor que se devolverá en una operación posterior de listado.

<?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 instantáneas

Este ejemplo muestra el resultado de una operación de listado que devuelve blobs e instantáneas en un contenedor llamado mycontainer. El URI de la solicitud es el siguiente:

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

La respuesta incluye tanto los blobs como las instantáneas:

<?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 con un delimitador

Este ejemplo muestra el resultado de una operación de listado que devuelve blobs debajo de un contenedor llamado mycontainer. El URI de la solicitud es el siguiente:

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

En este caso, el delimiter parámetro se especifica como /. El cuerpo de respuesta incluye la BlobPrefix etiqueta, que representa el grupo de manchas que comienzan con la misma subcadena, incluyendo el delimitador.

Las muestras de muestra bajo el recipiente son las siguientes. Los primeros cuatro se devuelven en la primera operación de listado, porque MaxResults está fijado en 4. Ten en cuenta que myfolder/blobA.txt y myfolder/blobB.txt están agrupados en el cuerpo de respuesta de la BlobPrefix etiqueta y cuentan como un solo blob en función del número de entidades devueltas. Para devolver los blobs que comienzan con este prefijo, haz una solicitud posterior en la que el parámetro prefijo se establezca como myfolder/.

  • blob1.txt

  • blob2.txt

  • micarpeta/blobA.txt

  • micarpeta/blobB.txt

  • newblob1.txt

  • newblob2.txt

El siguiente blob que se devuelve es newblob2.txt. El nombre del blob aparece en la 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 en el contenedor raíz

Para listar los blobs en el contenedor raíz, puedes usar la siguiente URL:

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

Ten en cuenta que cuando listas los blobs en el contenedor raíz, el cuerpo de respuesta XML no incluye una referencia explícita al contenedor raíz en el campo del URL blob. Aquí tienes una respuesta de ejemplo que lista los blobs en el contenedor raíz:

  
<?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 respuesta Apache Arrow

A partir de la versión 2026-06-06, la operación List Blobs también puede devolver resultados en formato Apache Arrow . La operación List Containers no soporta Apache Arrow en este momento.

Note

El soporte de Apache Arrow para List Blobs está actualmente en vista previa pública.

La salida de la lista es un flujo binario de Apache Arrow. Cada ejemplo en este tema muestra el lote de registros como una tabla en la que cada fila es un prefijo de blob o blob y cada columna es un campo. Los campos de marca de tiempo, como Last-Modified, se muestran aquí en formato ISO 8601. Cada tabla va seguida de los NumberOfRecords valores y NextMarker de los metadatos del esquema.

Lista de blobs e instantáneas en formato Apache Arrow

Este ejemplo muestra el resultado de una operación de listado que devuelve blobs e instantáneas en un contenedor llamado mycontainer. El URI de la solicitud es el siguiente:

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

La respuesta incluye tanto los blobs como las instantáneas:

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 mancha nulo 2009-09-09T09:20:02Z 0x8CBFF45D8A29A19 100 text/html nulo es-ES no-cache nulo BlockBlob desbloqueado {Color: azul, NúmeroMancha: 01, NombreDeAlgunosMetadatos: ValorAlgunosDatos}
blob2.txt mancha 2009-09-09T09:20:03.0427659Z 2009-09-09T09:20:02Z 0x8CBFF45D8B4C212 5000 application/octet-stream gzip nulo nulo nulo BlockBlob nulo {Color: green, BlobNumber: 02, SomeMetadataName: SomeMetadataValue, x-ms-invalid-name: nasdf$@#$$}
blob2.txt mancha 2009-09-09T09:20:03.1587543Z 2009-09-09T09:20:02Z 0x8CBFF45D8B4C212 5000 application/octet-stream gzip nulo nulo nulo BlockBlob nulo {Color: verde, NúmeroMancha: 02, SomeMetadataName: SomeMetadataValue}
blob2.txt mancha nulo 2009-09-09T09:20:02Z 0x8CBFF45D8B4C212 5000 application/octet-stream gzip nulo nulo nulo BlockBlob desbloqueado {Color: verde, NúmeroMancha: 02, SomeMetadataName: SomeMetadataValue}
blob3.txt mancha nulo 2009-09-09T09:20:03Z 0x8CBFF45D911FADF 16384 image/jpeg nulo nulo nulo 3 PageBlob bloqueado {Color: amarillo, NombreMancha: 03, NombreDeAlgunosMetadatos: ValorAlgunosDatos}

Los metadatos del esquema contienen NumberOfRecords = 5 y NextMarker = vacíos, lo que indica que el listado está completo.

Lista de blobs con delimitador en formato Apache Arrow

Este ejemplo muestra el resultado de una operación de listado que devuelve blobs debajo de un contenedor llamado mycontainer. El URI de la solicitud es el siguiente:

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

En este caso, el delimiter parámetro se especifica como /. El cuerpo de respuesta incluye un registro con ResourceType set en blobprefix, que representa el grupo de manchas que comienzan con la misma subcadena, incluyendo el delimitador.

Las muestras de muestra bajo el recipiente son las siguientes. Los primeros cuatro se devuelven en la primera operación de listado, porque MaxResults está fijado en 4. Ten en cuenta que myfolder/blobA.txt y myfolder/blobB.txt están agrupados en el cuerpo de respuesta del blobprefix registro y cuentan como un solo blob en función del número de entidades devueltas. Para devolver los blobs que comienzan con este prefijo, haz una solicitud posterior en la que el parámetro prefijo se establezca como myfolder/.

  • blob1.txt

  • blob2.txt

  • micarpeta/blobA.txt

  • micarpeta/blobB.txt

  • newblob1.txt

  • newblob2.txt

newblob2.txt será el siguiente blob que se devuelva cuando opaqueString se pase como parámetro marker en una petición posterior.

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

Los metadatos del esquema contienen NumberOfRecords = 4 y NextMarker = opaqueString.

Véase también

Enumerador de contenedores
Enumeración de blobs
Conceptos de servicio blob
Versioning for the Azure Storage services

  • Last updated on