VENTAS: 1-800-867-1389

List Blobs

Actualizado: febrero de 2014

La operación List Blobs enumera la lista de blobs del contenedor especificado.

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

 

Método URI de solicitud Versión de HTTP

GET

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

HTTP/1.1

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:

 

Método URI de solicitud Versión de HTTP

GET

http://127.0.0.1:10000/devstoreaccount1/mycontainer?restype=container&comp=list

HTTP/1.1

Para obtener más información, vea Uso del emulador de almacenamiento de Azure para desarrollo y prueba.

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

 

Parámetro Descripción

prefix

Opcional. Filtra los resultados para devolver solo los blobs cuyos nombres empiezan por el prefijo especificado.

delimiter

Opcional. Si la solicitud incluye este parámetro, la operación devuelve un elemento BlobPrefix en el cuerpo de respuesta que actúa como un marcador de posición para todos los blobs cuyos nombres comienzan por la misma subcadena hasta que aparece el carácter delimitador. El delimitador puede ser un carácter o una cadena.

marker

Opcional. Valor de cadena que identifica la parte de la lista que se va a devolver con la siguiente operación de lista. La operación devuelve un valor de marcador en el cuerpo de respuesta si la lista devuelta no estaba completa. Este valor de marcador se puede utilizar en una llamada subsiguiente para solicitar el siguiente conjunto de elementos de lista.

El valor de marcador es opaco para el cliente.

maxresults

Opcional. Especifica el número máximo de blobs que se van a devolver, incluidos todos los elementos BlobPrefix. Si la solicitud no especifica maxresults, o especifica un valor superior a 5.000, el servidor devolverá un máximo de 5.000 elementos.

Si se establece maxresults en un valor menor o igual que cero, se devolverá el código de respuesta de error 400 (Solicitud incorrecta).

include={snapshots,metadata,uncommittedblobs,copy}

Opcional. Especifica uno o más conjuntos de datos que se deben incluir en la respuesta:

  • snapshots: especifica que se deben incluir las instantáneas en la enumeración. Las instantáneas aparecen ordenadas de más antigua a más reciente en la respuesta.

  • metadata: especifica que se deben devolver los metadatos del blob en la respuesta.

  • uncommittedblobs: especifica que se deben incluir en la respuesta los blobs para los que se han cargado bloques, pero que no se han confirmado mediante Put Block List.

  • copy: versión 2012-02-12 y versiones más recientes. Especifica que se deben incluir en la respuesta los metadatos relacionados con cualquier operación Copy Blob actual o previa.

Si desea especificar varias de estas opciones en el URI, debe separarlas mediante una coma codificada para URL ("%82").

timeout

Opcional. El parámetro timeout se expresa en segundos. Para obtener más información, vea Establecer los tiempos de espera para las operaciones del servicio Blob.

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

 

Encabezado de solicitud Descripción

Authorization

Requerido. Especifica el esquema de autenticación, el nombre de la cuenta y la firma. Para obtener más información, vea Autenticación para los servicios de almacenamiento de Azure.

Date O bien x-ms-date

Requerido. Especifica la hora universal coordinada (UTC) para la solicitud. Para obtener más información, vea Autenticación para los servicios de almacenamiento de Azure.

x-ms-version

Obligatorio para todas las solicitudes autenticadas, opcional para las solicitudes anónimas. Especifica la versión de la operación que se utiliza para esta solicitud. Para obtener más información, vea Control de versiones de los servicios de almacenamiento de Azure.

x-ms-client-request-id

Opcional. Proporciona un valor opaco generado por el cliente con un límite de caracteres de 1 KB que se graba en los registros de análisis cuando el registro de análisis de almacenamiento está habilitado. Se recomienda encarecidamente usar este encabezado para correlacionar las actividades del lado cliente con las solicitudes recibidas por el servidor. Para obtener más información, vea Acerca del registro del análisis de almacenamiento y Registro de Azure: usar registros para realizar el seguimiento de las solicitudes de almacenamiento.

Para obtener una solicitud de ejemplo, vea Enumerar los recursos de blob.

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

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

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

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 cumplen la especificación del protocolo HTTP/1.1.

 

Encabezado de respuesta Descripción

Content-Type

Especifica el formato en el que se devuelven los resultados. Actualmente, este valor es application/xml.

x-ms-request-id

Este encabezado identifica de forma única la solicitud que se realizó y se puede utilizar para solucionar problemas relacionados con esta. Para obtener más información, vea Solucionar problemas relacionados con las operaciones de la API.

x-ms-version

Indica la versión del servicio Blob utilizado para ejecutar la solicitud. Este encabezado se devuelve para las solicitudes realizadas con la versión 2009-09-19 y versiones más recientes.

Este encabezado también se devuelve para las solicitudes anónimas sin una versión especificada si el contenedor se marcó para acceso público utilizando la versión 2009-09-19 del servicio Blob.

Date

Valor de fecha y hora UTC generado por el servicio que indica la hora a la que se inició 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.

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.

<?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>
      <Properties>
        <Last-Modified>date-time-value</Last-Modified>
        <Etag>etag</Etag>
        <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</BlobType>
        <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>
      </Properties>
      <Metadata>   
        <Name>value</Name>
      </Metadata>
    </Blob>
    <BlobPrefix>
      <Name>blob-prefix</Name>
    </BlobPrefix>
  </Blobs>
  <NextMarker />
</EnumerationResults>

LeaseState y LeaseDuration solo aparecen en la versión 2012-02-12 y versiones 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 aparecerán con un blob creado por Copy Blob en una versión anterior a 2012-02-12.

noteNota
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 más recientes, el servicio Blob calcula el valor Content-MD5 al cargar un blob mediante Put Blob, pero no lo calcula cuando se crea un blob mediante Put Block List. Es posible establecer explícitamente el valor Content-MD5 al crear el blob, o mediante una llamada a las operaciones Put Block List o Set Blob Properties.

Para obtener una respuesta de ejemplo, vea Enumerar los recursos de blob.

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.

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.

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 al crear 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 los 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>
      …

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

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 BlobPrefix es substring+delimiter, donde substring es la subcadena común con la que comienzan uno o varios nombres de blob, y delimiter es el valor del parámetro delimiter.

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 el servicio Blob 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.

 

Componente Descripción

Código de estado HTTP

Número entero de 3 dígitos estándar que especifica el error.

Código de error

Palabra clave que describe el error y que proporciona Azure en el elemento <ErrorCode>. Si no aparece ningún elemento <ErrorCode>, se utiliza una palabra clave que contiene el texto de error estándar asociado al código de estado HTTP de 3 dígitos de la especificación HTTP. Vea Códigos de error comunes de la API de REST.

Información

Descripción detallada del error, entre comillas.

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

ImportantImportante
El texto de la descripción mostrado aquí puede cambiar sin previo aviso, incluso antes de un cambio de versión, por lo que no debe usarlo literalmente para detectar condiciones de error.

 

Escenario Valor de CopyStatus Valor de CopyStatusDescription

Operación de copia completada correctamente.

success

vacío

El usuario ha anulado la operación de copia antes de que se haya completado.

aborted

vacío

Se produjo un error al leer el blob de origen durante una operación de copia, pero la operación se volverá a intentar.

pending

502 BadGateway "Al leer el origen se encontró un error que se puede reintentar. Se volverá a intentar. Hora del error: <time>"

Se produjo un error al escribir en el blob de destino durante una operación de copia, pero la operación se volverá a intentar.

pending

500 InternalServerError "Se encontró un error que se puede volver a intentar. Se volverá a intentar. Hora del error: <time>"

Se produjo un error irrecuperable al leer el blob de origen durante una operación de copia.

failed

404 ResourceNotFound "Error en la copia al leer el origen."

noteNota
Al informar de este error subyacente, Azure devuelve ResourceNotFound en el elemento <ErrorCode>. Si no aparece el elemento <ErrorCode> en la respuesta, aparecerá una representación de cadena estándar del estado HTTP, como NotFound.

El tiempo de espera que limita todas las operaciones de copia realizadas. (En la actualidad, el tiempo de espera es de 2 semanas).

failed

500 OperationCancelled "La copia superó el tiempo máximo permitido."

La operación de copia produjo errores muy frecuentes al leer del origen y no alcanzó la relación mínima entre intentos y operaciones correctas. (Este tiempo de espera impide que se produzcan reintentos en un origen deficiente durante 2 semanas antes de que se produzca un error).

failed

500 OperationCancelled "Error en la copia al leer el origen."

¿Te ha resultado útil?
(Caracteres restantes: 1500)
Gracias por sus comentarios
Mostrar:
© 2014 Microsoft