Put Range From URL

Artículo
03/29/2023

La Put Range From URL operación crea un nuevo intervalo que se va a confirmar como parte de un archivo donde el contenido se lee desde una dirección URL. Esta API está disponible a partir de la versión 2019-02-02.

Disponibilidad del protocolo

Protocolo de recurso compartido de archivos habilitado	Disponible
SMB
NFS

Solicitud

La solicitud Put Range From URL se puede construir como sigue. Se recomienda usar HTTPS. Reemplace myaccount por el nombre de la cuenta de almacenamiento:

Método	URI de solicitud	Versión de HTTP
`PUT`	`https://myaccount.file.core.windows.net/myshare/myfile?comp=range`	HTTP/1.1

Parámetros del identificador URI

Parámetro	Descripción
`timeout`	Opcional. El parámetro `timeout` se expresa en segundos. Para obtener más información, consulte Establecer tiempos de espera para las operaciones de Azure Files.

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 la 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`	Obligatorio para todas las solicitudes autorizadas. 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. Para `Put Range From URL`, la versión debe ser 2019-02-02 o posterior.
`x-ms-copy-source:name`	Necesario. Especifica la dirección URL del archivo de origen. El valor puede ser una dirección URL de hasta 2 KiB de longitud que especifica un archivo. El valor debe estar codificado para URL tal y como aparecería en un URI de solicitud. El archivo de origen debe ser público o debe estar autorizado a través de una firma de acceso compartido. Si el archivo de origen es público, no se requiere ninguna autorización para realizar la operación. Estos son algunos ejemplos de direcciones URL de objeto de origen: `https://myaccount.file.core.windows.net/myshare/mydir/myfile` `https://myaccount.file.core.windows.net/myshare/mydir/myfile?<sastoken>`
`x-ms-copy-source-authorization: <scheme> <signature>`	Opcional. Especifica el esquema de autorización y la firma del origen de copia. Para obtener más información, vea Autorización de solicitudes a Azure Storage. Solo se admite el portador del esquema para Azure Active Directory. Este encabezado se admite en la versión 2020-10-02 y posteriores.
`x-ms-write: { update }`	Necesario. Solo debe especificar `update`. Se produce un error en la solicitud si se llama a con `clear`. El `update` valor escribe los bytes especificados por el cuerpo de la solicitud en los intervalos especificados.
`Range` o `x-ms-range`	Necesario. Es obligatorio especificar `Range` o `x-ms-range`. Especifica el intervalo de bytes que se escribirá. Es necesario especificar tanto el inicio como el final del intervalo. Este encabezado se define mediante la especificación del protocolo HTTP/1.1. Para una operación de actualización, el intervalo puede tener un tamaño de hasta 4 MiB. Azure Files solo acepta un único intervalo de bytes para los `Range` encabezados y `x-ms-range` , y el intervalo de bytes debe especificarse en el formato siguiente: `bytes=startByte-endByte`. Si se especifican `Range` y `x-ms-range`, el servicio utiliza el valor de `x-ms-range`. Para obtener más información, vea Especificar el encabezado de intervalo para las operaciones de Azure Files.
`x-ms-source-range`	Necesario. Especifica el intervalo de bytes que se van a leer desde el origen. Es necesario especificar tanto el inicio como el final del intervalo. Azure Files solo acepta un único intervalo de bytes para los `Range` encabezados y `x-ms-range` , y el intervalo de bytes debe especificarse en el formato siguiente: `bytes=startByte-endByte`. El intervalo de origen puede tener un tamaño de hasta 4 MiB. Si el tamaño del intervalo de origen supera 4 MiB, Azure Files devuelve el código de estado 413 (solicitar entidad demasiado grande). Si el tamaño del intervalo de origen no coincide con el tamaño del intervalo (intervalo de destino), el servicio devuelve el código de estado 400 (solicitud incorrecta).
`Content-Length`	Necesario. Especifica el número de bytes que se transmiten en el cuerpo de la solicitud. El valor de este encabezado debe establecerse en `0`. Cuando la longitud no `0`es , se produce un error en la operación con el código de estado 400 (solicitud incorrecta).
`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, vea Supervisar Azure Files.
`x-ms-source-content-crc64`	Opcional. Hash CRC64 del intervalo especificado desde el URI. Este hash se usa para comprobar la integridad del intervalo durante el transporte de los datos desde el URI. Cuando se especifica este encabezado, Azure Files compara el hash del contenido que ha llegado del origen de copia con este valor de encabezado. Nota: Este hash CRC64 no se almacena con el archivo . Si los dos hash no coinciden, se produce un error en la operación con el código de error 400 (solicitud incorrecta).
`x-ms-source-if-match-crc64`	Opcional. Un valor de suma de comprobación CRC64. Especifique este encabezado para realizar la operación solo si la suma de comprobación del intervalo especificado leído desde el origen coincide con la suma de comprobación proporcionada. Si no se cumple la condición especificada, Azure Files devuelve el código de estado 412 (error de condición previa).
`x-ms-source-if-none-match-crc64`	Opcional. Un valor de suma de comprobación CRC64. Especifique este encabezado para realizar la operación solo si la suma de comprobación del intervalo especificado leído del origen es diferente de la suma de comprobación proporcionada. Si no se cumple la condición especificada, Azure Files devuelve el código de estado 412 (error de condición previa).
`x-ms-lease-id:<ID>`	Obligatorio si el archivo tiene una concesión activa. Para realizar esta operación en un archivo con una concesión activa, especifique el identificador de concesión válido para 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 de análisis cuando azure Storage Analytics registro está habilitado. Se recomienda encarecidamente usar este encabezado al correlacionar las actividades del lado cliente con las solicitudes recibidas por el servidor. Para más información, consulte Supervisión de Blob Storage.
`x-ms-file-last-write-time: { now ¦ preserve }`	Opcional. Versión 2021-06-08 y posteriores. Puede especificar una de las opciones siguientes: `now`: valor predeterminado. Novedades la última marca de tiempo de escritura en la hora de la solicitud. `preserve`: mantiene la marca de tiempo de última escritura existente sin cambios.
`x-ms-file-request-intent`	Obligatorio si `Authorization` el encabezado especifica un token de OAuth. El valor aceptable es `backup`. Este encabezado especifica que se debe conceder o `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/actionMicrosoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` si se incluyen en la directiva de RBAC asignada a la identidad autorizada mediante el `Authorization` encabezado . Disponible para la versión 2022-11-02 y posteriores.
`x-ms-allow-trailing-dot: { <Boolean> }`	Opcional. Versión 2022-11-02 y posteriores. El valor booleano especifica si se debe recortar o no un punto final presente en la dirección URL de la solicitud. Para obtener más información, consulte Nomenclatura y referencia a recursos compartidos, directorios, archivos y metadatos.
`x-ms-source-allow-trailing-dot: { <Boolean> }`	Opcional. Versión 2022-11-02 y posteriores. El valor booleano especifica si se debe recortar o no un punto final presente en la dirección URL de origen. Este encabezado solo se debe especificar si el origen de copia es un archivo de Azure. Este encabezado no se admite para ningún otro tipo de origen de copia. Para obtener más información, consulte Nomenclatura y referencia a recursos compartidos, directorios, archivos y metadatos.

Cuerpo de la solicitud

Sin cuerpo de la solicitud.

Solicitud de ejemplo

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/mydir/myfile?comp=range HTTP/1.1  
  
Request Headers:  
x-ms-page-write: update  
x-ms-copy-source: http://myaccount2.file.core.windows.net/myshare2/mydirectory2/myfile2?sv=2018-11-09&sp=r&sr=s&se=2018-08-22T09%3A59%3A28.2185790Z&sig=Qn6QEET3Gn%2FhCEVcXuwG7ssatIYiYRM5pNIy4Q3N0cQ%3D 
x-ms-date: Fri, 22 Aug 2018 01:15:50 GMT  
x-ms-version: 2019-02-02 
x-ms-range: bytes=100-1023  
x-ms-source-range: bytes=200-1123  
x-ms-source-content-crc64: 3bedb8b3730fc205 
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 0

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 más 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.

Encabezado de respuesta	Descripción
`ETag`	Contiene un valor que puede usar para realizar operaciones condicionalmente. El valor se incluye entre comillas.
`Last-Modified`	Fecha y hora en que se modificó por última vez el archivo. El formato de la fecha sigue las convenciones de RFC 1123. Para obtener más información, vea Representación de valores de fecha y hora en encabezados. Cualquier operación de escritura en el archivo, incluidas las actualizaciones de los metadatos o propiedades del archivo, cambia la hora de la última modificación del archivo.
`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 la API FileREST que se usó para ejecutar la solicitud.
`Date`	Valor de fecha y hora UTC generado por el servicio, que indica la hora a la que se inició la respuesta.
`x-ms-content-crc64`	Se devuelve para que el cliente pueda comprobar la integridad del contenido del mensaje. El valor de este encabezado se calcula mediante Azure Files. No es necesariamente el mismo que el valor especificado en los encabezados de solicitud.
`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 estará presente en la respuesta.
`x-ms-file-last-write-time`	Versión 2021-06-08 y posteriores. La última hora de escritura del archivo, en formato ISO 8601 (por ejemplo, `2017-05-10T17:52:33.9551861Z`).

Respuesta de muestra

Response Status:  
HTTP/1.1 201 Created  

Response Headers:
Date: Sun, 22 Aug 2020 01:33:35 GMT  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: Wed, 22 Aug 2020 01:13:31 GMT  
x-ms-version: 2019-02-02
x-ms-content-crc64: 3bedb8b3730fc205 
Content-Length: 0  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0

Authorization

El propietario de la cuenta puede llamar a esta operación y a cualquier persona con una firma de acceso compartido con permisos para escribir en este archivo o en el recurso compartido de archivos de Azure.

Observaciones

La Put Range From URL operación escribe un intervalo de datos en un archivo. Si se llama a la API en un archivo no existente en el destino, la API devuelve el código de estado HTTP 404 (no encontrado).

En la versión 2020-10-02 y posteriores, se admite la autorización de Azure Active Directory para el origen de la operación de copia.

Para crear un nuevo archivo, llame a Create File.

Put Range From URL operation devuelve success 201 (Created) solo si el intervalo especificado se escribe en el archivo.

Operación de lectura de archivos
Put Range From URL usa Get File para leer datos y metadatos, atributos y ACL del origen.

Operación de actualización de archivos
La llamada Put Range From URL con la opción "update" realiza una escritura en contexto en el archivo especificado. Cualquier contenido del archivo especificado se sobrescribe con la actualización.  

El tamaño del intervalo en la Put Range From URL operación para una operación de actualización puede tener un tamaño de hasta 4 MiB. Si intenta cargar un intervalo mayor que 4 MiB, Azure Files devuelve el código de estado 413 (RequestEntityTooLarge).