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 apportées aux données sources lors de l'importation 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 apportées à vos donné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 acceptée pour les importations de fichiers uniques, mais pas pour les objets importés par blocs, tels que les objets composites et les objets importés à l'aide d'une importation en plusieurs parties avec 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'ajoute 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 et une erreur BadRequestException: 400 est renvoyée.
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'importation d'objets, consultez Importation 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 (média) avec requête unique 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 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 limite. 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 limite 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 avec l'API JSON
Pour les importations avec reprise 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 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 avec 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'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 en une seule requête de l'API XML acceptent également l'en-tête Content-MD5 HTTP 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 CRC32C pour l'objet entier ou une somme de contrôle individuelle pour chaque partie importée. 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 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 de 2 Mio maximum, 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.
Copie et réécriture 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.
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 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 de création de 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 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 présente les clients Cloud Storage qui permettent de calculer les sommes de contrôle pour les écritures d'objets par défaut, y compris les versions de client compatibles avec les sommes de contrôle.
| Client | Versions compatibles avec les sommes de contrôle |
|---|---|
| Bibliothèque cliente C++ pour Cloud Storage | 2.46 et versions ultérieures |
| Bibliothèque cliente Go Cloud Storage | 1.60.0 et versions ultérieures |
| Bibliothèque cliente Java Cloud Storage | 2.62 et versions ultérieures |
| Bibliothèque cliente Node.js Cloud Storage | 7.19.0 et versions ultérieures |
| Bibliothèque cliente PHP Cloud Storage | 1.51.0 et versions ultérieures |
| Bibliothèque cliente Python Cloud Storage | 3.7.0 et versions ultérieures |
| Bibliothèque cliente Ruby Cloud Storage | 1.60.0 |
| Connecteur Cloud Storage |
|
| Cloud Storage FUSE | 3.8.0 et versions ultérieures |
| Google Cloud CLI |
Sommes de contrôle pour les lectures de données
Pour les téléchargements d'objets, le serveur envoie l'objet ainsi que sa somme de contrôle stockée dans la réponse. Le client calcule sa propre somme de contrôle du fichier 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.
Certaines bibliothèques clientes n'effectuent pas automatiquement la validation de la somme de contrôle sur les objets téléchargés. Votre application peut avoir besoin de calculer indépendamment la somme de contrôle du fichier téléchargé à 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.
Validation côté client pour les lectures
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 par décompression : 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 qui ne contient 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 à cette règle 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 d'un flux. Cela permet à votre client de vérifier instantanément que le bloc de données spécifique n'a pas été corrompu lors du 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 au lieu d'objets entiers à la fois, nous vous recommandons d'utiliser gRPC. Sinon, nous 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 différence 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 supprimer les données corrompues et utiliser la logique de répétition recommandée pour réessayer d'envoyer la requête.
Étapes suivantes
- Découvrez l'importation d'objets et le téléchargement d'objets dans Cloud Storage.
- Apprenez-en plus sur les stratégies de nouvelles tentatives de Cloud Storage.