Pour valider l'intégrité des données et détecter les modifications, Cloud Storage vous encourage à utiliser des sommes de contrôle lors du transfert de données vers et depuis vos buckets. Cette page explique comment les sommes de contrôle sont utilisées dans Cloud Storage et comment les spécifier lors de l'envoi de requêtes.
Empêcher la corruption des données à l'aide de sommes de contrôle
Les données peuvent parfois être corrompues lors de leur transfert vers ou depuis le cloud en raison de bugs logiciels ou matériels, d'erreurs de mémoire ou de routeur, de perturbations électriques ou de modifications des données sources lors d'importations de fichiers sur une période prolongée.
Pour vous protéger contre la corruption des données, Cloud Storage accepte l'utilisation de sommes de contrôle CRC32C et MD5 pour vérifier l'intégrité de vos données et détecter les modifications qui y sont apportées.
CRC32C est la méthode de validation recommandée pour effectuer des vérifications d'intégrité. La validation à l'aide de hachages MD5 est compatible avec les importations de fichiers uniques, mais pas avec les objets importés en plusieurs fragments, tels que les objets composites et les objets importés à l'aide d'une importation en plusieurs parties de l'API XML.
Sommes de contrôle pour les écritures de données
Pour les écritures d'objets, le client calcule la somme de contrôle du fichier local et l'associe aux en-têtes HTTP de la requête d'importation d'objets. Le serveur reçoit la charge utile de données, calcule sa propre somme de contrôle et valide les données en comparant les deux sommes de contrôle une fois l'importation terminée.
Si les sommes de contrôle correspondent, l'objet est stocké dans Cloud Storage avec ses sommes de contrôle. Si les sommes de contrôle ne correspondent pas, la requête d'écriture est rejetée avec une erreur BadRequestException: 400.
Validation côté serveur pour les écritures de données
Cloud Storage procède à une validation côté serveur dans les cas suivants :
Lorsque vous fournissez le hachage MD5 ou CRC32C d'un objet dans une requête d'importation d'objet. Pour en savoir plus sur les types d'importations d'objets, consultez Importations d'objets.
Lorsque vous effectuez une requête de copie ou de réécriture dans Cloud Storage. Pour les requêtes de copie et de réécriture d'objets, Cloud Storage effectue automatiquement une validation côté serveur basée sur une somme de contrôle non modifiable stockée avec l'objet source.
Importations de requêtes uniques (média) avec l'API JSON
Pour les importations de contenus multimédias avec l'API JSON, vous pouvez spécifier des sommes de contrôle dans l'en-tête X-Goog-Hash de la requête. Exemple :
curl -X POST --data-binary @Desktop/dog-pic.jpeg \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: image/jpeg" \
-H "X-Goog-Hash: crc32c=n03x6A==" \
"https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=media&name=dog-pic.jpeg"Importations en plusieurs parties avec l'API JSON
Pour les importations en plusieurs parties avec l'API JSON, vous pouvez spécifier des sommes de contrôle dans le conteneur de requête, soit dans la section des métadonnées d'objet, soit sous une troisième chaîne de délimitation. Pour en savoir plus sur la structure JSON et les clés valides d'un objet, consultez la représentation de la ressource d'objets.
L'exemple suivant spécifie une somme de contrôle CRC32C dans la partie des métadonnées d'objet d'un conteneur de requête :
--separator_string
Content-Type: application/json; charset=UTF-8
{
"name":"my-document.txt",
"crc32c": "n03x6A=="
}
--separator_string
Content-Type: text/plain
This is a text file.
--separator_string--
L'exemple suivant spécifie une somme de contrôle CRC32C dans la troisième chaîne de délimitation d'un conteneur de requête :
--separator_string
Content-Type: application/json; charset=UTF-8
{
"name":"my-document.txt"
}
--separator_string
Content-Type: text/plain
This is a text file.
--separator_string
Content-Type: application/json; charset=UTF-8
{ "crc32c": "n03x6A==" }
--separator_string--
Importations avec reprise de l'API JSON
Pour les importations avec reprise via l'API JSON, vous pouvez spécifier des sommes de contrôle dans l'en-tête X-Goog-Hash de la requête finale qui termine l'importation. Exemple :
curl -i -X PUT --data-binary @Desktop/dog-pic.jpeg \
-H "Content-Length: 2000000" \
-H "X-Goog-Hash: crc32c=n03x6A==" \
"SESSION_URI"La somme de contrôle spécifiée dans la requête finale est calculée à partir de l'objet entier, et pas seulement des données d'objet de la requête finale.
Importations en une seule requête avec l'API XML
Pour les importations à requête unique de l'API XML, vous pouvez spécifier des sommes de contrôle dans l'en-tête x-goog-hash de la requête.
Exemple :
curl -X PUT --data-binary @Desktop/dog-pic.jpeg \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: image/jpeg" \
-H "x-goog-hash: crc32c=n03x6A==" \
"https://storage.googleapis.com/my-bucket/dog-pic.jpeg"Les importations à requête unique de l'API XML acceptent également l'en-tête HTTP Content-MD5 standard. Pour en savoir plus, consultez la spécification Content-MD5.
Importations en plusieurs parties avec l'API XML
Pour les importations en plusieurs parties de l'API XML, vous pouvez spécifier une somme de contrôle pour chaque partie d'importation. Pour spécifier une somme de contrôle individuelle pour une partie d'importation, incluez l'en-tête x-goog-hash dans la requête pour cette partie spécifique.
Exemple :
PUT /dog-pic.jpeg?partNumber=1&uploadId=ABgVH8 HTTP/1.1 Host: my-bucket.storage.googleapis.com Content-Length: 1000000 x-goog-hash: crc32c=n03x6A==
Seules les sommes de contrôle CRC32C peuvent être utilisées pour vérifier l'intégrité des importations en plusieurs parties de l'API XML. Les sommes de contrôle MD5 ne sont pas acceptées.
Importations gRPC
Lorsque vous importez des objets à l'aide de gRPC, vous pouvez spécifier des sommes de contrôle au niveau de l'objet dans le premier ou le dernier message WriteObject de toute requête d'importation, qu'il s'agisse d'une importation unique ou d'une importation avec reprise.
De plus, gRPC est compatible avec les sommes de contrôle par message. Chaque message WriteObject contient des fragments de données d'une taille maximale de 2 Mio, et chaque fragment peut inclure sa propre somme de contrôle. Vous pouvez spécifier des sommes de contrôle par message à la place ou en plus d'une somme de contrôle au niveau de l'objet.
Importations composites parallèles
Dans le cas d'importations composites parallèles, vous devez effectuer un contrôle d'intégrité pour chaque importation de composants, puis utiliser les conditions préalables avec la requête de composition d'importation pour vous protéger d'une condition de concurrence. Les requêtes de composition ne sont pas validées côté serveur. Vous devez donc effectuer une validation côté client sur le nouvel objet composite si vous souhaitez un contrôle d'intégrité de bout en bout.
Copies et réécritures de Google Cloud CLI
Dans la gcloud CLI, les données copiées vers ou depuis un bucket Cloud Storage sont automatiquement validées. Pour les commandes cp, mv et rsync, la gcloud CLI utilise des sommes de contrôle MD5 ou CRC32C pour déterminer s'il existe une différence entre la version d'un objet trouvée à la source et celle trouvée à l'emplacement de destination. Si la somme de contrôle des données sources ne correspond pas à celle des données de destination, la gcloud CLI 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.
Cette validation automatique a lieu une fois l'objet finalisé. Les objets non valides sont donc visibles pendant 1 à 3 secondes avant d'être identifiés et supprimés. De plus, la gcloud CLI peut être interrompue après la fin de l'importation, mais avant qu'il effectue la validation, laissant l'objet non valide en place. Ces problèmes peuvent être évités lors de l'importation de fichiers uniques dans Cloud Storage à l'aide de la validation côté serveur, qui se produit lorsque vous utilisez l'option --content-md5 pour spécifier un hachage MD5.
La Google Cloud CLI ignore l'option --content-md5 pour les objets qui n'ont pas de hachage MD5.
Détection des modifications pour rsync
La commande gcloud storage rsync compare les sommes de contrôle dans les scénarios suivants pour déterminer s'il faut ignorer un transfert :
La source et la destination sont toutes deux des buckets Cloud Storage, et l'objet possède une somme de contrôle MD5 ou CRC32C dans les deux buckets.
L'objet n'a pas d'heure de modification de fichier (
mtime) dans la source ou la destination.
Si un objet a une valeur mtime à la fois dans la source et dans la destination, par exemple lorsque la source et la destination sont des systèmes de fichiers, la commande rsync compare la taille des objets et la valeur mtime, au lieu d'utiliser des sommes de contrôle. De même, si la source est un bucket et que la destination est un système de fichiers local, la commande rsync utilise l'heure créée pour l'objet source pour remplacer mtime, et la commande n'utilise pas de sommes de contrôle.
Si ni mtime ni les sommes de contrôle ne sont disponibles, rsync ne compare que les tailles de fichiers pour déterminer s'il existe une différence entre la version source d'un objet et la version de destination. Par exemple, ni mtime, ni les sommes de contrôle ne sont disponibles lorsque vous comparez des objets composites avec des objets chez un fournisseur cloud qui n'est pas compatible avec le hachage CRC32C, car les objets composites ne possèdent pas de sommes de contrôle MD5.
Validation côté client pour les écritures de données
Vous pouvez effectuer une validation côté client de vos importations en envoyant une requête de métadonnées pour l'objet importé, en comparant la valeur de hachage de l'objet importé à la valeur attendue et en supprimant 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.
Le tableau suivant indique la version minimale de chaque client Cloud Storage compatible avec les sommes de contrôle d'écriture d'objets.
| Client | Version compatible avec les sommes de contrôle d'écriture d'objets |
|---|---|
| Bibliothèque cliente Cloud Storage pour C++ | 2.46 et versions ultérieures |
| Bibliothèque cliente Cloud Storage pour Go | 1.60.0 et versions ultérieures |
| Bibliothèque cliente Cloud Storage pour Java | 2.62 et versions ultérieures |
| Bibliothèque cliente Cloud Storage pour Node.js | 7.19.0 et versions ultérieures |
| Bibliothèque cliente PHP Cloud Storage | 1.51.0 et versions ultérieures |
| Bibliothèque cliente Cloud Storage pour Python | 3.7.0 et versions ultérieures |
| Bibliothèque cliente Cloud Storage pour Ruby | 1.60.0 |
| Bibliothèque cliente Cloud Storage pour .NET | 2.3.0 et versions ultérieures. Nous vous recommandons d'utiliser la version 4.15.0, qui fournit une validation de la somme de contrôle côté serveur. |
| connecteur Cloud Storage |
|
| Cloud Storage FUSE | 3.8.0 et versions ultérieures |
| Google Cloud CLI |
Sommes de contrôle pour les lectures et les téléchargements de données
Pour les lectures et les téléchargements d'objets, le serveur envoie l'objet avec sa somme de contrôle stockée dans la réponse. Le client calcule sa propre somme de contrôle du fichier lu ou téléchargé en fonction des octets qu'il a reçus, puis compare les deux sommes de contrôle pour vérifier l'intégrité des données.
Validation côté client pour les lectures et les téléchargements
Par défaut, tous les SDK des bibliothèques clientes Cloud Storage sont compatibles avec le calcul des sommes de contrôle pour les téléchargements et les lectures d'objets. Le tableau suivant contient des informations sur la désactivation du téléchargement d'objets ou de la lecture des sommes de contrôle pour chaque SDK de bibliothèque cliente.
| Bibliothèque cliente | Instructions pour désactiver les sommes de contrôle de lecture ou de téléchargement d'objets |
|---|---|
| Bibliothèque cliente Cloud Storage pour C++ | Dans la bibliothèque cliente C++, vous désactivez la validation de la somme de contrôle en définissant DownloadChecksumValidationOption sur la valeur ChecksumAlgorithm::kNone. |
| Bibliothèque cliente Cloud Storage pour Go | Dans la bibliothèque cliente Go, vous désactivez la validation de la somme de contrôle en fournissant des options de lecteur lors de l'initialisation. Transmettez WithDisableReaderChecksum() lorsque vous appelez NewReader ou transmettez WithDisableMRDReadChecksum() lorsque vous appelez NewMultiRangeDownloader. |
| Bibliothèque cliente Cloud Storage pour Java | Pour désactiver la validation interne de la somme de contrôle CRC32C sur les chemins de lecture dans la bibliothèque cliente Java, transmettez la propriété système JVM -Dcom.google.cloud.storage.Hasher.read=disabled, qui désactive le hachage interne pour les lectures. Si vous souhaitez désactiver la somme de contrôle de manière globale pour les lectures et les écritures, utilisez plutôt -Dcom.google.cloud.storage.Hasher.default=disabled.
|
| Bibliothèque cliente Cloud Storage pour Node.js | Dans la bibliothèque cliente Node.js, vous désactivez la validation de la somme de contrôle en transmettant { validation: false } dans l'objet d'option de configuration fourni aux appels de méthode de téléchargement. |
| Bibliothèque cliente PHP Cloud Storage | Dans la bibliothèque cliente PHP, vous désactivez la validation de la somme de contrôle sur les chemins de lecture des API JSON et API XML en transmettant 'validate' => false ou 'validate' => 'none' dans le tableau d'options associatives ($options['validate']) lors de l'appel des méthodes de téléchargement. |
| Bibliothèque cliente Cloud Storage pour Python | Dans la bibliothèque cliente Python, la désactivation de la validation de la somme de contrôle dépend du transport client : pour le client JSON, transmettez checksum=None (compatible avec des méthodes telles que download_to_file), tandis que pour le client gRPC, définissez enable_checksum=False. |
| Bibliothèque cliente Cloud Storage pour Ruby | Dans la bibliothèque cliente Ruby, vous désactivez la validation de la somme de contrôle en transmettant des arguments de mot clé (checksum: ou verify:) directement aux méthodes de téléchargement, en définissant spécifiquement verify: none ou verify: false. |
| Bibliothèque cliente Cloud Storage pour .NET | Dans la bibliothèque cliente .NET, vous désactivez la validation de la somme de contrôle en définissant la propriété ChecksumValidation sur DownloadValidationMode.Never sur l'objet DownloadObjectOptions transmis aux appels de méthode de téléchargement. |
Effectuer des vérifications de l'intégrité des données sur les objets téléchargés ou lus
Dans certains cas, votre application peut avoir besoin de calculer indépendamment la somme de contrôle du fichier téléchargé ou lu à l'aide des octets reçus, et de la comparer au hachage fourni par le serveur pour vérifier l'intégrité des données.
Pour effectuer une vérification de l'intégrité des données téléchargées, calculez la somme de contrôle à la réception des données et comparez vos résultats à la somme de contrôle fournie par le serveur.
Les sommes de contrôle côté serveur sont basées sur l'objet complet tel qu'il est stocké dans Cloud Storage. Cela signifie que les types de téléchargements suivants ne peuvent pas être validés par rapport aux sommes de contrôle fournies par le serveur :
Téléchargements soumis à un transcodage décompressif : la somme de contrôle fournie par le serveur représente l'objet dans son état compressé, tandis que les données diffusées voient leur compression supprimée et, par conséquent, ont une valeur de somme de contrôle différente.
Une réponse ne contenant qu'une partie des données de l'objet : ce type de réponse se produit pour les requêtes
Range.Les lectures par plage gRPC constituent une exception à ce point et sont compatibles avec la validation de bout en bout. Dans les lectures par plage gRPC, Cloud Storage valide les données en incluant une somme de contrôle CRC32C unique dans chaque fragment de réponse d'un flux, ce qui permet à votre client de vérifier instantanément que le bloc de données spécifique n'a pas été corrompu pendant le transfert. Pour une validation plus large, le flux fournit également la somme de contrôle complète de l'objet entier, que les clients avancés peuvent utiliser pour calculer un total cumulé et vérifier l'intégrité du fichier plus volumineux.
Si votre application doit lire des plages d'objets plutôt que des objets complets à la fois, nous vous recommandons d'utiliser gRPC. Sinon, nous vous recommandons de n'utiliser les requêtes de plage qu'à l'occasion d'un redémarrage du téléchargement d'un objet complet après le dernier décalage reçu, car vous pourrez alors calculer et valider la somme de contrôle à la fin du téléchargement complet.
Lors de la validation de votre téléchargement, une non-concordance entre la somme de contrôle calculée et celle fournie par le serveur indique que les données ont été corrompues pendant le transfert. Dans ce cas, vous devez supprimer les données corrompues et utiliser la logique de nouvelle tentative recommandée pour relancer la requête.
Étapes suivantes
- Découvrez comment importer et télécharger des objets dans Cloud Storage.
- Apprenez-en plus sur les stratégies de nouvelles tentatives de Cloud Storage.