Get Block List

Artículo
02/07/2024

La operación Get Block List recupera la lista de bloques que se han cargado como parte de un blob en bloques.

Hay dos listas de bloques mantenidas para un blob:

Lista de bloques confirmadas: lista de bloques que se han confirmado correctamente en un blob especificado mediante Put Block List.
Lista de bloques no confirmada: lista de bloques que se han cargado para un blob mediante Put Block, pero que aún no se han confirmado. Estos bloques se almacenan en Azure en asociación con un blob, pero aún no forman parte del blob.

Puede llamar Get Block List a para devolver la lista de bloques confirmada, la lista de bloques no confirmada o ambas listas. También puede llamar a esta operación para recuperar la lista de bloques confirmada para una instantánea.

Solicitud

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

URI de solicitud de método GET	Versión de HTTP
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist&snapshot=<DateTime>` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist&versionid=<DateTime>`	HTTP/1.1

Solicitud 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:

URI de solicitud de método GET	Versión de HTTP
`http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=blocklist`	HTTP/1.1

Para más información, consulte Uso del emulador de Azurite para desarrollo y pruebas locales de Azure Storage.

Parámetros del identificador URI

Puedes especificar los siguientes parámetros adicionales en el URI de la solicitud:

Parámetro de URI	Descripción
`snapshot`	Opcional. El parámetro de instantánea es un valor `DateTime` opaco que, cuando está presente, especifica la lista de blobs que se va a recuperar. Para más información sobre cómo trabajar con instantáneas de blob, consulte Creación de una instantánea de un blob.
`versionid`	Opcional para las versiones 2019-12-12 y posteriores. El `versionid` parámetro es un valor opaco `DateTime` que, cuando está presente, especifica la versión del blob que se va a recuperar.
`blocklisttype`	Especifica si se debe devolver la lista de bloques confirmados, la lista de bloques sin confirmar o ambas listas. Los valores válidos son `committed`, `uncommitted` o `all`. Si omite este parámetro, `Get Block List` devuelve la lista de bloques confirmados.
`timeout`	Opcional. El parámetro `timeout` se expresa en segundos. Para más información, consulte Establecimiento de tiempos de espera para las operaciones de Blob Storage.

Encabezados de solicitud

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

Encabezado de solicitud	Descripción
`Authorization`	Necesario. Especifica el esquema de autorización, el nombre de cuenta y la firma. Para obtener más información, vea Autorización de solicitudes a Azure Storage.
`Date` o `x-ms-date`	Necesario. Especifica la hora universal coordinada (UTC) de la solicitud. Para obtener más información, vea Autorización de solicitudes a Azure Storage.
`x-ms-version`	Obligatorio para todas las solicitudes autorizadas, 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 Versiones de los servicios de Azure Storage.
`x-ms-lease-id:<ID>`	Opcional. Si se especifica este encabezado, la operación se realizará solo si se cumplen las dos condiciones siguientes: - La concesión del blob está activa actualmente. : el identificador de concesión especificado en la solicitud coincide con el del blob. Si se especifica este encabezado y no se cumple ninguna condición, se produce un error en la solicitud y se produce un error en la operación con el código de estado 412 (error en la condición previa).
`x-ms-client-request-id`	Opcional. Proporciona un valor opaco generado por el cliente con un límite de caracteres de 1 kibibyte (KiB) que se registra en los registros cuando se configura el registro. Se recomienda encarecidamente usar este encabezado para correlacionar las actividades del lado cliente con las solicitudes que recibe el servidor. Para obtener más información, consulte Supervisión de Azure Blob Storage.

Esta operación también admite el uso de encabezados condicionales que permiten ejecutar la operación solo si se cumple una condición especificada. Para más información, consulte Especificación de encabezados condicionales para las operaciones de Blob Storage.

Cuerpo de la solicitud

Ninguno.

Solicitud de ejemplo

El siguiente URI de solicitud de ejemplo devuelve la lista de bloques confirmada para un blob denominado MOV1.avi:

GET http://myaccount.blob.core.windows.net/movies/MOV1.avi?comp=blocklist&blocklisttype=committed HTTP/1.1

El siguiente URI de solicitud de ejemplo devuelve la lista de bloques confirmada y no confirmada:

GET http://myaccount.blob.core.windows.net/movies/MOV1.avi?comp=blocklist&blocklisttype=all HTTP/1.1

El siguiente URI de solicitud de ejemplo devuelve la lista de bloques confirmada para una instantánea. Una instantánea consta solo de bloques confirmados, por lo que no hay bloques sin confirmar asociados.

GET http://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist&snapshot=2009-09-30T20%3a11%3a15.2735974Z

Response

La respuesta incluye un código de estado HTTP, un conjunto de encabezados de respuesta y un cuerpo de respuesta que contiene la lista de bloques.

status code

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

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

Encabezados de respuesta

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

Encabezado de respuesta	Descripción
`Last-Modified`	Fecha y hora en que se modificó por última vez el blob. El formato de la fecha sigue las convenciones de RFC 1123. Para obtener más información, vea Representar valores de fecha y hora en encabezados. Solo se devuelve si el blob tiene bloques confirmados. Cualquier operación que modifique el blob, incluidas las actualizaciones de los metadatos o las propiedades del blob, cambia la hora de la última modificación del blob.
`ETag`	La ETag del blob. Solo se devuelve si el blob tiene bloques confirmados.
`Content-Type`	El tipo de contenido MIME del blob. El valor predeterminado es `application/xml`.
`x-ms-blob-content-length`	Tamaño del blob en bytes.
`x-ms-request-id`	Este encabezado identifica de forma única la solicitud realizada y se puede usar para solucionar problemas de la solicitud. Para más información, consulte Solución de problemas de operaciones de API.
`x-ms-version`	Indica la versión del servicio que se usó para ejecutar la solicitud. Este encabezado se devuelve para las solicitudes realizadas en la versión 2009-09-19 y versiones posteriores. Este encabezado también se devuelve para las solicitudes anónimas sin una versión especificada si el contenedor se marcó para el acceso público mediante la versión 2009-09-19 de Blob Storage. Nota: Solo se puede devolver la lista de bloqueados confirmada a través de una solicitud anónima.
`Date`	Valor de fecha y hora UTC generado por el servicio, que indica la hora en que se inició la respuesta.
`x-ms-client-request-id`	Se puede usar para solucionar problemas de solicitudes y respuestas correspondientes. El valor de este encabezado es igual al valor del `x-ms-client-request-id` encabezado si está presente en la solicitud y el valor no contiene más de 1024 caracteres ASCII visibles. Si el `x-ms-client-request-id` encabezado no está presente en la solicitud, no está presente en la respuesta.

Esta operación también admite el uso de encabezados condicionales para obtener la lista de bloques solo si se cumple una condición especificada. Para más información, consulte Especificación de encabezados condicionales para las operaciones de Blob Storage.

Response body

El formato del cuerpo de respuesta de una solicitud que devuelve solo bloques confirmados es el siguiente:

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
    <Block>
      <Name>base64-encoded-block-id</Name>
      <Size>size-in-bytes</Size>
    </Block>
  <CommittedBlocks>
</BlockList>

El formato del cuerpo de respuesta de una solicitud que devuelve ambos tipos de bloques, confirmados y sin confirmar, es el siguiente:


<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
     <Block>
        <Name>base64-encoded-block-id</Name>
        <Size>size-in-bytes</Size>
     </Block>
  </CommittedBlocks>
  <UncommittedBlocks>
    <Block>
      <Name>base64-encoded-block-id</Name>
      <Size>size-in-bytes</Size>
    </Block>
  </UncommittedBlocks>
 </BlockList>

Respuesta de muestra

En el ejemplo siguiente, el parámetro blocklisttype se ha establecido en committed, por lo que en la respuesta solo se devuelven los bloques confirmados del blob.

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Sun, 25 Sep 2011 00:33:19 GMT

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
    <Block>
      <Name>BlockId001</Name>
      <Size>4194304</Size>
    </Block>
    <Block>
      <Name>BlockId002</Name>
      <Size>4194304</Size>
    </Block>
  </CommittedBlocks>
</BlockList>

En este ejemplo, el parámetro blocklisttype se ha establecido en all, por lo que en la respuesta se devuelven tanto los bloques confirmados como los bloques sin confirmar del blob.

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Sun, 25 Sep 2011 00:35:56 GMT

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
    <Block>
      <Name>BlockId001</Name>
      <Size>4194304</Size>
    </Block>
    <Block>
      <Name>BlockId002</Name>
      <Size>4194304</Size>
    </Block>
  </CommittedBlocks>
  <UncommittedBlocks>
    <Block>
      <Name>BlockId003</Name>
      <Size>4194304</Size>
    </Block>
    <Block>
      <Name>BlockId004</Name>
      <Size>1024000</Size>
    </Block>
  </UncommittedBlocks>
</BlockList>

En este ejemplo siguiente, el blocklisttype parámetro se estableció allen , pero el blob aún no se ha confirmado, por lo que el CommittedBlocks elemento está vacío.

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Wed, 14 Sep 2011 00:40:22 GMT

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks />
  <UncommittedBlocks>
    <Block>
      <Name>BlockId001</Name>
      <Size>1024</Size>
    </Block>
    <Block>
      <Name>BlockId002</Name>
      <Size>1024</Size>
    </Block>
    <Block>
      <Name>BlockId003</Name>
      <Size>1024</Size>
    </Block>
    <Block>
      <Name>BlockId004</Name>
      <Size>1024</Size>
    </Block>
  </UncommittedBlocks>
</BlockList>

Authorization

La autorización es necesaria al llamar a cualquier operación de acceso a datos en Azure Storage. Puede autorizar la Get Block List operación como se describe a continuación.

Azure Storage admite el uso de Microsoft Entra ID para autorizar solicitudes a datos de blobs. Con Microsoft Entra ID, puede usar el control de acceso basado en rol de Azure (RBAC de Azure) para conceder permisos a una entidad de seguridad. La entidad de seguridad puede ser un usuario, un grupo, una entidad de servicio de aplicación o una identidad administrada de Azure. La entidad de seguridad se autentica mediante Microsoft Entra ID para devolver un token de OAuth 2.0. Después, el token se puede usar para autorizar una solicitud en Blob service.

Para más información sobre la autorización mediante Microsoft Entra ID, consulte Autorización del acceso a blobs mediante Microsoft Entra ID.

Permisos

A continuación se enumeran las acciones de RBAC necesarias para que un usuario, grupo o entidad de servicio de Microsoft Entra llame a la Get Block List operación y el rol RBAC integrado con privilegios mínimos que incluye esta acción:

Acción RBAC de Azure:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
Rol integrado con privilegios mínimos:Lector de datos de Blob de Storage

Para más información sobre cómo asignar roles mediante RBAC de Azure, consulte Asignación de un rol de Azure para el acceso a datos de blobs.

Una firma de acceso compartido (SAS) proporciona acceso delegado seguro a los recursos de una cuenta de almacenamiento. Con una SAS, tiene un control pormenorizado sobre cómo un cliente puede acceder a los datos. Puede especificar a qué recurso puede acceder el cliente, qué permisos tienen para esos recursos y cuánto tiempo es válido la SAS.

La Get Block List operación admite tres tipos de firmas de acceso compartido: SAS de delegación de usuarios, SAS de servicio y SAS de cuenta.

Como procedimiento recomendado de seguridad, se recomienda usar Microsoft Entra credenciales en lugar de la clave de la cuenta de almacenamiento, que se puede poner en peligro más fácilmente. Si el diseño de la aplicación requiere firmas de acceso compartido, use Microsoft Entra credenciales para crear una SAS de delegación de usuarios, siempre que sea posible.

Cuando no se permite el acceso a la clave compartida para la cuenta de almacenamiento, no se permitirá un token de SAS de servicio o un token de SAS de cuenta en una solicitud a Blob Storage. Para más información, consulte Descripción de cómo no permitir la clave compartida afecta a los tokens de SAS.

SAS de delegación de usuarios

Una SAS de delegación de usuarios está protegida con credenciales de Microsoft Entra y también por los permisos especificados para la SAS.

La llamada a la Get Block List operación mediante un token de SAS delegado en un recurso de contenedor o blob requiere el permiso De lectura (r) como parte del token de SAS de delegación de usuarios.

Para más información sobre la SAS de delegación de usuarios, consulte Creación de una SAS de delegación de usuarios.

SAS de servicio

Una SAS de servicio está protegida con la clave de cuenta de almacenamiento. Una SAS de servicio delega el acceso a un recurso en un único servicio de Azure Storage, como Blob Storage.

La llamada a la Get Block List operación mediante un token de SAS delegado en un recurso de contenedor o blob requiere el permiso De lectura (r) como parte del token de SAS de servicio.

Para más información sobre la SAS de servicio, consulte Creación de una SAS de servicio.

SAS de cuenta

Una SAS de cuenta está protegida con la clave de cuenta de almacenamiento. SAS de cuenta delega el acceso a los recursos en uno o varios de los servicios de almacenamiento. Todas las operaciones disponibles con una SAS de servicio o delegación de usuarios están también disponibles con una SAS de cuenta.

En la tabla siguiente se indica el tipo de recurso firmado y los permisos firmados que se especificarán al delegar el acceso:

Operación	Servicio firmado	Tipo de recurso firmado	Permiso firmado
Get Block List	Blob (b)	Objeto (o)	Lectura (r)

Para más información sobre la SAS de cuenta, consulte Creación de una SAS de cuenta.

Comentarios

Llame Get Block List a para devolver la lista de bloques que se han confirmado en un blob en bloques, la lista de bloques que aún no se han confirmado o ambas listas. Use el parámetro blocklisttype para especificar qué lista de bloques se debe devolver. La lista de bloques confirmados se devuelve en el mismo orden en que se han confirmado con la operación Put Block List .

Puede usar la lista de bloques no confirmada para determinar qué bloques faltan en el blob en casos en los que las llamadas a Put Block o Put Block List han producido errores. La lista de bloques no confirmados se devuelve en orden alfabético. Si un identificador de bloque se ha cargado más de una vez, en la lista solo aparece el último bloque cargado.

Nota

Cuando aún no se ha confirmado un blob, llamar a Get Block List con blocklisttype=all devuelve los bloques no confirmados y el CommittedBlocks elemento está vacío.

Get Block List no admite la simultaneidad cuando lee la lista de bloques no confirmados. Llama a donde Get Block Listblocklisttype=uncommitted o blocklisttype=all tienen una tasa de solicitudes máxima menor que otras operaciones de lectura. Para más información sobre el rendimiento de destino para las operaciones de lectura, consulte Objetivos de escalabilidad y rendimiento de Azure Storage.

A partir de la versión 2019-12-12, un blob en bloques puede contener bloques de hasta 4000 mebibytes (MiB). Para proteger las aplicaciones que usan un entero de 32 bits con signo para representar el tamaño de bloque, llamar a Get Block List en un blob en bloques que contenga un bloque mayor que 100 MiB con una versión DE REST anterior a 2019-12-12 da como resultado el código de estado 409 (Conflicto).

Get Block List se aplica solo a los blobs en bloques. Si llama a Get Block List en un blob en páginas, se generará el código de estado 400 (Solicitud incorrecta).

Get Block List en un blob en bloques archivado producirá un error.

Facturación

Las solicitudes de precios pueden originarse en clientes que usan API de Blob Storage, ya sea directamente a través de la API REST de Blob Storage o desde una biblioteca cliente de Azure Storage. Estas solicitudes acumulan cargos por transacción. El tipo de transacción afecta a cómo se cobra la cuenta. Por ejemplo, las transacciones de lectura se acumulan en una categoría de facturación diferente a las transacciones de escritura. En la tabla siguiente se muestra la categoría de facturación de Get Block List las solicitudes basadas en el tipo de cuenta de almacenamiento:

Operación	Tipo de cuenta de almacenamiento	Categoría de facturación
Get Block List	Blobs en bloques Premium De uso general, estándar, v2	Otras operaciones
Get Block List	De uso general, estándar, v1	Lee operaciones.

Para obtener información sobre los precios de la categoría de facturación especificada, consulte precios Azure Blob Storage.

Consulte también

Autorización de solicitudes a los códigos de error y estado de Azure Storage : establecer tiempos de espera para las operaciones de Blob Storage