Anexar bloque de dirección URLAppend Block From URL

La operación del bloque Append de la dirección URL confirma un nuevo bloque de datos al final de un BLOB en anexos existente.The Append Block From URL operation commits a new block of data to the end of an existing append blob.

La Append Block From URL operación solo se permite si el BLOB se creó con x-ms-blob-type establecido en AppendBlob .The Append Block From URL operation is permitted only if the blob was created with x-ms-blob-type set to AppendBlob. Append Block From URL solo se admite en la versión 2018-11-09 o posterior.Append Block From URL is supported only on version 2018-11-09 version or later.

SolicitudRequest

El bloque Append de la solicitud URL se puede construir como sigue.The Append Block From URL request may be constructed as follows. Se recomienda HTTPS.HTTPS is recommended. Reemplace mi cuenta por el nombre de la cuenta de almacenamiento:Replace myaccount with the name of your storage account:

URI de solicitud del método PUTPUT Method Request URI Versión HTTPHTTP Version
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock HTTP/1.1HTTP/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:When making a request against the emulated storage service, specify the emulator hostname and Blob service port as 127.0.0.1:10000, followed by the emulated storage account name:

URI de solicitud del método PUTPUT Method Request URI Versión HTTPHTTP Version
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=appendblock HTTP/1.1HTTP/1.1

Para obtener más información, vea uso del emulador de Azure Storage para desarrollo y pruebas.For more information, see Using the Azure Storage Emulator for Development and Testing.

Parámetros del identificador URIURI parameters

ParámetroParameter DescripciónDescription
timeouttimeout Opcional.Optional. El parámetro de tiempo de espera se expresa en segundos.The timeout parameter is expressed in seconds. Para obtener más información, consulte configuración de tiempos de espera para las operaciones de BLOB Service.For more information, see Setting Timeouts for Blob Service Operations.

Encabezados de solicitudRequest Headers

En la tabla siguiente se describen los encabezados de solicitud requeridos y opcionales.The following table describes required and optional request headers.

Encabezado de solicitudRequest Header DescripciónDescription
Authorization Necesario.Required. Especifica el esquema de autorización, el nombre de cuenta y la firma.Specifies the authorization scheme, account name, and signature. Consulte autorización de solicitudes para Azure Storage para obtener más información.See Authorize requests to Azure Storage for more information.
Date o x-ms-dateDate or x-ms-date Necesario.Required. Especifica la hora universal coordinada (UTC) de la solicitud.Specifies the Coordinated Universal Time (UTC) for the request. Para obtener más información, consulte autorización de solicitudes para Azure Storage.For more information, see Authorize requests to Azure Storage.
x-ms-version Obligatorio para todas las solicitudes autorizadas.Required for all authorized requests. Especifica la versión de la operación que se utiliza para esta solicitud.Specifies the version of the operation to use for this request. Para obtener más información, vea control de versiones de los servicios de Azure Storage.For more information, see Versioning for the Azure Storage Services.
Content-Length Necesario.Required. Especifica el número de bytes que se transmiten en el cuerpo de la solicitud.Specifies the number of bytes being transmitted in the request body. El valor de este encabezado debe establecerse en cero.The value of this header must be set to zero. Cuando la longitud no sea cero, se producirá un error en la operación con el código de estado 400 (solicitud incorrecta).When the length is not zero, the operation will fail with the status code 400 (Bad Request).
x-ms-copy-source:name Necesario.Required. Especifica la dirección URL del BLOB de origen.Specifies the URL of the source blob. El valor puede ser una dirección URL de hasta 2 KiB de longitud que especifica un BLOB.The value may be a URL of up to 2 KiB in length that specifies a blob. El valor debe estar codificado para URL tal y como aparecería en un URI de solicitud.The value should be URL-encoded as it would appear in a request URI. El BLOB de origen debe ser público o debe estar autorizado a través de una firma de acceso compartido.The source blob must either be public or must be authorized via a shared access signature. Si el BLOB de origen es público, no se requiere autorización para realizar la operación.If the source blob is public, no authorization is required to perform the operation. Estos son algunos ejemplos de direcciones URL de objetos de origen:Here are some examples of source object URLs:

- https://myaccount.blob.core.windows.net/mycontainer/myblob
- https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>
- https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>
x-ms-source-range Opcional.Optional. Carga solo los bytes del BLOB en la dirección URL de origen en el intervalo especificado.Uploads only the bytes of the blob in the source URL in the specified range. Si no se especifica, todo el contenido del BLOB de origen se carga como un solo bloque Append.If this is not specified, the entire source blob contents are uploaded as a single append block. Vea especificar el encabezado de intervalo para las operaciones del servicio BLOB para obtener más información.See Specifying the Range Header for Blob Service Operations for more information.
x-ms-source-content-md5 Opcional.Optional. Un hash MD5 del contenido del bloque Append del URI.An MD5 hash of the append block content from the URI. Este hash se utiliza para comprobar la integridad del bloque Append durante el transporte de los datos desde el URI.This hash is used to verify the integrity of the append block during transport of the data from the URI. Cuando se especifica este encabezado, el servicio de almacenamiento compara el hash del contenido que ha llegado desde el origen de copia con este valor de encabezado.When this header is specified, the storage service compares the hash of the content that has arrived from the copy-source with this header value.

Tenga en cuenta que este hash MD5 no se almacena con el BLOB.Note that this md5 hash is not stored with the blob.

Si ambos valores de hash no coinciden, la operación producirá un error con el código de estado 400 (Solicitud incorrecta).If the two hashes do not match, the operation will fail with error code 400 (Bad Request).
x-ms-source-content-crc64 Opcional.Optional. Un hash de CRC64 del contenido del bloque de anexión del URI.A CRC64 hash of the append block content from the URI. Este hash se utiliza para comprobar la integridad del bloque Append durante el transporte de los datos desde el URI.This hash is used to verify the integrity of the append block during transport of the data from the URI. Cuando se especifica este encabezado, el servicio de almacenamiento compara el hash del contenido que ha llegado desde el origen de copia con este valor de encabezado.When this header is specified, the storage service compares the hash of the content that has arrived from the copy-source with this header value.

Tenga en cuenta que este hash de CRC64 no se almacena con el BLOB.Note that this CRC64 hash is not stored with the blob.

Si ambos valores de hash no coinciden, la operación producirá un error con el código de estado 400 (Solicitud incorrecta).If the two hashes do not match, the operation will fail with error code 400 (Bad Request).

Si x-ms-source-content-md5 x-ms-source-content-crc64 los encabezados y están presentes, la solicitud generará un error 400 (solicitud incorrecta).If both x-ms-source-content-md5 and x-ms-source-content-crc64 headers are present, the request will fail with a 400 (Bad Request).

Este encabezado es compatible con las versiones 2019-02-02 o posteriores.This header is supported in versions 2019-02-02 or later.
x-ms-encryption-scope Opcional.Optional. Indica el ámbito de cifrado que se va a utilizar para cifrar el contenido de origen.Indicates the encryption scope to use to encrypt the source contents. Este encabezado es compatible con las versiones 2019-02-02 o posteriores.This header is supported in versions 2019-02-02 or later.
x-ms-lease-id:<ID> Obligatorio si el blob tiene una concesión activa.Required if the blob has an active lease. Para realizar esta operación en un blob con una concesión activa, especifique el identificador de concesión válido de este encabezado.To perform this operation on a blob with an active lease, specify the valid lease ID for this header.
x-ms-client-request-id Opcional.Optional. Proporciona un valor opaco generado por el cliente con un límite de 1 KiB de caracteres que se registra en los registros de análisis cuando el registro de análisis de almacenamiento está habilitado.Provides a client-generated, opaque value with a 1 KiB character limit that is recorded in the analytics logs when storage analytics logging is enabled. Se recomienda encarecidamente usar este encabezado para correlacionar las actividades del lado cliente con las solicitudes recibidas por el servidor.Using this header is highly recommended for correlating client-side activities with requests received by the server. Para obtener más información, consulte acerca del registro de Storage Analytics y el registro de Azure: uso de registros para realizar un seguimiento de las solicitudes de almacenamiento.For more information, see About Storage Analytics Logging and Azure Logging: Using Logs to Track Storage Requests.
x-ms-blob-condition-maxsize Encabezado condicional opcional.Optional conditional header. Longitud máxima en bytes permitida para el BLOB en anexos.The max length in bytes permitted for the append blob. Si la Append Block From URL operación haría que el BLOB superara ese límite o el tamaño del BLOB ya es mayor que el valor especificado en este encabezado, la solicitud producirá un error MaxBlobSizeConditionNotMet (código de Estado HTTP 412 – error de condición previa).If the Append Block From URL operation would cause the blob to exceed that limit or if the blob size is already greater than the value specified in this header, the request will fail with MaxBlobSizeConditionNotMet error (HTTP status code 412 – Precondition Failed).
x-ms-blob-condition-appendpos Encabezado condicional opcional, que solo se usa para la Append Block from URL operación.Optional conditional header, used only for the Append Block from URL operation. Número que indica el desplazamiento de bytes que se va a comparar.A number indicating the byte offset to compare. Append Block from URL solo se realizará correctamente si la posición de anexión es igual a este número.Append Block from URL will succeed only if the append position is equal to this number. Si no es así, se producirá un error en la solicitud con el error AppendPositionConditionNotMet (código de Estado HTTP 412 – error de condición previa).If it is not, the request will fail with the AppendPositionConditionNotMet error (HTTP status code 412 – Precondition Failed).

Esta operación admite el uso de encabezados condicionales adicionales para asegurarse de que la API se realiza correctamente solo si se cumple una condición especificada.This operation supports the use of additional conditional headers to ensure that the API succeeds only if a specified condition is met. Para obtener más información, consulte Especificación de encabezados condicionales para las operaciones de Blob Service.For more information, see Specifying Conditional Headers for Blob Service Operations.

Encabezados de solicitud (claves de cifrado proporcionadas por el cliente)Request Headers (Customer-provided encryption keys)

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.Beginning with version 2019-02-02, the following headers may be specified on the request to encrypt a blob with a customer-provided key. El cifrado con una clave proporcionada por el cliente (y el conjunto de encabezados correspondiente) es opcional.Encryption with a customer-provided key (and the corresponding set of headers) is optional.

Encabezado de solicitudRequest header DescripciónDescription
x-ms-encryption-key Necesario.Required. La clave de cifrado AES-256 codificada en Base64.The Base64-encoded AES-256 encryption key.
x-ms-encryption-key-sha256 Necesario.Required. El hash SHA256 con codificación Base64 de la clave de cifrado.The Base64-encoded SHA256 hash of the encryption key.
x-ms-encryption-algorithm: AES256 Necesario.Required. Especifica el algoritmo que se va a usar para el cifrado.Specifies the algorithm to use for encryption. El valor de este encabezado debe ser AES256 .The value of this header must be AES256.

Cuerpo de la solicitudRequest Body

El cuerpo de la solicitud incluye el contenido del bloque.The request body contains the content of the block.

Solicitud de ejemploSample Request

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock  HTTP/1.1  

Request Headers:  
x-ms-version: 2018-11-09  
x-ms-date: <date>  
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-65535
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0 
If-Match: "0x8CB172A360EC34B"  

ResponseResponse

La respuesta incluye un código de estado HTTP y un conjunto de encabezados de respuesta.The response includes an HTTP status code and a set of response headers.

Código de estadoStatus Code

Una operación correcta devuelve el código de estado 201 (Creado).A successful operation returns status code 201 (Created).

Para obtener información sobre los códigos de estado, vea códigos de estado y de error.For information about status codes, see Status and Error Codes.

Encabezados de respuestaResponse Headers

La respuesta para esta operación incluye los encabezados siguientes.The response for this operation includes the following headers. La respuesta también puede incluir otros encabezados HTTP estándar.The response may also include additional standard HTTP headers. Todos los encabezados estándar cumplen la especificación del protocolo HTTP/1.1.All standard headers conform to the HTTP/1.1 protocol specification.

Encabezado de respuestaResponse header DescripciónDescription
EncabezadoEtag ETag contiene un valor entre comillas que el cliente puede usar para realizar operaciones PUT condicionales mediante el encabezado de solicitud if-Match.The ETag contains a value in quotes that the client can use to perform conditional PUT operations by using the If-Match request header.
Última modificaciónLast-Modified La fecha y la hora en la que se modificó por última vez el blob.The date/time that the blob was last modified. El formato de la fecha sigue las convenciones de RFC 1123.The date format follows RFC 1123. Para obtener más información, vea representación de valores de fecha y hora en encabezados.For more information, see Representation of Date-Time Values in Headers.

Cualquier operación de escritura en el BLOB (incluidas las actualizaciones de los metadatos o las propiedades del BLOB) cambia la hora de la última modificación del BLOB.Any write operation on the blob (including updates on the blob's metadata or properties) changes the last-modified time of the blob.
Content-MD5 Este encabezado se devuelve para que el cliente pueda comprobar la integridad del contenido del mensaje.This header is returned so that the client can check for message content integrity. El valor de este encabezado lo calcula el servicio Blob; no es necesariamente el mismo valor que el especificado en los encabezados de solicitud.The value of this header is computed by the Blob service; it is not necessarily the same value specified in the request headers. En las versiones 2019-02-02 o posteriores, este encabezado solo se devuelve cuando la solicitud tiene este encabezado.For versions 2019-02-02 or later, This header is only returned when the request has this header.
x-ms-content-crc64 En las versiones 2019-02-02 o posteriores, este encabezado se devuelve para que el cliente pueda comprobar la integridad del contenido del mensaje.For versions 2019-02-02 or later, This header is returned so that the client can check for message content integrity. El valor de este encabezado lo calcula el servicio Blob; no es necesariamente el mismo valor que el especificado en los encabezados de solicitud.The value of this header is computed by the Blob service; it is not necessarily the same value specified in the request headers.

Este encabezado se devuelve cuando x-ms-source-content-md5 el encabezado no está presente en la solicitud.This header is returned when x-ms-source-content-md5 header is not present in the request.
x-ms-request-idx-ms-request-id Este encabezado identifica de forma única la solicitud que se realizó y se puede utilizar para solucionar problemas relacionados con esta.This header uniquely identifies the request that was made and can be used for troubleshooting the request. Para obtener más información, vea Solucionar problemas relacionados con las operaciones de la API.For more information, see Troubleshooting API Operations.
x-ms-versionx-ms-version Indica la versión del servicio Blob utilizado para ejecutar la solicitud.Indicates the version of the Blob service used to execute the request. Este encabezado se devuelve para las solicitudes realizadas en la versión 2009-09-19 y versiones posteriores.This header is returned for requests made against version 2009-09-19 and later.
FechaDate Valor de fecha y hora UTC generado por el servicio que indica la hora a la que se inició la respuesta.A UTC date/time value generated by the service that indicates the time at which the response was initiated.
x-MS-BLOB-Append-offsetx-ms-blob-append-offset Este encabezado de respuesta solo se devuelve para las operaciones de anexión.This response header is returned only for append operations. Devuelve el desplazamiento en el que se confirmó el bloque, en bytes.It returns the offset at which the block was committed, in bytes.
x-MS-BLOB-Committed-Block-Countx-ms-blob-committed-block-count El número de bloques confirmados presentes en el BLOB.The number of committed blocks present in the blob. Se puede utilizar para controlar el número de más anexos que se pueden realizar.This can be used to control how many more appends can be done.
x-ms-request-server-encrypted: true/false Versión 2015-12-11 o posterior.Version 2015-12-11 or newer. El valor de este encabezado se establece en true si el contenido de la solicitud se cifra correctamente mediante el algoritmo especificado; de false lo contrario,.The value of this header is set to true if the contents of the request are successfully encrypted using the specified algorithm, and false otherwise.
x-ms-encryption-key-sha256 Versión 2019-02-02 o posterior.Version 2019-02-02 or newer. Se devuelve este encabezado 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 con la clave proporcionada.This header is returned if the request used a customer-provided key for encryption, so the client can ensure the contents of the request are successfully encrypted using the provided key.
x-ms-encryption-scope Versión 2019-02-02 o posterior.Version 2019-02-02 or newer. Este encabezado se devuelve si la solicitud usaba un ámbito de cifrado, por lo que el cliente puede asegurarse de que el contenido de la solicitud se cifre correctamente mediante el ámbito de cifrado.This header is returned if the request used an encryption scope, so the client can ensure the contents of the request are successfully encrypted using the encryption scope.

Respuesta de ejemploSample Response

Response Status:  
HTTP/1.1 201 Created  

Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: <date>  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-blob-append-offset: 2097152  
x-ms-blob-committed–block-count: 1000  

AuthorizationAuthorization

La llamada a esta operación la puede realizar el propietario de la cuenta y cualquiera que disponga de una firma de acceso compartido con permiso para escribir en el blob o en su contenedor.This operation can be called by the account owner and by anyone with a Shared Access Signature that has permission to write to this blob or its container.

ComentariosRemarks

El bloque Append de la dirección URL carga un bloque en el final de un BLOB en anexos existente.Append Block From URL uploads a block to the end of an existing append blob. El bloque de datos está disponible inmediatamente una vez que la llamada se realiza correctamente en el servidor.The block of data is immediately available once the call succeeds on the server. Un bloque puede tener un tamaño máximo de 4 MiB.A block may be up to 4 MiB in size.

Append Block From URL solo se realiza correctamente si el BLOB ya existe.Append Block From URL succeeds only if the blob already exists.

Los blobs cargados con no Append Block From URL exponen identificadores de bloque, por lo que no se puede llamar a Get Block List en un BLOB en anexos.Blobs uploaded using Append Block From URL do not expose block ids, so you cannot call Get Block List against an append blob. Si lo hace, se producirá un error 409.Doing so results in a 409 error.

En la solicitud se pueden especificar los siguientes encabezados condicionales opcionales:The following optional conditional headers can be specified on the request:

  1. x-ms-blob-condition-appendpos: Puede establecer este encabezado en un desplazamiento de bytes en el que el cliente espera anexar el bloque.x-ms-blob-condition-appendpos: You can set this header to a byte offset at which the client expects to append the block. La solicitud se realiza correctamente solo si el desplazamiento actual coincide con el especificado por el cliente.The request succeeds only if the current offset matches that specified by the client. De lo contrario, se produce un error en la solicitud con el error AppendPositionConditionNotMet (código de Estado HTTP 412 – error de condición previa).Otherwise, the request fails with the AppendPositionConditionNotMet error (HTTP status code 412 – Precondition Failed).

    Los clientes que usan un solo escritor pueden utilizar este encabezado para determinar si un bloque Append de la operación de dirección URL tuvo éxito a pesar de un error de red.Clients using a single writer may use this header to determine whether when an Append Block From URL operation succeeded despite network failure.

  2. x-ms-blob-condition-maxsize: Los clientes pueden utilizar este encabezado para asegurarse de que las operaciones de anexión no aumentan el tamaño del BLOB más allá del tamaño máximo esperado en bytes.x-ms-blob-condition-maxsize: Clients can use this header to ensure that append operations do not increase the blob size beyond an expected maximum size in bytes. Si se produce un error en la condición, se producirá un error MaxBlobSizeConditionNotMet en la solicitud (código de Estado HTTP 412 – error de condición previa).If the condition fails, the request will fail with MaxBlobSizeConditionNotMet error (HTTP status code 412 – Precondition Failed).

Cada bloque puede tener un tamaño diferente, hasta un máximo de 4 MiB.Each block can be a different size, up to a maximum of 4 MiB. Se permite un máximo de 50.000 anexos para cada BLOB en anexos.A maximum of 50,000 appends are permitted for each append blob. Por lo tanto, el tamaño máximo de un BLOB en anexos es ligeramente superior a 195 GiB (4 unidades MiB X 50.000).The maximum size of an append blob is therefore slightly more than 195 GiB (4 MiB X 50,000 blocks). Si intenta cargar un bloque mayor que 4 MiB, el servicio devuelve el código de Estado HTTP 413 (entidad de solicitud demasiado grande).If you attempt to upload a block that is larger than 4 MiB, the service returns HTTP status code 413 (Request Entity Too Large). El servicio Blob también devuelve información adicional sobre el error en la respuesta, incluyendo el tamaño máximo de bloque permitido en bytes.The service also returns additional information about the error in the response, including the maximum block size permitted in bytes. Si intenta cargar más de 50.000 bloques, el servicio devuelve el error BlockCountExceedsLimit (código de Estado HTTP 409: conflicto).If you attempt to upload more than 50,000 blocks, the service returns the BlockCountExceedsLimit error (HTTP status code 409 – Conflict).

Si el blob tiene una concesión activa, el cliente debe especificar un identificador de concesión válido en la solicitud para poder escribir un bloque en el blob.If the blob has an active lease, the client must specify a valid lease ID on the request in order to write a block to the blob. Si el cliente no especifica un identificador de concesión o especifica un identificador de concesión no válido, Blob service devuelve el código de estado 412 (Error de condición previa).If the client does not specify a lease ID, or specifies an invalid lease ID, the Blob service returns status code 412 (Precondition Failed). Si el cliente especifica un identificador de concesión, pero el blob no dispone de una concesión activa, el servicio Blob también devuelve el código de estado 412 (Error de condición previa).If the client specifies a lease ID but the blob does not have an active lease, the Blob service also returns status code 412 (Precondition Failed).

La llamada a Append Block from URL en un BLOB en bloques o en una página existente devolverá un error InvalidBlobType (código de estado http 409-Conflict).Calling Append Block From URL on an existing block blob or page blob will return an InvalidBlobType error (HTTP status code 409 - Conflict). La llamada al bloque Append de la dirección URL en un BLOB no existente devolverá un error BlobNotFound (código de estado http 404 – no encontrado).Calling Append Block From URL on a non-existent blob will return a BlobNotFound error (HTTP status code 404 – Not Found).

Evitar anexados duplicados o retrasadosAvoiding duplicate or delayed appends

En un escenario de escritor único, el cliente puede evitar anexados duplicados o escrituras diferidas mediante el encabezado condicional x-MS-BLOB-Condition-appendpos para comprobar el desplazamiento actual o comprobando el ETag condicionalmente mediante If-Match .In a single writer scenario, the client can avoid duplicate appends or delayed writes either by using the x-ms-blob-condition-appendpos conditional header to check the current offset, or by checking the ETag conditionally using If-Match.

En un escenario de varios escritores, cada cliente puede usar encabezados condicionales, pero puede que no sea un enfoque óptimo en cuanto al rendimiento.In a multiple writer scenario, each client can use conditional headers, but this may not be an optimal approach in terms of performance. Para obtener el máximo rendimiento de los anexos simultáneos, las aplicaciones deben administrar los anexos redundantes y los agregados retrasados en su nivel de aplicación (por ejemplo, agregar tiempos o números de secuencia en los datos que se van a anexar).For the highest concurrent append throughput, applications should handle redundant appends and delayed appends in their application layer (e.g., add epochs or sequence numbers in the data being appended).