Put Block

  • Artículo

La operación Put Block crea un nuevo bloque que se confirmará como parte de un blob en bloques.

Solicitud

Puede construir la solicitud de la Put Block siguiente manera. Se recomienda usar HTTPS. Reemplace myaccount por el nombre de la cuenta de almacenamiento:

URI de solicitud de método PUT Versión de HTTP
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=id HTTP/1.1

Solicitud del servicio de almacenamiento emulado

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

URI de solicitud de método PUT Versión de HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=block&blockid=id 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

Parámetro Descripción
blockid Necesario. Valor de cadena de tipo Base64 válido que identifica el bloque. Antes de codificar, la cadena debe tener un tamaño menor o igual que 64 bytes.

Para un blob especificado, la longitud del valor del blockid parámetro debe tener el mismo tamaño para cada bloque.

Nota: La cadena Base64 debe estar codificada con dirección URL.
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 Service.

Encabezados de solicitud

Los encabezados de solicitud obligatorios y opcionales se describen en la tabla siguiente:

Encabezado de solicitud Descripción
Authorization Necesario. Especifica el esquema de autorización, el nombre de cuenta y la firma. Consulte Autorización de solicitudes a Azure Storage para más información.
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 Necesario para todas las solicitudes autorizadas. Especifica la versión de la operación que se utiliza para esta solicitud. Para más información, consulte Control de versiones para los servicios de Azure Storage.
Content-Length Necesario. La longitud del contenido del bloque, en bytes. El bloque debe tener un tamaño menor o igual que 4000 mebibytes (MiB) para la versión 2019-12-12 y posteriores. Consulte la sección Comentarios para ver los límites en versiones anteriores.

Cuando no se proporciona la longitud, se produce un error en la operación con el código de estado 411 (longitud requerida).
Content-MD5 Opcional. Hash MD5 del contenido del bloque. Este hash se utiliza para comprobar la integridad del bloque durante el transporte. Cuando se especifica este encabezado, el servicio de almacenamiento compara el hash del contenido que ha llegado con este valor de encabezado.

Nota: Este hash MD5 no se almacena con el blob.

Si los dos hashes no coinciden, se produce un error en la operación con el código de error 400 (solicitud incorrecta).
x-ms-content-crc64 Opcional. Hash CRC64 del contenido del bloque. Este hash se utiliza para comprobar la integridad del bloque durante el transporte. Cuando se especifica este encabezado, el servicio de almacenamiento compara el hash del contenido que ha llegado con este valor de encabezado.

Nota: Este hash CRC64 no se almacena con el blob.

Si ambos valores de hash no coinciden, la operación produce un error con el código de estado 400 (solicitud incorrecta).

Si los encabezados Content-MD5 y x-ms-content-crc64 están presentes, la solicitud produce un error 400 (solicitud incorrecta).

Este encabezado es compatible con las versiones 2019-02-02 y posteriores.
x-ms-encryption-scope Opcional. Indica el ámbito de cifrado que se va a usar para cifrar el contenido de la solicitud. Este encabezado es compatible con las versiones 2019-02-02 y posteriores.
x-ms-lease-id:<ID> Obligatorio si el blob tiene una concesión activa. Para realizar esta operación en un blob con una concesión activa, especifique el identificador de concesión válido de este encabezado.
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.

Encabezados de solicitud (claves de cifrado proporcionadas por el cliente)

A partir de la versión 2019-02-02, se pueden especificar los siguientes encabezados en la solicitud para cifrar un blob con una clave proporcionada por el cliente. El cifrado con una clave proporcionada por el cliente (y el conjunto de encabezados correspondiente) es opcional.

Encabezado de solicitud Descripción
x-ms-encryption-key Necesario. La clave de cifrado AES-256 codificada en Base64.
x-ms-encryption-key-sha256 Necesario. Hash SHA256 codificado en Base64 de la clave de cifrado.
x-ms-encryption-algorithm: AES256 Necesario. Especifica el algoritmo que se va a usar para el cifrado. El valor de este encabezado debe ser AES256.

Cuerpo de la solicitud

El cuerpo de la solicitud incluye el contenido del bloque.

Solicitud de ejemplo

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=AAAAAA%3D%3D HTTP/1.1  
  
Request Headers:  
x-ms-version: 2011-08-18  
x-ms-date: Sun, 25 Sep 2011 14:37:35 GMT  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048576

Response

La respuesta incluye un código de estado HTTP y un conjunto de encabezados de respuesta.

status code

Una operación correcta devuelve el código de estado 201 (Creado).

Para obtener información sobre los códigos de estado, vea 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 otros encabezados HTTP estándar. Todos los encabezados estándar se ajustan a la especificación del protocolo HTTP/1.1.

Encabezado de respuesta Descripción
Content-MD5 Se devuelve para que el cliente pueda comprobar la integridad del contenido del mensaje. Blob Storage calcula el valor de este encabezado y no es necesariamente el mismo valor que se especifica en los encabezados de solicitud. Para las versiones 2019-02-02 y posteriores, este encabezado solo se devuelve cuando la solicitud tiene este encabezado.
x-ms-content-crc64 Para las versiones 2019-02-02 y posteriores, este encabezado se devuelve para que el cliente pueda comprobar la integridad del contenido del mensaje. Blob Storage calcula el valor de este encabezado y no es necesariamente el mismo valor que se especifica en los encabezados de solicitud.

Este encabezado se devuelve cuando Content-md5 el encabezado no está presente en la solicitud.
x-ms-request-id Identifica de forma única la solicitud que se realizó y puede usarla 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 de Blob Storage que se usó para ejecutar la solicitud. Este encabezado se devuelve para las solicitudes realizadas en la versión 2009-09-19 o posterior.
Date Valor de fecha y hora UTC generado por el servicio, que indica cuándo se inició la respuesta.
x-ms-request-server-encrypted: true/false Versión 2015-12-11 y posteriores. El valor de este encabezado se establece true en si el contenido de la solicitud se cifra correctamente mediante el algoritmo especificado. De lo contrario, el valor se establece en false.
x-ms-encryption-key-sha256 Versión 2019-02-02 y posteriores. Este encabezado se devuelve si la solicitud usó una clave proporcionada por el cliente para el cifrado, de modo que el cliente pueda asegurarse de que el contenido de la solicitud se cifre correctamente mediante la clave proporcionada.
x-ms-encryption-scope Versión 2019-02-02 y posteriores. Este encabezado se devuelve si la solicitud usó un ámbito de cifrado para que el cliente pueda asegurarse de que el contenido de la solicitud se cifre correctamente mediante el ámbito de cifrado.
x-ms-client-request-id Se puede usar para solucionar problemas de solicitudes y sus 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.

Respuesta de muestra

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sun, 25 Sep 2011 23:47:09 GMT  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

Authorization

Se requiere autorización al llamar a cualquier operación de acceso a datos en Azure Storage. Puede autorizar la Put Block 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 un usuario, grupo o entidad de servicio de Microsoft Entra para llamar a la Put Block operación y el rol RBAC integrado con privilegios mínimos que incluye esta acción:

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

Comentarios

Put Block carga un bloque para su futura inclusión en un blob en bloques. Cada bloque de un blob en bloques puede tener un tamaño diferente. Un blob en bloques puede incluir un máximo de 50 000 bloques confirmados.

En la tabla siguiente se describen los tamaños máximos permitidos de bloques y blobs, por versión del servicio:

Versión del servicio Tamaño máximo de bloque (a través de Put Block) Tamaño máximo del blob (a través de Put Block List) Tamaño máximo de blob a través de una operación de escritura única (a través de Put Blob)
Versión 2019-12-12 y posteriores 4000 MiB Aproximadamente 190,7 tebibytes (TiB) (4000 MiB × 50 000 bloques) 5000 MiB
Versiones 2016-05-31 a 2019-07-07 100 MiB Aproximadamente 4,75 TiB (100 MiB × 50 000 bloques) 256 MiB
Versiones anteriores a 2016-05-31 4 MiB Aproximadamente 195 gibibytes (GiB) (4 MiB × 50 000 bloques) 64 MiB

El número máximo de bloques no confirmados que se pueden asociar a un blob es de 100 000. Si se supera este número, el servicio devuelve el código de estado 409 (RequestEntityTooLargeBlockCountExceedsLimit).

Después de cargar un conjunto de bloques, puede crear o actualizar el blob en el servidor desde este conjunto mediante una llamada a la operación Put Block List . Cada bloque del conjunto se identifica mediante un identificador de bloque único dentro de ese blob. Los identificadores de bloques se limitan a un blob determinado, por lo que los distintos blobs pueden tener bloques con los mismos identificadores.

Si llama a Put Block en un blob que aún no existe, se crea un nuevo blob en bloques con una longitud de contenido de 0. Este blob lo enumera la operación List Blobs si se especifica la opción include=uncommittedblobs. El bloque o los bloques que carga no se confirman hasta que se llama Put Block List a en el nuevo blob. Un blob que se crea de esta manera se mantiene en el servidor durante una semana. Si no ha agregado más bloques o bloques confirmados al blob dentro de ese período de tiempo, el blob se recopila como elemento no utilizado.

Un bloque que se ha cargado correctamente con la Put Block operación no forma parte de un blob hasta que se confirma con Put Block List. Antes Put Block List de llamar a para confirmar el blob nuevo o actualizado, las llamadas a Get Blob devuelven el contenido del blob sin incluir el bloque no confirmado.

Si carga un bloque que tiene el mismo identificador de bloque que otro bloque que aún no se ha confirmado, el último bloque cargado con ese identificador se confirmará en la siguiente operación correcta Put Block List .

Después Put Block List de llamar a , todos los bloques no confirmados especificados en la lista de bloques se confirman como parte del nuevo blob. Los bloques no confirmados que no se especificaron en la lista de bloques del blob se recopilan y quitan de Blob Storage. Los bloques no confirmados también se recopilan como elementos no utilizados si no hay llamadas correctas a Put Block o Put Block List en el mismo blob dentro de una semana después de la última operación correcta Put Block . Si se llama a Put Blob en el blob , los bloques no confirmados se recopilan como elementos no utilizados.

Si el blob tiene una concesión activa, el cliente debe especificar un identificador de concesión válido en la solicitud para escribir un bloque en el blob. Si el cliente no especifica un identificador de concesión o especifica un identificador de concesión no válido, Blob Storage devuelve el código de estado 412 (error de condición previa). Si el cliente especifica un identificador de concesión, pero el blob no tiene una concesión activa, Blob Storage también devuelve el código de estado 412 (error de condición previa).

Para un blob especificado, todos los identificadores de bloque deben tener la misma longitud. Si se carga un bloque con un identificador de grupo de distinta longitud que los identificadores de bloque de los bloques sin confirmar existentes, el servicio devuelve el código de respuesta de error 400 (Solicitud incorrecta).

Si intenta cargar un bloque mayor que 4000 MiB para la versión 2019-12-12 o posterior, mayor que 100 MiB para la versión 2016-05-31 o posterior, o superior a 4 MiB para versiones anteriores, el servicio devuelve el código de estado 413 (Solicitar entidad demasiado grande). El servicio también devuelve información adicional sobre el error en la respuesta, incluido el tamaño máximo de bloque permitido, en bytes.

La llamada Put Block a no actualiza la hora de la última modificación de un blob existente.

Una llamada a Put Block en un blob en páginas devuelve un error.

Llamar a Put Block en un blob archivado devuelve un error y llamarlo en un hot blob o cool no cambia el nivel de blob.

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 Put Block las solicitudes basadas en el tipo de cuenta de almacenamiento:

Operación Tipo de cuenta de almacenamiento Categoría de facturación
Put Block Blobs en bloques Premium
De uso general, estándar, v2
De uso general, estándar, v1		 Operaciones de escritura

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 Azure Storage
Estado y códigos de error
Códigos de error de Blob Service
Establecimiento de tiempos de espera para las operaciones de Blob Service