Pour valider l'intégrité des données et détecter les modifications, Cloud Storage vous encourage à utiliser des sommes de contrôle lorsque vous transférez des 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.
Éviter 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 de longue durée.
Pour vous aider à vous protéger contre la corruption des données, Cloud Storage est compatible avec l'utilisation des sommes de contrôle CRC32C et MD5 pour vérifier l'intégrité de vos données et détecter les modifications.
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 par blocs, 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'objet. 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 refusé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 en une seule requête (média) de l'API JSON
Pour les importations de fichiers multimédias de 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 de l'API JSON
Pour les importations en plusieurs parties de 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 de l'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 Objects.
L'exemple suivant spécifie une somme de contrôle CRC32C dans la partie des métadonnées de l'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 de 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 de l'objet dans la requête finale.
Importations en une seule requête de l'API XML
Pour les importations en une seule requête de l'API XML, vous pouvez spécifier des sommes de contrôle dans l'
x-goog-hash en-tête 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 en une seule requête de l'API XML acceptent également l'en-tête HTTP standard Content-MD5. Pour en savoir plus, consultez la spécification Content-MD5.
Importations en plusieurs parties de 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 individuelle. Pour spécifier une somme de contrôle individuelle pour une partie d'importation, incluez l'
x-goog-hash en-tête 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 WriteObject message de toute requête d'importation, qu'il s'agisse d'une
importation en une seule fois ou d'une importation avec reprise.
De plus, gRPC est compatible avec les sommes de contrôle par message. Chaque message WriteObject contient des blocs de données d'une taille maximale de 2 Mio, et chaque bloc 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 effectuer 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 sans 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 comporte une somme de contrôle MD5 ou CRC32C dans les deux buckets.
L'objet ne comporte pas d'heure de modification de fichier (
mtime) dans la source ni dans 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 fichier 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 de services 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 contient 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 Cloud Storage pour PHP | 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 des sommes 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 reçus et 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 de bibliothèque cliente 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 des sommes de contrôle de lecture ou de téléchargement d'objets 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 vérification des sommes 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 vérification des sommes 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 des sommes 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 le hachage
globalement pour les lectures et les écritures, utilisez
-Dcom.google.cloud.storage.Hasher.default=disabled plutôt.
|
| Bibliothèque cliente Cloud Storage pour Node.js | Dans la bibliothèque cliente Node.js, vous désactivez la validation des sommes 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 Cloud Storage pour PHP | Dans la bibliothèque cliente PHP, vous désactivez la validation des sommes 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 associatif
($options['validate']) lorsque vous appelez 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 vérification des sommes de contrôle dépend
du transport du 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 vérification des sommes 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 vérification des sommes de contrôle en
définissant la ChecksumValidation propriété sur
DownloadValidationMode.Never dans l'
DownloadObjectOptions objet transmis aux appels de méthode
de téléchargement. |
Effectuer des contrôles d'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 un contrôle d'intégrité des données téléchargées, calculez la somme de contrôle à mesure que les données sont reçues 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.
Réponse qui ne contient qu'une partie des données de l'objet : ce type de réponse se produit pour les
Rangerequêtes.Les lectures par plage gRPC constituent une exception à cette puce 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 bloc de réponse individuel 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 en transit. 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 au lieu d'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 que vous avez calculée et celle fournie par le serveur indique que les données ont été corrompues en transit. Dans ce cas, vous devez ignorer les données corrompues et utiliser la logique de nouvelle tentative recommandée pour retenter la requête.
Étape suivante
- Découvrez les importations et les téléchargements d'objets dans Cloud Storage.
- Apprenez-en plus sur les stratégies de nouvelles tentatives de Cloud Storage.