Copiar archivo
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:
|
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:
|
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-TypeContent-EncodingContent-LanguageContent-LengthCache-ControlContent-MD5Content-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.