Copie incrémentielle BLOB

  • Article

L’opération Incremental Copy Blob copie un instantané de l’objet blob de page source vers un objet blob de page de destination. Seules les différences par rapport aux instantané précédemment copiées sont transférées vers la destination. Les instantanés copiés sont des copies complètes de l’instantané d’origine et vous pouvez les lire ou les copier comme d’habitude. Cette API est prise en charge depuis rest version 2016-05-31.

Requête

Vous pouvez construire la Incremental Copy Blob requête comme suit. HTTPS est recommandé. Remplacez myaccount par le nom de votre compte de stockage, mycontainer par le nom de votre conteneur et myblob par le nom de votre objet blob de destination. Le comp paramètre de requête, avec la valeur , incrementalcopyindique que cette demande consiste à créer une instantané incrémentielle.

URI de demande de méthode PUT Version HTTP
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=incrementalcopy HTTP/1.1

URI de service de stockage émulé

Lorsque vous effectuez une demande auprès du service de stockage émulé, spécifiez le nom d’hôte de l’émulateur et Stockage Blob Azure port de service 127.0.0.1 :10000, suivi du nom du compte de stockage émulé. Indiquez également que cette demande concerne la copie incrémentielle, en définissant le comp paramètre de requête sur incrementalcopy.

URI de demande de méthode PUT Version HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=incrementalcopy HTTP/1.1

Pour plus d’informations, consultez Utiliser l’émulateur Azurite pour le développement local de Stockage Azure.

Paramètres URI

Vous pouvez spécifier les paramètres supplémentaires suivants sur l’URI de requête.

Paramètre Description
timeout facultatif. Le paramètre timeout est exprimé en secondes. Pour plus d’informations, consultez Définition de délais d’expiration pour les opérations de stockage Blob.

En-têtes de requête

Le tableau suivant décrit les en-têtes de demande obligatoires ou 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 et facultatif pour les requêtes anonymes. Spécifie la version de l'opération à utiliser pour cette demande. Pour plus d'informations, consultez la page Contrôle de version pour les services de Stockage Microsoft Azure.
If-Modified-Since facultatif. Valeur DateTime. Spécifiez cet en-tête conditionnel pour copier l'objet blob uniquement si l'objet blob de destination a été modifié depuis la date/l'heure indiquées. Si l’objet blob de destination n’a pas été modifié, Stockage Blob retourne status code 412 (Échec de la condition préalable).
If-Unmodified-Since facultatif. Valeur DateTime. Spécifiez cet en-tête conditionnel pour copier l’objet blob uniquement si l’objet blob de destination n’a pas été modifié depuis la date/heure spécifiée. Si l’objet blob de destination a été modifié, Stockage Blob retourne status code 412 (Échec de la condition préalable).
If-Match facultatif. Valeur ETag. Spécifiez une ETag valeur pour cet en-tête conditionnel pour copier l’objet blob, uniquement si la valeur spécifiée ETag correspond à la ETag valeur d’un objet blob de destination existant. Si le ETag pour l’objet blob de destination ne correspond pas au ETag spécifié pour If-Match, Stockage Blob retourne status code 412 (Échec de la condition préalable).
If-None-Match facultatif. Valeur ETag ou caractère générique (*).

Spécifiez une ETag valeur pour cet en-tête conditionnel pour copier l’objet blob, uniquement si la valeur spécifiée ETag ne correspond pas à la ETag valeur de l’objet blob de destination.

Spécifiez le caractère générique (*) pour effectuer l’opération, uniquement si l’objet blob de destination n’existe pas.

Si la condition spécifiée n’est pas remplie, Stockage Blob retourne status code 412 (Échec de la condition préalable).
x-ms-copy-source:name Obligatoire. Spécifie le nom de l’objet blob de page source instantané.

Cette valeur est une URL d’une longueur maximale de 2 kibioctets (Kio) qui spécifie un objet blob de page instantané. La valeur doit être encodée sous forme d'URL, comme dans une URI de demande. L’URI d’objet blob source peut être autorisé de l’une des deux manières suivantes :

L’URI d’objet blob source peut référencer un instantané d’objet blob de page, mais il doit inclure un jeton de signature d’accès partagé (SAP) qui a été créé sur l’objet blob de base du instantané. Le champ de ressource signée (sr) de la sap doit être défini sur b. Par exemple : https://<account-name>.blob.core.windows.net/<container-name>/<page-blob-name>?snapshot=2022-07-23T00:14:45.3964054Z&sp=r&st=2022-07-23T00:15:38Z&se=2022-07-23T08:15:38Z&spr=https&sv=2021-06-08&sr=b&sig=<signature>.

L’URI d’objet blob source peut référencer un objet blob de page publique instantané ; par exemple, https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>.
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.

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.

Syntaxe Description
ETag Contient une valeur que vous pouvez utiliser pour effectuer des opérations conditionnelles. La valeur est entre guillemets.
Last-Modified Date et heure de la dernière modification apportée à l’objet blob. Pour plus d’informations, consultez Représentation des valeurs de date/heure dans les en-têtes.

Toute opération d’écriture sur l’objet blob (y compris les mises à jour sur les métadonnées ou propriétés de l’objet blob) modifie l’heure de la dernière modification de l’objet blob.
x-ms-request-id Identifie de manière unique la demande qui a été effectuée et peut être utilisée pour la résolution des problèmes de la demande. Pour plus d’informations, consultez Résolution des problèmes liés aux opérations d’API.
x-ms-version Indique la version du stockage Blob utilisée pour exécuter la demande.
Date Valeur de date/heure UTC qui indique l’heure à laquelle la réponse a été lancée. Le service génère cette valeur.
x-ms-copy-id: <id> Identificateur de chaîne pour cette opération de copie. Utilisez avec Get Blob Properties pour case activée la status de cette opération de copie, ou passez à Abort Copy Blob pour arrêter une copie en attente.
x-ms-copy-status: pending État de l’opération de copie. Cela est toujours en attente pour indiquer que la copie a démarré et est en cours.
x-ms-client-request-id Peut être utilisé pour résoudre les problèmes liés aux demandes et aux 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. 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, il ne sera pas présent dans la réponse.

Response body

Aucun.

Exemple de réponse

Voici un exemple de réponse pour une demande d’exécution d’une copie incrémentielle :

Response Status:
HTTP/1.1 202 Accepted

Response Headers: 
Last-Modified: <date> 
ETag: "0x8CEB669D794AFE2"
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402
x-ms-version: 2016-05-31
x-ms-copy-id: 1f812371-a41d-49e6-b123-f4b542e851c5
x-ms-copy-status: pending
Date: <date>

Autorisation

Une autorisation est requise lors de l’appel d’une opération d’accès aux données dans stockage Azure. La section suivante décrit comment l’objet de destination pour l’opération Incremental Copy Blob peut être autorisé. L’accès à l’objet blob ou au fichier source est autorisé séparément, comme décrit dans les détails de l’en-tête de x-ms-copy-source demande.

Le Stockage Azure prend en charge l’utilisation de Microsoft Entra ID pour autoriser les demandes de données blob. Avec Microsoft Entra ID, vous pouvez utiliser le contrôle d’accès en fonction du rôle Azure (Azure RBAC) pour accorder des autorisations à un principal de sécurité. Le principal de sécurité peut être un utilisateur, un groupe, un principal de service d’application ou une identité managée Azure. Le principal de sécurité est authentifié par Microsoft Entra ID pour retourner un jeton OAuth 2.0. Le jeton peut ensuite être utilisé pour autoriser une requête auprès du service BLOB.

Pour en savoir plus sur l’autorisation à l’aide de Microsoft Entra ID, consultez Autoriser l’accès aux objets blob à l’aide de Microsoft Entra ID.

Autorisations

Vous trouverez ci-dessous l’action RBAC nécessaire pour qu’un utilisateur, un groupe ou un principal de service Microsoft Entra appelle l’opérationIncremental Copy Blob, ainsi que le rôle RBAC intégré Azure le moins privilégié qui inclut cette action :

Pour en savoir plus sur l’attribution de rôles à l’aide d’Azure RBAC, consultez Attribuer un rôle Azure pour accéder aux données blob.

Remarques

La destination d’une copie incrémentielle ne doit pas exister ou doit avoir été créée avec une copie incrémentielle précédente à partir du même objet blob source. Une fois que vous l’avez créé, l’objet blob de destination est associé de manière permanente à la source et ne peut être utilisé que pour les copies incrémentielles. Les Get Blob Properties API et List Blobs indiquent si l’objet blob est un objet blob de copie incrémentielle créé de cette façon.

Vous ne pouvez pas télécharger directement des objets blob de copie incrémentielle. Les seules opérations prises en charge sont Get Blob Properties, Incremental Copy Blobet Delete Blob. Vous pouvez lire et supprimer les instantanés copiés comme d’habitude.

Vous effectuez une copie incrémentielle de façon asynchrone sur le service, et vous devez interroger la complétion. Reportez-vous à l’API Copy Blob pour plus d’informations sur la façon d’interroger une copie en attente. Une fois la copie terminée, l’objet blob de destination contient une nouvelle instantané. L’API Get Blob Properties retourne l’heure instantané du instantané nouvellement créé.

La première fois que vous effectuez une copie incrémentielle sur un objet blob de destination, un nouvel objet blob est créé, avec un instantané entièrement copié à partir de la source. Chaque appel suivant à Incremental Copy Blob crée un instantané, en copiant uniquement les modifications différentielles de la instantané précédemment copiée.

Les modifications différentielles sont calculées sur le serveur en émettant un Get Page Ranges appel sur le instantané d’objet blob source. Définissez prevsnapshot sur le instantané copié le plus récemment. Par conséquent, les mêmes restrictions s’appliquent Get Page Ranges à Incremental Copy Blob. Plus précisément, vous devez copier les instantanés dans l’ordre croissant et, si l’objet blob source est recréé à l’aide Put Blob de ou Copy Blob, les Incremental Copy Blob nouveaux instantanés échouent.

L’espace de stockage supplémentaire consommé par le instantané copié est la taille des données différentielles transférées pendant la copie. Vous pouvez déterminer cette taille en effectuant un appel d’API différentiel sur Get Page Ranges le instantané, pour la comparer à la instantané précédente.

Voir aussi

Autoriser les demandes à Stockage Azure
Codes d’état et d’erreur
Définition de délais d’expiration pour les opérations de stockage Blob