List Blobs

La List Blobs operación devuelve una lista de los blobs del contenedor especificado.

Solicitud

La solicitud List Blobs se puede construir como sigue. Se recomienda HTTPS. Reemplace myaccount por el nombre de la cuenta de almacenamiento:

URI del servicio de almacenamiento emulado

Al realizar una solicitud en el servicio de almacenamiento emulado, especifique el nombre de host del emulador y el puerto del servicio Blob como 127.0.0.1:10000, seguido del nombre de la cuenta de almacenamiento emulado:

Para obtener más información, vea Using the Azure Storage Emulator for Development and Testing.

Parámetros de identificador URI

Se pueden especificar los parámetros adicionales siguientes en el URI.

Encabezados de solicitud

En la tabla siguiente se describen los encabezados de solicitud requeridos y opcionales.

Cuerpo de la solicitud

Ninguno.

Solicitud de ejemplo

Consulte Enumeración de recursos de blob para obtener una solicitud de ejemplo.

Respuesta

La respuesta incluye un código de estado HTTP, un conjunto de encabezados de respuesta y un cuerpo de respuesta en formato XML.

Código de estado

Una operación correcta devuelve el código de estado 200 Correcto.

Para obtener información sobre los códigos de estado, vea Códigos de estado y de error.

Encabezados de respuesta

La respuesta para esta operación incluye los encabezados siguientes. La respuesta también puede incluir otros encabezados HTTP estándar. Todos los encabezados estándar se ajustan a la especificación del protocolo HTTP/1.1.

Cuerpo de la respuesta

El formato de la respuesta XML es el siguiente.

Tenga en cuenta que los elementos Prefix, Marker, MaxResults y Delimiter solo están presentes si se especificaron en el URI de solicitud. El elemento NextMarker tiene un valor solo si los resultados de la lista no están completos.

Las instantáneas, los metadatos del blob y los blobs sin confirmar se incluyen en la respuesta solo si se especifican mediante el parámetro include en el URI de solicitud.

En la versión 2009-09-19 y versiones más recientes, las propiedades del blob se encapsulan en un elemento Properties.

A partir de la versión 2009-09-19, List Blobs devuelve en el cuerpo de respuesta los elementos siguientes cuyo nombre ha cambiado:

• Last-Modified (anteriormente LastModified)

• Content-Length (anteriormente Size)

• Content-Type (anteriormente ContentType)

• Content-Encoding (anteriormente ContentEncoding)

• Content-Language (anteriormente ContentLanguage)

El elemento Content-MD5 aparece para los blobs creados con la versión 2009-09-19 y versiones más recientes. En la versión 2012-02-12 y versiones posteriores, el Blob service calcula el valor al cargar un blob mediante Put Blob , pero no lo calcula al crear un blob mediante Content-MD5 Put Block List. Puede establecer explícitamente el valor al crear el blob o llamando a Content-MD5 las operaciones Put Block List o Set Blob Properties.

Para las versiones de 2009-09-19 y posteriores, pero anteriores a la versión 2015-02-21, la llamada a en un contenedor que incluye blobs en anexos producirá un error con el código de estado List Blobs 409 (FeatureVersionMismatch) si el resultado de la lista contiene un blob en anexos.

LeaseState y LeaseDuration solo aparecen en la versión 2012-02-12 y posteriores.

CopyId, CopyStatus, CopySource, CopyProgress, CopyCompletionTime y CopyStatusDescription solo aparecen en la versión 2012-02-12 y versiones posteriores, cuando esta operación incluye el parámetro include={copy}. Estos elementos no aparecen si el blob no ha sido nunca el destino de una operación Copy Blob, o si el blob se ha modificado después de una operación Copy Blob finalizada, mediante Set Blob Properties, Put Blob o Put Block List. Estos elementos tampoco aparecen con un blob creado por Copy Blob antes de la versión 2012-02-12.

En la versión 2013-08-15 y posteriores, el elemento EnumerationResults contiene un atributo ServiceEndpoint que especifica el extremo del blob y un campo ContainerName que especifica el nombre del contenedor. En las versiones anteriores, estos dos atributos estaban combinados en el campo ContainerName. Además, en la versión 2013-08-15 y posteriores, se ha quitado el elemento Url de Blob.

Para la versión 2015-02-21 y posteriores, devuelve blobs de todos los tipos List Blobs (blobs en bloques, páginas y anexos).

Para la versión 2015-12-11 y posteriores, List Blobs devuelve el ServerEncrypted elemento . Este elemento se establece en true si los metadatos de blob y aplicación están completamente cifrados y, de lo false contrario, .

Para la versión 2016-05-31 y posteriores, devuelve el elemento para las instantáneas y blobs de copia incremental con el valor List Blobs IncrementalCopy establecido en true .

Para la versión 2017-04-17 y posteriores, devuelve el elemento si se ha establecido explícitamente List Blobs AccessTier un nivel de acceso. Para obtener una lista de los niveles de blob en páginas Premium permitidos, consulte Discos administrados Premium Storage alto rendimiento para máquinas virtuales. En el caso Storage o De uso general cuentas v2, los valores válidos son Hot / Cool / Archive . Si el blob está en estado pendiente de rehidratación, ArchiveStatus el elemento se devuelve con uno de los valores válidos. rehydrate-pending-to-hot / rehydrate-pending-to-cool Para obtener información detallada sobre los niveles de blobs en bloques, consulte Niveles de almacenamiento de acceso es decir,acceso es cool y de archivo.

Para la versión 2017-04-17 y posteriores, devuelve el elemento en Blob List Blobs Storage o De uso general cuentas AccessTierInferred v2. Si el blob en bloques no tiene establecido el nivel de acceso, se deduce el nivel de las propiedades de la cuenta de almacenamiento y este valor se establece en true . Este encabezado solo está presente si el nivel se deduce de la propiedad account. Para obtener información detallada sobre los niveles de blobs en bloques, consulte Niveles de almacenamiento de acceso es decir,acceso es cool y de archivo.

Para la versión 2017-04-17 y posteriores, devuelve el elemento en Blob List Blobs Storage o De uso general cuentas AccessTierChangeTime v2. Esto solo se devuelve si se ha establecido alguna vez el nivel en el blob en bloques. El formato de la fecha sigue las convenciones de RFC 1123. Para obtener más información, vea Representación de Date-Time valores en encabezados. Para obtener información detallada sobre los niveles de blobs en bloques, consulte Niveles de almacenamiento de acceso es decir,acceso es cool y de archivo.

Para la versión 2017-07-29 y posteriores, y aparecen Deleted cuando esta operación incluye el parámetro DeletedTime RemainingRetentionDays include={deleted} . Estos elementos no aparecen si no se eliminó este blob. Estos elementos aparecen para blobs o instantáneas que se eliminan con DELETE la operación cuando se ha habilitado la característica de eliminación temporal. Deleted Element se establece en true para blobs e instantáneas que se eliminan temporalmente. Deleted-Time corresponde a la hora en que se eliminó el blob. RemainingRetentionDays indica el número de días después de los cuales Blob service eliminará permanentemente el blob eliminado temporalmente.

Para la versión 2017-11-09 y posteriores, devuelve la hora a la Creation-Time que se creó este blob.

Para la versión 2019-02-02 y posteriores, devuelve el elemento si el blob está cifrado con una List Blobs clave proporcionada por el CustomerProvidedKeySha256 cliente. El valor se establecerá en el hash SHA-256 de la clave usada para cifrar el blob. Además, si la operación incluye el parámetro y hay metadatos de aplicación presentes en un blob cifrado con una clave proporcionada por el cliente, el elemento tendrá un atributo para indicar que el blob tiene metadatos que no se pueden descifrar como parte de la include={metadata} Metadata Encrypted="true" List Blobs operación. Llame a Get Blob Properties (Obtener propiedades de blob) u Get Blob Metadata (Obtener metadatos de blob) con la clave proporcionada por el cliente para acceder a los metadatos de estos blobs.

Para la versión 2019-02-02 y posteriores, devuelve el elemento si el blob está List Blobs cifrado con un ámbito de EncryptionScope cifrado. El valor se establecerá en el nombre del ámbito de cifrado utilizado para cifrar el blob. Si la operación incluye el parámetro , los metadatos de la aplicación en el blob se descifrarán de forma transparente include={metadata} y estarán disponibles en el Metadata elemento .

Para la versión 2019-12-12 y posteriores, devuelve el elemento en las cuentas de Blob Storage o De uso general v2 si el objeto está en estado pendiente de List Blobs RehydratePriority rehidratación. Los valores válidos son High / Standard . Para obtener información detallada sobre los niveles de blobs en bloques, consulte Niveles de almacenamiento de acceso es decir,acceso es cool y de archivo.

Para la versión 2019-12-12 y posteriores, devuelve el elemento para blobs y versiones de blob generadas cuando el control de versiones está habilitado en List Blobs VersionId la cuenta.

Para la versión 2019-12-12 y posteriores, devuelve el elemento de la versión actual del blob con el valor establecido en , para diferenciarlo de las versiones generadas automáticamente de solo List Blobs IsCurrentVersion true lectura.

Para la versión 2019-12-12 y posteriores, devuelve el elemento List Blobs TagCount para blobs con cualquier etiqueta. El Tags elemento solo aparece cuando esta operación incluye el parámetro include={tags} . Estos elementos no aparecen si no hay etiquetas en el blob.

Para la versión 2019-12-12 y posteriores, devuelve el elemento List Blobs Sealed para Append Blobs. El elemento solo aparece cuando se ha sellado Sealed el blob Append. Estos elementos no aparecen si el blob en anexos no está sellado.

Para la versión 2020-02-10 y posteriores, List Blobs devuelve el LastAccessTime elemento . Los elementos muestran cuándo se ha accedido por última vez a los datos del blob según la directiva de seguimiento de la hora de último acceso de la cuenta de almacenamiento. El elemento no se devolverá si la cuenta de almacenamiento no tiene una directiva de seguimiento de hora de último acceso o la directiva está deshabilitada. Para obtener información sobre cómo establecer la directiva de seguimiento de hora del último acceso de la cuenta, consulte Api de Blob Service. El elemento no realiza un seguimiento de la última vez que se tiene acceso a LastAccessTime los metadatos del blob.

Para la versión 2020-06-12 y posteriores, devuelve los elementos List Blobs y cuando esta operación incluye el parámetro ImmutabilityPolicyUntilDate ImmutabilityPolicyMode include={immutabilitypolicy} .

Para la versión 2020-06-12 y posteriores, devuelve el elemento List Blobs cuando esta operación incluye el parámetro LegalHold include={legalhold} .

Para la versión 2020-06-12 y posteriores, para las cuentas con un espacio de nombres jerárquico habilitado, devuelve el elemento , y cuando la solicitud List Blobs Owner contiene el parámetro Group Permissions Acl include={permissions} . Tenga en cuenta que el elemento será una lista combinada de acceso y Acl acl predeterminadas que se han establecido en el archivo o directorio.

Para la versión 2020-08-04 y posteriores, para las cuentas habilitadas para espacio de nombres jerárquico, devuelve el elemento List Blobs DeletionId para los blobs eliminados. DeletionId es un identificador de 64 bits sin signo que identifica de forma única una ruta de acceso eliminada temporalmente para distinguirla de otros blobs eliminados con la misma ruta de acceso.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="http://myaccount.blob.core.windows.net/"  ContainerName="mycontainer">  
  <Prefix>string-value</Prefix>  
  <Marker>string-value</Marker>  
  <MaxResults>int-value</MaxResults>  
  <Delimiter>string-value</Delimiter>  
  <Blobs>  
    <Blob>  
      <Name>blob-name</name>  
      <Snapshot>date-time-value</Snapshot>  
      <VersionId>date-time-vlue</VersionId>
      <IsCurrentVersion>true</IsCurrentVersion>
      <Deleted>true</Deleted>
      <Properties> 
        <Creation-Time>date-time-value</Creation-Time>
        <Last-Modified>date-time-value</Last-Modified>  
        <Etag>etag</Etag>
        <Owner>owner user id</Owner>
        <Group>owning group id</Group>
        <Permissions>permission string</Permissions>
        <Acl>access control list</Acl>
        <Content-Length>size-in-bytes</Content-Length>  
        <Content-Type>blob-content-type</Content-Type>  
        <Content-Encoding />  
        <Content-Language />  
        <Content-MD5 />  
        <Cache-Control />  
        <x-ms-blob-sequence-number>sequence-number</x-ms-blob-sequence-number>  
        <BlobType>BlockBlob|PageBlob|AppendBlob</BlobType>  
        <AccessTier>tier</AccessTier>  
        <LeaseStatus>locked|unlocked</LeaseStatus>  
        <LeaseState>available | leased | expired | breaking | broken</LeaseState>  
        <LeaseDuration>infinite | fixed</LeaseDuration>  
        <CopyId>id</CopyId>  
        <CopyStatus>pending | success | aborted | failed </CopyStatus>  
        <CopySource>source url</CopySource>  
        <CopyProgress>bytes copied/bytes total</CopyProgress>  
        <CopyCompletionTime>datetime</CopyCompletionTime>  
        <CopyStatusDescription>error string</CopyStatusDescription>  
        <ServerEncrypted>true</ServerEncrypted> 
        <CustomerProvidedKeySha256>encryption-key-sha256</CustomerProvidedKeySha256>
        <EncryptionScope>encryption-scope-name</EncryptionScope>
        <IncrementalCopy>true</IncrementalCopy>
        <AccessTierInferred>true</AccessTierInferred>
        <AccessTierChangeTime>datetime</AccessTierChangeTime>
        <DeletedTime>datetime</DeletedTime>
        <RemainingRetentionDays>no-of-days</RemainingRetentionDays>
        <TagCount>number of tags between 1 to 10</TagCount>
        <RehydratePriority>rehydrate priority</RehydratePriority>
      </Properties>  
      <Metadata>     
        <Name>value</Name>  
      </Metadata>  
      <Tags>
          <TagSet>
              <Tag>
                  <Key>TagName</Key>
                  <Value>TagValue</Value>
              </Tag>
          </TagSet>
      </Tags>
      <OrMetadata />
    </Blob>  
    <BlobPrefix>  
      <Name>blob-prefix</Name>  
    </BlobPrefix>  
  </Blobs>  
  <NextMarker />  
</EnumerationResults>  

Respuesta de ejemplo

Consulte Enumeración de recursos de blob para obtener una respuesta de ejemplo.

Autorización

Si se establece la lista de control de acceso (ACL) del contenedor para permitir el acceso anónimo al contenedor, cualquier cliente puede llamar a esta operación. En caso contrario, esta operación la puede realizar el propietario de la cuenta y cualquiera que disponga de una firma de acceso compartido con permiso para enumerar blobs en un contenedor.

Comentarios

Propiedades del blob en la respuesta

Si ha solicitado la inclusión de blobs sin confirmar en la enumeración, tenga en cuenta que algunas propiedades no se establecen hasta que se confirma el blob, de modo que es posible que no se devuelvan en la respuesta.

El elemento x-ms-blob-sequence-number solo se devuelve para los blobs en páginas.

El OrMetadata elemento solo se devuelve para blobs en bloques.

En los blobs en páginas, el valor devuelto en el elemento Content-Length corresponde al valor del encabezado x-ms-blob-content-length del blob.

El elemento Content-MD5 solo aparece en el cuerpo de respuesta si se ha establecido en el blob con la versión 2009-09-19 o versiones posteriores. Puede establecer la propiedad Content-MD5 cuando se crea el blob o llamando a Set Blob Properties. En la versión 2012-02-12 y en las versiones más recientes, Put Blob establece el valor MD5 de un blob en bloques incluso si la solicitud Put Blob no incluye un encabezado MD5.

Metadatos en la respuesta

El elemento Metadata está presente solo si se especificó el parámetro include=metadata en el URI. Dentro del elemento Metadata, el valor de cada par nombre-valor aparece en un elemento que corresponde al nombre del par.

Tenga en cuenta que los metadatos solicitados con este parámetro deben almacenarse de acuerdo con las restricciones de nomenclatura impuestas por la versión 2009-09-19 del servicio Blob. A partir de esta versión, todos los nombres de metadatos deben cumplir las convenciones de nomenclatura para los identificadores de C#.

Si un par nombre-valor de metadatos infringe las restricciones de nomenclatura impuestas por la versión 2009-09-19, el cuerpo de respuesta indica el nombre problemático en un elemento x-ms-invalid-name, tal como se muestra en el fragmento XML siguiente:

  
…  
<Metadata>  
  <MyMetadata1>first value</MyMetadata1>  
  <MyMetadata2>second value</MyMetadata2>  
  <x-ms-invalid-name>invalid-metadata-name</x-ms-invalid-name>  
</Metadata>  
…  
  

Etiquetas en la respuesta

El Tags elemento solo está presente si el parámetro se include=tags especificó en el URI y si hay etiquetas en el blob. Dentro del elemento , se devuelven hasta 10 elementos, cada uno de los que contiene y de las etiquetas de índice de TagSet Tag key value blobs definidas por el usuario. No se garantiza el orden de las etiquetas en la respuesta.

Los Tags elementos y no se TagCount devuelven si no hay etiquetas en el blob.

El servicio de almacenamiento mantiene una fuerte coherencia entre un blob y sus etiquetas, pero el índice secundario es finalmente coherente. Las etiquetas pueden estar visibles en una respuesta a Enumerar blobs antes de que sean visibles para las operaciones buscar blobs por etiquetas.

Instantáneas en la respuesta

Las instantáneas aparecen en la respuesta solo si se especificó el parámetro include=snapshots en el URI. Las instantáneas que aparecen en la respuesta no incluyen el elemento LeaseStatus, ya que las instantáneas no pueden tener concesiones activas.

Si llama a List Blobs con un delimitador, no podrá incluir instantáneas en la enumeración. Las solicitudes que incluyan ambos devolverán un error InvalidQueryParameter (código de estado HTTP 400 – Solicitud incorrecta).

Blobs sin confirmar en la respuesta

Los blobs sin confirmar aparecen en la respuesta solo si se especificó el parámetro include=uncommittedblobs en el URI. Los blobs sin confirmar que aparecen en la respuesta no incluyen ninguno de los elementos siguientes:

• Last-Modified

• Etag

• Content-Type

• Content-Encoding

• Content-Language

• Content-MD5

• Cache-Control

• Metadata

Blobs eliminados en la respuesta

Los blobs eliminados solo se muestran en la respuesta si include=deleted el parámetro se especificó en el URI. Los blobs eliminados enumerados en la respuesta no incluyen los elementos Lease, ya que los blobs eliminados no pueden tener concesiones activas.

Las instantáneas eliminadas se incluyen en la respuesta de la lista include=deleted,snapshot si se especificó en el URI.

Metadatos de replicación de objetos en la respuesta

El elemento está presente cuando se ha evaluado una directiva de replicación de objetos en un blob y la llamada a List Blobs se realizó con la versión OrMetadata 2019-12-12 o posterior. Dentro del elemento OrMetadata, el valor de cada par nombre-valor aparece en un elemento que corresponde al nombre del par. El formato de nombre es , donde es un GUID que representa el identificador de la directiva de replicación de objetos en la cuenta de almacenamiento y es un GUID que representa el identificador de regla or-{policy-id}_{rule-id} en el contenedor de {policy-id} {rule-id} almacenamiento. Los valores válidos son complete / failed .

  
…  
<OrMetadata>  
  <or-e524bba7-4323-4b93-91f8-d09d5d0b7057_d86c51de-ef02-4264-bdcf-dcd389a6c7ac>complete</or-e524bba7-4323-4b93-91f8-d09d5d0b7057_d86c51de-ef02-4264-bdcf-dcd389a6c7ac>  
  <or-2b302b5d-fcd5-44d6-a5ed-455bf27e17ea_4a398ff5-2a89-4090-879b-10248f23428e>failed</or-2b302b5d-fcd5-44d6-a5ed-455bf27e17ea_4a398ff5-2a89-4090-879b-10248f23428e>  
</OrMetadata>  
…  
  

Directiva de inmutabilidad en la respuesta

Los ImmutabilityPolicyUntilDate elementos , solo están ImmutabilityPolicyMode presentes si el parámetro se include=immutabilitypolicy especificó en el URI.

<Properties> 
   <ImmutabilityPolicyUntilDate>date-time-value</ImmutabilityPolicyUntilDate>   
   <ImmutabilityPolicyMode>unlocked | locked </ImmutabilityPolicyMode>  
 </Properties> 

Retención legal en la respuesta

El elemento LegalHold está presente solo si se especificó el parámetro include=legalhold en el URI.

 <Properties> 
   <LegalHold>true | false </LegalHold>  
 </Properties> 

Devolver conjuntos de resultados mediante un valor de marcador

Si especifica un valor para el parámetro maxresults y el número de blobs que se van a devolver supera este valor, o supera el valor predeterminado de maxresults, el cuerpo de respuesta contendrá un elemento NextMarker que indica el siguiente blob que se debe devolver en una solicitud subsiguiente. Para devolver el siguiente conjunto de elementos, especifique el valor de NextMarker como el parámetro de marcador en el URI para la solicitud siguiente.

Tenga en cuenta que el valor de NextMarker se debe tratar como opaco.

Utilizar un delimitador para recorrer el espacio de nombres del blob

El parámetro delimiter permite al autor de la llamada recorrer el espacio de nombres del blob utilizando un delimitador configurado por el usuario. De esta manera, puede recorrer una jerarquía virtual de blobs como si fuera un sistema de archivos. El delimitador puede ser un carácter o una cadena. Si la solicitud incluye este parámetro, la operación devuelve un elemento BlobPrefix. El elemento BlobPrefix se devuelve en lugar de todos los blobs cuyos nombres comienzan por la misma subcadena hasta que aparece el carácter delimitador. El valor del elemento es BlobPrefix substring+delimiter, donde substring es la subcadena común que comienza uno o varios nombres de blob, y delimiter es el valor del parámetro delimitador.

Puede utilizar el valor de BlobPrefix para hacer una llamada subsiguiente que permita enumerar los blobs que comienzan por este prefijo, especificando el valor de BlobPrefix para el parámetro prefix en el URI de solicitud.

Tenga en cuenta que cada elemento BlobPrefix devuelto se tiene en cuenta para calcular el número máximo de resultados, de la misma manera que los elementos Blob.

Los blobs se muestran en el cuerpo de respuesta en orden alfabético, con las letras mayúsculas en primer lugar.

Errores de copia en CopyStatusDescription

CopyStatusDescription contiene más información sobre el error de Copy Blob.

• Cuando se produce un error en un intento de copia y Blob service sigue reintentando la operación, CopyStatus se establece en pending, y el texto de CopyStatusDescription describe el error que puede haber ocurrido durante el último intento de copia.

• Si CopyStatus se establece en failed, el texto de CopyStatusDescription describe el error que provocó la operación de copia incorrecta.

En la tabla siguiente se describen los tres campos de cada valor de CopyStatusDescription.

En la tabla siguiente se describen los valores de CopyStatus y CopyStatusDescription en escenarios de error comunes.

Vea también

Códigos de estado y error
Códigos de error del servicio BLOB