Hachages et ETags : bonnes pratiques

Les utilisateurs Cloud Storage sont invités à valider les données qu'ils transfèrent vers/depuis leurs buckets à l'aide des sommes de contrôle CRC32C ou MD5. Cette section décrit les bonnes pratiques relatives à ces opérations de validation.

Utiliser des hachages pour le contrôle d'intégrité

Lorsque les données sont transférées depuis ou vers le cloud, elles peuvent être corrompues pour de multiples raisons :

  • Liens réseau bruyants
  • Erreurs de mémoire sur les ordinateurs clients ou serveurs, ou sur les routeurs le long du chemin
  • Bugs logiciels (p.ex., dans une bibliothèque utilisée par les clients)
  • Modifications apportées au fichier source alors qu'une importation est en cours sur une période prolongée.

Pour vous protéger contre la corruption des données, Cloud Storage accepte deux types de hachages : CRC32C et MD5. CRC32C est la méthode de validation recommandée. Les clients qui préfèrent MD5 peuvent utiliser ce hachage, mais les hachages MD5 ne sont pas compatibles avec les objets composites ou les objets créés à partir d'une importation en plusieurs parties avec l'API XML.

CRC32C

Tous les objets Cloud Storage ont un hachage de type CRC32C. Les bibliothèques permettant de calculer un hachage CRC32C incluent :

Le CRC32C encodé en base64 est classé par ordre d'octets en mode big-endian.

MD5

Cloud Storage accepte le hachage MD5 pour les objets qui répondent aux critères suivants :

Ce hachage ne s'applique qu'à un objet complet. Il ne peut donc pas être utilisé pour vérifier l'intégrité des téléchargements partiels en cas d'exécution d'une plage GET.

ETags

L'en-tête ETag d'un objet renvoie la valeur MD5 de l'objet si toutes les conditions suivantes sont remplies :

Dans tous les autres cas, les utilisateurs ne doivent faire aucune hypothèse concernant la valeur utilisée dans un ETag, sauf qu'elle change chaque fois que les données sous-jacentes sont modifiées, conformément à la spécification.

Le même objet peut avoir une valeur ETag différente lorsqu'elle est demandée par l'API XML plutôt que par l'API JSON.

Validation

Une vérification de l'intégrité du téléchargement peut être effectuée en hachant les données téléchargées à la volée et en comparant les résultats aux hachages fournis par le serveur. Vous devez supprimer les données téléchargées comportant des valeurs de hachage incorrectes et appliquer une logique de répétition des tentatives pour éviter des boucles à l'infini potentiellement coûteuses.

Cloud Storage procède à une validation côté serveur dans les cas suivants :

  • Lorsque vous effectuez une requête de copie ou de réécriture dans Cloud Storage.

  • Lorsque vous fournissez le hachage MD5 ou CRC32C attendu d'un objet dans une requête d'importation. Cloud Storage ne crée l'objet que si le hachage que vous fournissez correspond à la valeur calculée par Cloud Storage.

Les utilisateurs peuvent également choisir d'effectuer une validation côté client de leurs importations. Ils doivent alors envoyer une requête de métadonnées pour l'objet importé, comparer la valeur de hachage indiquée et supprimer l'objet en cas de non-concordance. Cette méthode est utile si le hachage MD5 ou CRC32C de l'objet n'est pas connu au début de l'importation. Pour éviter les conditions de concurrence où des processus indépendants suppriment ou remplacent les données les uns des autres, nous vous recommandons également d'utiliser les générations d'objet et conditions préalables.

Dans le cas d'importations composites parallèles, les utilisateurs doivent effectuer un contrôle d'intégrité pour chaque importation de composants, puis utiliser les conditions préalables de composant avec leurs requêtes de composition pour se protéger d'une condition de concurrence. La composition d'objets n'offrant aucune validation MD5 côté serveur, les utilisateurs qui souhaitent effectuer un contrôle d'intégrité de bout en bout doivent appliquer la validation côté client au nouvel objet composite.

À la fin de chaque opération de copie, les commandes gsutil cp et rsync confirment que la somme de contrôle du fichier local correspond à celle de l'objet stocké dans Cloud Storage. Si ce n'est pas le cas, gsutil supprime la copie non valide et affiche un message d'avertissement. Ceci arrive très rarement. Vous pouvez retenter l'opération si cela se produit.

API XML

Dans l'API XML, les hachages MD5 et CRC32C encodés en base64 sont exposés et acceptés via l'en-tête x-goog-hash. Auparavant, les MD5 étaient utilisés en tant qu'ETag d'objets, mais les utilisateurs doivent éviter cette situation car certains objets utilisent des valeurs ETag opaques qui n'offrent aucune garantie en dehors de leur changement à chaque modification de l'objet.

La validation de l'importation côté serveur peut être effectuée en fournissant des hachages calculés localement via l'en-tête de requête x-goog-hash. De plus, le MD5 peut être fourni en utilisant l'en-tête Content-MD5 HTTP standard (reportez-vous à la spécification).

API JSON

Dans l'API JSON, les propriétés md5Hash et crc32c des ressources d'objets contiennent respectivement des hachages MD5 et CRC32C encodés en base64. La provision de l'une ou l'autre des propriétés de métadonnées est facultative. Fournir l'une des deux propriétés dans le cadre d'une importation avec reprise ou d'une importation en plusieurs parties avec l'API JSON déclenche une validation côté serveur pour le nouvel objet. Si, pour l'une des propriétés, Cloud Storage calcule une valeur qui ne correspond pas à la valeur fournie, l'objet n'est pas créé. Si les propriétés ne sont pas fournies lors d'une importation, Cloud Storage calcule les valeurs et les écrit dans les métadonnées de l'objet.