Copier le fichier
L’opération Copy File copie un objet blob ou un fichier dans un fichier de destination dans le compte de stockage.
Disponible dans la version 2015-02-21 et ultérieure.
Disponibilité du protocole
| Protocole de partage de fichiers activé | Disponible |
|---|---|
| SMB |
|
| NFS |
|
Requête
Vous pouvez construire la Copy File requête comme suit. Nous recommandons HTTPS.
À compter de la version 2013-08-15, vous pouvez spécifier une signature d’accès partagé pour le fichier de destination s’il se trouve dans le même compte que le fichier source. À compter de la version 2015-04-05, vous pouvez également spécifier une signature d’accès partagé pour le fichier de destination s’il se trouve dans un autre compte de stockage.
| Méthode | URI de demande | Version HTTP |
|---|---|---|
PUT |
https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
HTTP/1.1 |
Remplacez les composants du chemin indiqués dans l'URI de la demande par les vôtres, comme suit :
| Composant Path | Description |
|---|---|
myaccount |
nom de votre compte de stockage. |
myshare |
Nom du partage de fichiers. |
mydirectorypath |
facultatif. Chemin d'accès au répertoire parent. |
myfile |
Nom du fichier. |
Pour plus d’informations sur les restrictions de nommage de chemin d’accès, consultez Affectation de noms et référencement de partages, répertoires, fichiers et métadonnées.
Paramètres URI
Vous pouvez spécifier les paramètres supplémentaires suivants dans l’URI de requête :
| Paramètre | Description |
|---|---|
timeout |
facultatif. Le paramètre timeout est exprimé en secondes. Pour plus d’informations, consultez Définir des délais d’expiration pour les opérations de Azure Files. |
En-têtes de requête
Le tableau suivant décrit les en-têtes de requête obligatoires et facultatifs :
| En-tête de requête | Description |
|---|---|
Authorization |
Obligatoire. Spécifie le schéma d’autorisation, le nom du compte et la signature. Pour plus d’informations, consultez Autoriser les requêtes auprès du Stockage Azure. |
Date ou x-ms-date |
Obligatoire. Spécifie la date/heure en temps universel coordonné (UTC) pour la requête. Pour plus d’informations, consultez Autoriser les requêtes auprès du Stockage Azure. |
x-ms-version |
Obligatoire pour toutes les demandes autorisées. Spécifie la version de l'opération à utiliser pour cette demande. Cette opération est disponible uniquement dans la version 2015-02-21 et ultérieure. Pour plus d'informations, consultez la page Contrôle de version pour les services de Stockage Microsoft Azure. |
x-ms-meta-name:value |
facultatif. Spécifie les paires nom/valeur associées au fichier en tant que métadonnées. Si aucune paire nom/valeur n’est spécifiée, l’opération copie les métadonnées de l’objet blob ou du fichier source dans le fichier de destination. Si une ou plusieurs paires nom/valeur sont spécifiées, le fichier de destination est créé avec les métadonnées spécifiées et les métadonnées ne sont pas copiées à partir de l’objet blob ou du fichier source. Les noms de métadonnées doivent respecter les règles d’affectation de noms pour les identificateurs C#. Notez que les métadonnées de fichier spécifiées via Azure Files ne sont pas accessibles à partir d’un client SMB. |
x-ms-copy-source:name |
Obligatoire. Spécifie l’URL du fichier ou de l’objet blob source, d’une longueur maximale de 2 Kibioctets (Kio). Pour copier un fichier dans un autre fichier dans le même compte de stockage, vous pouvez utiliser une clé partagée pour autoriser le fichier source. Si vous copiez un fichier à partir d’un autre compte de stockage, ou si vous copiez un objet blob à partir du même compte de stockage ou d’un autre compte de stockage, vous devez autoriser le fichier source ou l’objet blob à l’aide d’une signature d’accès partagé. Si la source est un objet blob public, aucune autorisation n’est requise pour effectuer l’opération de copie. Vous pouvez également spécifier un fichier dans un partage instantané comme source de copie. Voici quelques exemples d’URL d’objet source :
|
x-ms-lease-id:<ID> |
Obligatoire si le fichier de destination a un bail actif. Disponible pour la version 2019-02-02 et ultérieure. L’ID de bail spécifié pour cet en-tête doit correspondre à l’ID de bail du fichier de destination. Si la demande n’inclut pas l’ID de bail ou si l’ID n’est pas valide, l’opération échoue avec status code 412 (Échec de la condition préalable). Si cet en-tête est spécifié et que le fichier de destination n’a pas de bail actif, l’opération échoue avec status code 412 (échec de la condition préalable). |
x-ms-file-permission-copy-mode: { source ¦ override } |
facultatif. Disponible pour la version 2019-07-07 et ultérieure. Détermine le comportement de copie du descripteur de sécurité du fichier :
|
x-ms-file-permission |
Obligatoire si x-ms-file-permission-copy-mode est spécifié comme override et x-ms-file-permission-key n’est pas spécifié. Disponible pour la version 2019-07-07 et ultérieure. Cette autorisation est le descripteur de sécurité pour le fichier spécifié dans le langage SDDL (Security Descriptor Definition Language). Vous pouvez utiliser cet en-tête si la taille des autorisations est de 8 Kibioctets (Kio) ou moins. Sinon, vous pouvez utiliser x-ms-file-permission-key. Si elle est spécifiée, elle doit avoir un propriétaire, un groupe et une liste de contrôle d’accès discrétionnaire (DACL). Notez qu’un seul de x-ms-file-permission ou x-ms-file-permission-key peut être spécifié. |
x-ms-file-permission-key |
Obligatoire si x-ms-file-permission-copy-mode est spécifié comme override et x-ms-file-permission n’est pas spécifié. Disponible pour la version 2019-07-07 et ultérieure. Cet en-tête spécifie la clé de l’autorisation à définir pour le fichier. Vous pouvez créer cette clé à l’aide de l’opération Create Permission .Notez qu’un seul de x-ms-file-permission ou x-ms-file-permission-key peut être spécifié. |
x-ms-file-copy-ignore-readonly |
facultatif. Disponible pour la version 2019-07-07 et ultérieure. Cette valeur booléenne spécifie si l’attribut ReadOnly sur un fichier de destination préexistant doit être respecté. S’il s’agit de true, l’opération de copie réussit. Sinon, un fichier précédent à la destination avec le jeu d’attributs ReadOnly entraîne l’échec de l’opération de copie. |
x-ms-file-attributes |
facultatif. Disponible pour la version 2019-07-07 et ultérieure. Cet en-tête spécifie les attributs de système de fichiers à définir sur le fichier de destination. Consultez la liste des attributs disponibles. Vous pouvez utiliser la valeur de source pour copier les attributs du fichier source vers le fichier de destination. Vous pouvez utiliser la valeur pour none effacer tous les attributs du fichier de destination. |
x-ms-file-creation-time |
facultatif. Disponible pour la version 2019-07-07 et ultérieure. Cet en-tête spécifie la propriété pour l’heure de création, en UTC, à définir sur le fichier de destination. Vous pouvez utiliser la valeur de source pour copier l’heure de création du fichier source vers le fichier de destination. |
x-ms-file-last-write-time |
facultatif. Disponible pour la version 2019-07-07 et ultérieure. Cet en-tête spécifie la propriété de l’heure de la dernière écriture, en UTC, à définir sur le fichier de destination. Vous pouvez utiliser la valeur de pour copier l’heure de source la dernière écriture du fichier source vers le fichier de destination. |
x-ms-file-copy-set-archive |
facultatif. Disponible pour la version 2019-07-07 et ultérieure. Cette valeur booléenne spécifie si l’attribut Archive doit être défini, quelle que soit la valeur d’en-tête x-ms-file-attributes . |
x-ms-client-request-id |
facultatif. Fournit une valeur opaque générée par le client avec une limite de caractères de 1 Kio enregistrée dans les journaux lors de la configuration de la journalisation. Nous vous recommandons vivement d’utiliser cet en-tête pour mettre en corrélation les activités côté client avec les demandes reçues par le serveur. Pour plus d’informations, consultez Surveiller Stockage Blob Azure. |
x-ms-file-change-time: { <DateTime> ¦ source } |
facultatif. Version 2021-06-08 et ultérieures. Propriété HEURE DE MODIFICATION UTC pour le fichier, mise en forme au format ISO 8601. Une valeur de source peut être utilisée pour copier l’heure de modification du fichier source vers le fichier de destination. L’horodatage par défaut est l’heure de la demande. |
x-ms-file-request-intent |
Obligatoire si Authorization l’en-tête spécifie un jeton OAuth. La valeur acceptable est backup. Cet en-tête spécifie que le Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action ou Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action doit être accordé s’il est inclus dans la stratégie RBAC affectée à l’identité autorisée à l’aide de l’en-tête Authorization . Disponible pour les versions 2022-11-02 et ultérieures. |
x-ms-allow-trailing-dot: { <Boolean> } |
facultatif. Version 2022-11-02 et ultérieures. La valeur booléenne spécifie si un point de fin présent dans l’URL de requête doit être rogné ou non. Pour plus d’informations, consultez Nommer et référencer des partages, des répertoires, des fichiers et des métadonnées. |
x-ms-source-allow-trailing-dot: { <Boolean> } |
facultatif. Version 2022-11-02 et ultérieures. La valeur booléenne spécifie si un point de fin présent dans l’URL source doit être rogné ou non. Cet en-tête doit être spécifié uniquement si la source de copie est un fichier Azure. Cet en-tête n’est pas pris en charge pour tout autre type de source de copie. Pour plus d’informations, consultez Nommer et référencer des partages, des répertoires, des fichiers et des métadonnées. |
Corps de la demande
Aucun.
response
La réponse inclut un code d'état HTTP et un ensemble d'en-têtes de réponse.
Code d’état
Une opération réussie renvoie le code d'état 202 (Accepté).
Pour plus d’informations sur les codes status, consultez État et codes d’erreur.
En-têtes de réponse
La réponse de l'opération inclut les en-têtes suivants. La réponse peut également inclure des en-têtes HTTP standard supplémentaires. Tous les en-têtes standard sont conformes à la spécification du protocole HTTP/1.1.
| En-tête de réponse | Description |
|---|---|
ETag |
Si l’opération de copie est terminée, contient la ETag valeur du fichier de destination. Si l’opération de copie n’est pas terminée, contient la ETag valeur du fichier vide créé au début de l’opération. |
Last-Modified |
Retourne la date/heure de fin de l’opération de copie dans le fichier de destination. |
x-ms-request-id |
Identifie de manière unique la demande qui a été effectuée. Vous pouvez utiliser cet en-tête pour résoudre les problèmes liés à la demande. Pour plus d’informations, consultez Résoudre les problèmes liés aux opérations d’API. |
x-ms-version |
Indique la version de Azure Files utilisée pour exécuter la demande. |
Date |
Valeur de date/heure UTC qui indique l’heure à laquelle le service a envoyé la réponse. |
x-ms-copy-id: <id> |
Fournit un identificateur de chaîne pour cette opération de copie. Utilisez avec Get File ou Get File Properties pour case activée l’status de cette opération de copie, ou passez à Abort Copy File pour annuler une opération de copie en attente. |
x-ms-copy-status: <success ¦ pending> |
Indique l’état de l’opération de copie avec les valeurs suivantes : - success: l’opération de copie s’est terminée avec succès.- pending: l’opération de copie est toujours en cours. |
x-ms-client-request-id |
Peut être utilisé pour résoudre les demandes et les réponses correspondantes. La valeur de cet en-tête est égale à la valeur de l’en-tête x-ms-client-request-id s’il est présent dans la requête et que la valeur est au maximum de 1 024 caractères ASCII visibles. Si l’en-tête x-ms-client-request-id n’est pas présent dans la demande, cet en-tête ne sera pas présent dans la réponse. |
Response body
None
Exemple de réponse
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>
Autorisation
Cette opération peut être appelée par le propriétaire du compte ou par un client disposant d’une signature d’accès partagé qui a l’autorisation d’écrire dans le fichier de destination ou son partage. Notez que la signature d’accès partagé spécifiée dans la demande s’applique uniquement au fichier de destination.
L’accès au fichier source ou à l’objet blob est autorisé séparément, comme décrit dans les détails de l’en-tête x-ms-copy-sourcede la demande .
Le tableau suivant décrit comment les objets de destination et source d’une Copy File opération peuvent être autorisés :
| Fichier | Autorisation avec une clé partagée ou une clé partagée Lite | Autorisation avec signature d’accès partagé | Objet public ne nécessitant pas d’autorisation |
|---|---|---|---|
| Fichier de destination | Oui | Oui | Non applicable |
| Fichier source dans le même compte | Oui | Oui | Non applicable |
| Fichier source dans un autre compte | Non | Oui | Non applicable |
| Objet blob source dans le même compte ou un autre compte | Non | Oui | Oui |
Attributs du système de fichiers
| Attribut | Attribut de fichier Win32 | Définition |
|---|---|---|
ReadOnly |
FILE_ATTRIBUTE_READONLY |
Le fichier est en lecture seule. Les applications peuvent lire le fichier, mais ne peuvent pas y écrire ni le supprimer. |
Hidden |
FILE_ATTRIBUTE_HIDDEN |
Le fichier est masqué. Il n’est pas inclus dans une liste de répertoires ordinaire. |
System |
FILE_ATTRIBUTE_SYSTEM |
Le système d’exploitation utilise une partie du fichier, ou il utilise le fichier exclusivement. |
None |
FILE_ATTRIBUTE_NORMAL |
Le fichier n’a pas d’autres attributs définis. Cet attribut n’est valide que lorsqu’il est utilisé seul. |
Archive |
FILE_ATTRIBUTE_ARCHIVE |
Le fichier est un fichier archive. Les applications utilisent généralement cet attribut pour marquer les fichiers à des fins de sauvegarde ou de suppression. |
Temporary |
FILE_ATTRIBUTE_TEMPORARY |
Le fichier est utilisé pour le stockage temporaire. |
Offline |
FILE_ATTRIBUTE_OFFLINE |
Les données du fichier ne sont pas disponibles immédiatement. Cet attribut de système de fichiers fournit principalement la compatibilité avec Windows. Azure Files ne le prend pas en charge avec les options de stockage hors connexion. |
NotContentIndexed |
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED |
Le service d’indexation de contenu n’indexe pas le fichier. |
NoScrubData |
FILE_ATTRIBUTE_NO_SCRUB_DATA |
Le scanneur d’intégrité des données d’arrière-plan ne lit pas le flux de données utilisateur. Cet attribut de système de fichiers fournit principalement la compatibilité avec Windows. |
Remarques
L’opération Copy File peut se terminer de manière asynchrone. Vous pouvez utiliser l’ID de copie que l’en-tête x-ms-copy-id de réponse retourne à case activée l’status de l’opération de copie ou pour l’annuler. Azure Files copie les fichiers selon les meilleurs efforts.
Si le fichier de destination existe, il sera remplacé. Vous ne pouvez pas modifier le fichier de destination pendant que l’opération de copie est en cours.
L’opération Copy File copie toujours l’intégralité de l’objet blob ou du fichier source. La copie d’une plage d’octets ou d’un ensemble de blocs n’est pas prise en charge.
La source d’une Copy File opération peut être un fichier qui réside dans un partage instantané. La destination d’une Copy File opération ne peut pas être un fichier qui réside dans un partage instantané.
Lorsque la source d’une opération de copie fournit des ETag valeurs, si des modifications sont apportées à la source pendant que l’opération est en cours, elle échoue. Une tentative de modification du fichier de destination alors qu’une opération de copie est en cours échoue avec status code 409 (Conflit).
La ETag valeur du fichier de destination change lorsque l’opération Copy File démarre. Il continue à changer fréquemment pendant l’opération de copie.
Copie des propriétés et des métadonnées
Lorsqu’un objet blob ou un fichier est copié, les propriétés système suivantes sont copiées dans le fichier de destination avec les mêmes valeurs :
Content-TypeContent-EncodingContent-LanguageContent-LengthCache-ControlContent-MD5Content-Disposition
Le fichier de destination a toujours la même taille que l’objet blob ou le fichier source. La valeur de l’en-tête Content-Length du fichier de destination correspond à la valeur de cet en-tête pour l’objet blob ou le fichier source.
Copie d’un objet blob ou d’un fichier loué dans un fichier
L’opération Copy File lit uniquement à partir de l’objet blob ou du fichier source, de sorte qu’un bail sur l’objet source n’affecte pas l’opération. L’opération Copy File enregistre la ETag valeur du fichier ou de l’objet blob source au démarrage de l’opération. Si la ETag valeur change avant la fin de l’opération de copie, l’opération échoue. Vous pouvez empêcher les modifications apportées à l’objet blob source du fichier en le louant pendant l’opération de copie.
Si le fichier de destination a un bail infini actif, vous devez spécifier son ID de bail dans l’appel à l’opération Copy File . Pendant que l’opération de copie est en attente, toute opération de bail sur le fichier de destination échoue avec status code 409 (Conflit). Un bail infini sur le fichier de destination est verrouillé de cette façon pendant l’opération de copie, que vous copiez dans un fichier de destination dont le nom est différent de la source ou que vous copiez dans un fichier de destination du même nom que la source. Si le client spécifie un ID de bail sur un fichier qui n’existe pas encore, Azure Files retourne status code 412 (Échec de la condition préalable).
Utilisation d’une opération de copie en attente
L’opération Copy File peut terminer la copie des fichiers de manière asynchrone. Utilisez le tableau suivant pour déterminer l’étape suivante en fonction du code status qui Copy File retourne :
| Code d’état | Signification |
|---|---|
| 202 (Acceptée), x-ms-copy-status: succès | L’opération de copie s’est terminée avec succès. |
| 202 (Acceptée), x-ms-copy-status: en attente | L’opération de copie n’est pas terminée. Interrogez l’objet blob de destination à l’aide Get File Properties de pour examiner x-ms-copy-status jusqu’à ce que l’opération de copie se termine ou échoue. |
| 4xx, 500 ou 503 | Échec de l’opération de copie. |
Pendant et après une Copy File opération, les propriétés du fichier de destination contiennent l’ID de copie de l’opération Copy File et l’URL de l’objet blob ou du fichier source. Une fois l’opération terminée, Azure Files écrit la valeur d’heure et de résultat (success, failedou aborted) dans les propriétés du fichier de destination. Si l’opération a un failed résultat, l’en-tête x-ms-copy-status-description contient une chaîne de détails d’erreur.
Une opération en attente Copy File a un délai d’attente de deux semaines. Une tentative de copie qui n’est pas terminée au bout de deux semaines expire et laisse un fichier vide avec le x-ms-copy-status champ défini sur failed et le x-ms-status-description champ défini sur 500 (OperationCancelled). Les erreurs intermittentes et non irrécupérables qui peuvent se produire pendant une opération de copie peuvent entraver la progression de l’opération, mais pas provoquer son échec. Dans ces cas, x-ms-copy-status-description décrit les erreurs intermittentes.
Toute tentative de modification du fichier de destination pendant l’opération de copie échoue avec status code 409 (Conflit), « Copier le fichier en cours ».
Si vous appelez une Abort Copy File opération, un en-tête s’affiche x-ms-copy-status:aborted . Le fichier de destination aura des métadonnées intactes et une longueur de fichier de 0 octet. Vous pouvez répéter l’appel d’origine à Copy File pour réessayer l’opération.
Facturation
Le compte de destination d’une Copy File opération est facturé pour une transaction pour démarrer l’opération. Le compte de destination entraîne également une transaction pour chaque demande d’annulation ou de demande de status de l’opération de copie.
Lorsque le fichier source ou l’objet blob se trouve dans un autre compte, le compte source entraîne des coûts de transaction. En outre, si les comptes source et de destination résident dans différentes régions (par exemple, USA Nord et USA Sud), la bande passante que vous utilisez pour transférer la demande est facturée au compte source en sortie. Les sorties entre les comptes au sein de la même région sont gratuits.