Copiar archivo

Artículo
03/29/2023

La Copy File operación copia un blob o un archivo en un archivo de destino dentro de la cuenta de almacenamiento.

Disponible en la versión 2015-02-21 y posteriores.

Disponibilidad del protocolo

Protocolo de recurso compartido de archivos habilitado	Disponible
SMB
NFS

Request

Puede construir la Copy File solicitud como se indica a continuación. Se recomienda HTTPS.

A partir de la versión 2013-08-15, puede especificar una firma de acceso compartido para el archivo de destino si se encuentra en la misma cuenta que el archivo de origen. A partir de la versión 2015-04-05, también puede especificar una firma de acceso compartido para el archivo de destino si se encuentra en otra cuenta de almacenamiento.

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

Reemplace los componentes de la ruta de acceso que se muestran en el URI de solicitud por los suyos de la siguiente manera:

Componente de ruta de acceso	Descripción
`myaccount`	El nombre de la cuenta de almacenamiento.
`myshare`	El nombre del recurso compartido de archivos.
`mydirectorypath`	Opcional. La ruta de acceso al directorio principal.
`myfile`	Nombre del archivo.

Para más información sobre las restricciones de nomenclatura de rutas de acceso, consulte Nomenclatura y referencia a recursos compartidos, directorios, archivos y metadatos.

Parámetros del identificador URI

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

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

Encabezados de solicitud

En la tabla siguiente se describen los encabezados de solicitud obligatorios y opcionales:

Encabezado de solicitud	Descripción
`Authorization`	Necesario. Especifica el esquema de autorización, el nombre de la 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. Especifica la versión de la operación que se utiliza para esta solicitud. Esta operación solo está disponible en la versión 2015-02-21 y posteriores. Para obtener más información, vea Versiones de los servicios de Azure Storage.
`x-ms-meta-name:value`	Opcional. Especifica los pares nombre-valor asociados al archivo como metadatos. Si no se especifican pares nombre-valor, la operación copia los metadatos del blob o archivo de origen en el archivo de destino. Si se especifican uno o varios pares nombre-valor, el archivo de destino se crea con los metadatos especificados y los metadatos no se copian del blob o archivo de origen. Los nombres de metadatos deben cumplir las reglas de nomenclatura de los identificadores de C#. Tenga en cuenta que los metadatos de archivo especificados a través de Azure Files no son accesibles desde un cliente SMB.
`x-ms-copy-source:name`	Necesario. Especifica la dirección URL del archivo de origen o el blob, hasta 2 kibibytes (KiB) de longitud. Para copiar un archivo en otro archivo dentro de la misma cuenta de almacenamiento, puede usar una clave compartida para autorizar el archivo de origen. Si va a copiar un archivo desde otra cuenta de almacenamiento o si va a copiar un blob desde la misma cuenta de almacenamiento u otra cuenta de almacenamiento, debe autorizar el archivo de origen o el blob mediante una firma de acceso compartido. Si el origen es un blob público, no se requiere ninguna autorización para realizar la operación de copia. También puede especificar un archivo en una instantánea de recurso compartido como origen de copia. Estos son algunos ejemplos de direcciones URL de objeto de origen: `https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile` `https://myaccount.blob.core.windows.net/mycontainer/myblob?sastoken` `http://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>`
`x-ms-lease-id:<ID>`	Obligatorio si el archivo de destino tiene una concesión activa. Disponible para la versión 2019-02-02 y posteriores. El identificador de concesión especificado para este encabezado debe coincidir con el identificador de concesión del archivo de destino. Si la solicitud no incluye el identificador de concesión o el identificador no es válido, se produce un error en la operación con el código de estado 412 (error de condición previa). Si se especifica este encabezado y el archivo de destino no tiene actualmente una concesión activa, se produce un error en la operación con el código de estado 412 (Error de condición previa).
`x-ms-file-permission-copy-mode: { source ¦ override }`	Opcional. Disponible para la versión 2019-07-07 y posteriores. Determina el comportamiento de copia del descriptor de seguridad del archivo: `source`: el descriptor de seguridad del archivo de destino se copia del archivo de origen. `override`: el descriptor de seguridad del archivo de destino se determina a través del `x-ms-file-permission` encabezado o `x-ms-file-permission-key` .
`x-ms-file-permission`	Obligatorio si `x-ms-file-permission-copy-mode` se especifica como `override` y `x-ms-file-permission-key` no se especifica. Disponible para la versión 2019-07-07 y posteriores. Este permiso es el descriptor de seguridad del archivo especificado en el Lenguaje de definición de descriptores de seguridad (SDDL). Puede usar este encabezado si el tamaño de los permisos es de 8 kibibytes (KiB) o menos. De lo contrario, puede usar `x-ms-file-permission-key`. Si se especifica, debe tener un propietario, un grupo y una lista de control de acceso discrecional (DACL). Tenga en cuenta que solo se puede especificar uno de `x-ms-file-permission` o `x-ms-file-permission-key` .
`x-ms-file-permission-key`	Obligatorio si `x-ms-file-permission-copy-mode` se especifica como `override` y `x-ms-file-permission` no se especifica. Disponible para la versión 2019-07-07 y posteriores. Este encabezado especifica la clave del permiso que se va a establecer para el archivo. Puede crear esta clave mediante la `Create Permission` operación . Tenga en cuenta que solo se puede especificar uno de `x-ms-file-permission` o `x-ms-file-permission-key` .
`x-ms-file-copy-ignore-readonly`	Opcional. Disponible para la versión 2019-07-07 y posteriores. Este valor booleano especifica si se debe respetar el `ReadOnly` atributo en un archivo de destino preexistente. Si es `true`, la operación de copia se realiza correctamente. De lo contrario, un archivo anterior en el destino con el `ReadOnly` conjunto de atributos hace que se produzca un error en la operación de copia.
`x-ms-file-attributes`	Opcional. Disponible para la versión 2019-07-07 y posteriores. Este encabezado especifica los atributos del sistema de archivos que se van a establecer en el archivo de destino. Consulte la lista de atributos disponibles. Puede usar un valor de `source` para copiar los atributos del archivo de origen en el archivo de destino. Puede usar un valor de `none` para borrar todos los atributos del archivo de destino.
`x-ms-file-creation-time`	Opcional. Disponible para la versión 2019-07-07 y posteriores. Este encabezado especifica la propiedad para la hora de creación, en UTC, que se va a establecer en el archivo de destino. Puede usar un valor de para copiar la hora de `source` creación del archivo de origen en el archivo de destino.
`x-ms-file-last-write-time`	Opcional. Disponible para la versión 2019-07-07 y posteriores. Este encabezado especifica la propiedad de la hora de última escritura, en UTC, para establecer en el archivo de destino. Puede usar un valor de para copiar la última hora de `source` escritura del archivo de origen en el archivo de destino.
`x-ms-file-copy-set-archive`	Opcional. Disponible para la versión 2019-07-07 y posteriores. Este valor booleano especifica si se debe establecer el `Archive` atributo, independientemente del valor de `x-ms-file-attributes` encabezado.
`x-ms-client-request-id`	Opcional. Proporciona un valor opaco generado por el cliente con un límite de caracteres de 1 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.
`x-ms-file-change-time: { <DateTime> ¦ source }`	Opcional. Versión 2021-06-08 y posteriores. La propiedad hora de cambio UTC del archivo, con formato ISO 8601. Se puede usar un valor de `source` para copiar la hora de cambio del archivo de origen al archivo de destino. La marca de tiempo predeterminada es la hora de la solicitud.
`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 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 debe especificarse si el origen de copia es un archivo de Azure. Este encabezado no es compatible con 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

Ninguno.

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 202 (Aceptado).

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 incluye 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`	Si se completa la operación de copia, contiene el `ETag` valor del archivo de destino. Si no se completa la operación de copia, contiene el `ETag` valor del archivo vacío creado al principio de la operación.
`Last-Modified`	Devuelve la fecha y hora en que finalizó la operación de copia en el archivo de destino.
`x-ms-request-id`	Identifica de forma única la solicitud que se realizó. Puede usar este encabezado 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 Azure Files que se usa para ejecutar la solicitud.
`Date`	Valor de fecha y hora UTC que indica la hora en la que el servicio envió la respuesta.
`x-ms-copy-id: <id>`	Proporciona un identificador de cadena para esta operación de copia. Use con `Get File` o `Get File Properties` para comprobar el estado de esta operación de copia o pasar para `Abort Copy File` cancelar una operación de copia pendiente.
`x-ms-copy-status: <success ¦ pending>`	Indica el estado de la operación de copia con estos valores: - `success`: la operación de copia finalizó correctamente. - `pending`: la operación de copia sigue en curso.
`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 es como máximo de 1024 caracteres ASCII visibles. Si el `x-ms-client-request-id` encabezado no está presente en la solicitud, este encabezado no estará presente en la respuesta.

Response body

Ninguno

Respuesta de muestra

Response Status:  
HTTP/1.1 202 Accepted  
  
Response Headers:   
Last-Modified: <date>   
ETag: "0x8CEB669D794AFE2"  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402  
x-ms-version: 2015-02-21  
x-ms-copy-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
x-ms-copy-status: pending  
Date: <date>

Authorization

El propietario de la cuenta puede llamar a esta operación o un cliente que posee una firma de acceso compartido que tiene permiso para escribir en el archivo de destino o en su recurso compartido. Tenga en cuenta que la firma de acceso compartido especificada en la solicitud solo se aplica al archivo de destino.

El acceso al archivo de origen o al blob se autoriza por separado, como se describe en los detalles del encabezado x-ms-copy-sourcede solicitud .

En la tabla siguiente se describe cómo se pueden autorizar los objetos de destino y origen de una Copy File operación:

Archivo	Autorización con clave compartida o clave compartida Lite	Autorización con firma de acceso compartido	Objeto público que no requiere autorización
Archivo de destino	Sí	Sí	No aplicable
Archivo de origen en la misma cuenta	Sí	Sí	No aplicable
Archivo de origen en otra cuenta	No	Sí	No aplicable
Blob de origen en la misma cuenta u otra cuenta	No	Sí	Sí

Atributos del sistema de archivos

Atributo	Atributo de archivo Win32	Definición
`ReadOnly`	`FILE_ATTRIBUTE_READONLY`	El archivo es de solo lectura. Las aplicaciones pueden leer el archivo, pero no pueden escribir en él ni eliminarlo.
`Hidden`	`FILE_ATTRIBUTE_HIDDEN`	El archivo está oculto. No se incluye en una lista de directorios normal.
`System`	`FILE_ATTRIBUTE_SYSTEM`	El sistema operativo usa una parte del archivo, o usa el archivo exclusivamente.
`None`	`FILE_ATTRIBUTE_NORMAL`	El archivo no tiene otros atributos establecidos. Este atributo solo es válido cuando se usa solo.
`Archive`	`FILE_ATTRIBUTE_ARCHIVE`	El archivo es un archivo de archivado. Las aplicaciones suelen usar este atributo para marcar los archivos de copia de seguridad o eliminación.
`Temporary`	`FILE_ATTRIBUTE_TEMPORARY`	El archivo se usa para el almacenamiento temporal.
`Offline`	`FILE_ATTRIBUTE_OFFLINE`	Los datos del archivo no están disponibles inmediatamente. Este atributo del sistema de archivos proporciona principalmente compatibilidad con Windows. Azure Files no lo admite con opciones de almacenamiento sin conexión.
`NotContentIndexed`	`FILE_ATTRIBUTE_NOT_CONTENT_INDEXED`	El servicio de indexación de contenido no indexa el archivo.
`NoScrubData`	`FILE_ATTRIBUTE_NO_SCRUB_DATA`	El analizador de integridad de datos en segundo plano no leerá el flujo de datos del usuario. Este atributo del sistema de archivos proporciona principalmente compatibilidad con Windows.

Comentarios

La Copy File operación puede finalizar de forma asincrónica. Puede usar el identificador de copia que devuelve el x-ms-copy-id encabezado de respuesta para comprobar el estado de la operación de copia o cancelarlo. Azure Files copia los archivos de la mejor manera posible.

Si el archivo de destino existe, se sobrescribirá. No se puede modificar el archivo de destino mientras la operación de copia está en curso.

La Copy File operación siempre copia todo el blob o archivo de origen. ya que no se admite la copia de un intervalo de bytes o un conjunto de bloques.

El origen de una Copy File operación puede ser un archivo que reside en una instantánea de recurso compartido. El destino de una Copy File operación no puede ser un archivo que resida en una instantánea de recurso compartido.

Cuando el origen de una operación de copia proporciona ETag valores, si hay algún cambio en el origen mientras la operación está en curso, se producirá un error. Se producirá un error al intentar cambiar el archivo de destino mientras una operación de copia está en curso con el código de estado 409 (conflicto).

El ETag valor del archivo de destino cambia cuando se inicia la Copy File operación. Continúa modificando con frecuencia durante la operación de copia.

Copiar propiedades y metadatos

Cuando se copia un blob o un archivo, se copian las siguientes propiedades del sistema en el archivo de destino con los mismos valores:

Content-Type
Content-Encoding
Content-Language
Content-Length
Cache-Control
Content-MD5
Content-Disposition

El archivo de destino siempre tiene el mismo tamaño que el blob o archivo de origen. El valor del Content-Length encabezado del archivo de destino coincide con el valor de ese encabezado para el blob o archivo de origen.

Copia de un blob o un archivo concedidos a un archivo

La Copy File operación solo lee del blob o archivo de origen, por lo que una concesión en el objeto de origen no afecta a la operación. La Copy File operación guarda el ETag valor del blob o archivo de origen cuando se inicia la operación. Si el ETag valor cambia antes de que finalice la operación de copia, se produce un error en la operación. Puede evitar cambios en el blob de origen del archivo al alquilarlo durante la operación de copia.

Si el archivo de destino tiene una concesión infinita activa, debe especificar su identificador de concesión en la llamada a la Copy File operación. Mientras la operación de copia está pendiente, se produce un error en cualquier operación de concesión en el archivo de destino con el código de estado 409 (conflicto). Una concesión infinita en el archivo de destino se bloquea de esta manera durante la operación de copia, independientemente de si va a copiar en un archivo de destino que tenga un nombre diferente del origen o copiado en un archivo de destino que tenga el mismo nombre que el origen. Si el cliente especifica un identificador de concesión en un archivo que aún no existe, Azure Files devuelve el código de estado 412 (error de condición previa).

Trabajar con una operación de copia pendiente

La Copy File operación podría terminar de copiar los archivos de forma asincrónica. Use la tabla siguiente para determinar el paso siguiente en función del código de estado que Copy File devuelve:

status code	Significado
202 (Aceptado), x-ms-copy-status: success	La operación de copia finalizó correctamente.
202 (Aceptado), x-ms-copy-status: pending	La operación de copia no ha finalizado. Sondee el blob de destino mediante `Get File Properties` para examinar `x-ms-copy-status` hasta que finalice o se produzca un error en la operación de copia.
4xx, 500 o 503	Error en la operación de copia.

Durante y después de una Copy File operación, las propiedades del archivo de destino contienen el identificador de copia de la Copy File operación y la dirección URL del blob o archivo de origen. Cuando finalice la operación, Azure Files escribe el valor de tiempo y resultado (success, failedo aborted) en las propiedades del archivo de destino. Si la operación tiene un failed resultado, el x-ms-copy-status-description encabezado contiene una cadena de detalles de error.

Una operación pendiente Copy File tiene un tiempo de espera de dos semanas. Intento de copia que no ha terminado después de dos semanas de espera y deja un archivo vacío con el x-ms-copy-status campo establecido failed en y el x-ms-status-description campo establecido en 500 (OperationCancelled). Los errores intermitentes y no irrecuperables que pueden producirse durante una operación de copia pueden impedir el progreso de la operación, pero no provocar que se produzca un error. En estos casos, x-ms-copy-status-description describe los errores intermitentes.

Cualquier intento de modificar el archivo de destino durante la operación de copia producirá un error con el código de estado 409 (conflicto), "Copiar archivo en curso".

Si llama a una Abort Copy File operación, verá un x-ms-copy-status:aborted encabezado. El archivo de destino tendrá metadatos intactos y una longitud de archivo de 0 bytes. Puede repetir la llamada original a para volver a Copy File intentar la operación.

Facturación

La cuenta de destino de una operación se cobra por una Copy File transacción para iniciar la operación. La cuenta de destino también incurre en una transacción para cada solicitud para cancelar o solicitar el estado de la operación de copia.

Cuando el archivo de origen o el blob están en otra cuenta, la cuenta de origen incurre en costos de transacción. Además, si las cuentas de origen y destino residen en regiones diferentes (por ejemplo, Norte de EE. UU. y Sur de EE. UU.), el ancho de banda que usa para transferir la solicitud se cobra a la cuenta de origen como salida. Las salidas entre cuentas de la misma región son gratuitas.