Importations avec reprise

Configuration

Cette page traite des importations avec reprise dans Cloud Storage. Il s'agit de la méthode recommandée pour importer des fichiers volumineux. En effet, si une défaillance du réseau se produit en cours d'importation, vous n'aurez pas à reprendre celle-ci depuis le début.

Présentation

Une importation avec reprise vous permet de reprendre des opérations de transfert de données vers Cloud Storage après un échec de communication ayant interrompu le flux de données. Les importations avec reprise nécessitent l'envoi de plusieurs requêtes, chacune contenant une partie de l'objet que vous importez. Ceci est différent d'une importation par requête unique, qui rassemble toutes les données de l'objet dans une seule requête, et doit redémarrer depuis le début si le processus échoue.

  • Utilisez une importation avec reprise si vous importez des fichiers volumineux ou si vous importez des données sur une connexion à faible débit. Pour connaître les limites de taille des fichiers permettant d'utiliser des importations avec reprise, consultez la section Éléments à prendre en compte sur la taille d'importation.

  • L'importation avec reprise doit être terminée dans la semaine suivant son lancement, mais peut être annulée à tout moment.

  • Seule une importation avec reprise terminée apparaît dans votre bucket et, le cas échéant, remplace un objet existant portant le même nom.

Utilisation des importations avec reprise par les outils et les API

Selon votre manière d'interagir avec Cloud Storage, les importations avec reprise peuvent être gérées automatiquement en votre nom. Cette section décrit le comportement d'importation avec reprise pour différents outils et explique comment configurer la taille de la mémoire tampon appropriée pour votre application.

Console

La console Google Cloud gère automatiquement les importations avec reprise en votre nom. Cependant, si vous actualisez ou quittez la console Google Cloud alors qu'une importation est en cours, celle-ci est annulée.

Ligne de commande

gcloud CLI utilise les importations avec reprise dans les commandes gcloud storage cp et gcloud storage rsync lors de l'importation de données dans Cloud Storage. Si votre importation est interrompue, vous pouvez la reprendre en exécutant la même commande que celle utilisée pour la lancer. Lorsque vous reprenez une importation incluant plusieurs fichiers, utilisez l'option --no-clobber pour empêcher la réimportation de fichiers déjà transférés avec succès.

Bibliothèques clientes

Lors des importations réutilisables, les bibliothèques clientes fonctionnent comme des wrappers autour de l'API JSON Cloud Storage.

C++

Les fonctions dans storage::Client s'exécutent selon un comportement différent :

Par défaut, UploadFile() effectue une importation avec reprise lorsque l'objet dépasse 20 Mio. Sinon, la fonction effectue une importation simple ou en plusieurs parties. Vous pouvez configurer ce seuil en définissant MaximumSimpleUploadsSizeOption lors de la création d'un storage::Client.

La taille de la mémoire tampon par défaut est de 8 Mio, que vous pouvez modifier avec l'option UploadBufferSizeOption.

La bibliothèque cliente C++ utilise une taille de mémoire tampon égale à la taille des fragments. La taille de la mémoire tampon doit être un multiple de 256 Kio (256 x 1 024 octets). Lorsque vous utilisez WriteObject() et UploadFile(), nous vous recommandons d'appliquer des compromis entre vitesse d'importation et utilisation de la mémoire. L'utilisation de petits tampons pour importer des objets volumineux peut ralentir l'importation. Pour en savoir plus sur la relation entre la vitesse d'importation et la taille de la mémoire tampon pour C++, consultez l'analyse détaillée dans GitHub.

C#

Lors de l'importation, la bibliothèque cliente C# effectue toujours des importations avec reprise. Pour lancer une importation avec reprise, utilisez CreateObjectUploader.

La bibliothèque cliente C# utilise une taille de mémoire tampon égale à la taille des fragments. La taille de la mémoire tampon par défaut est de 10 Mo. Vous pouvez modifier cette valeur en définissant ChunkSize sur UploadObjectOptions. La taille de la mémoire tampon doit être un multiple de 256 Kio (256 x 1 024 octets). Les tailles de mémoire tampon plus importantes accélèrent généralement les importations, mais notez qu'un compromis est appliqué entre la vitesse et l'utilisation de mémoire.

Go

Par défaut, les importations avec reprise se produisent automatiquement lorsque la taille du fichier dépasse 16 Mio. Vous devez modifier la taille limite pour effectuer des importations avec reprise avec Writer.ChunkSize. Les importations avec reprise sont toujours fragmentées lors de l'utilisation de la bibliothèque cliente Go.

Les importations en plusieurs parties s'effectuent lorsque l'objet est inférieur à Writer.ChunkSize ou lorsque Writer.ChunkSize est défini sur 0, où la fragmentation est désactivée. Le Writer ne peut pas relancer les requêtes si la valeur de ChunkSize est définie sur 0.

La bibliothèque cliente Go utilise une taille de mémoire tampon égale à la taille des fragments. La taille de la mémoire tampon doit être un multiple de 256 Kio (256 x 1 024 octets). Les tailles de mémoire tampon plus importantes accélèrent généralement les importations, mais notez qu'un compromis est appliqué entre la vitesse et l'utilisation de mémoire. Si vous exécutez plusieurs importations avec reprise simultanément, vous devez définir Writer.ChunkSize sur une valeur inférieure à 16 Mio pour éviter toute surcharge de mémoire.

Notez que l'objet n'est pas finalisé dans Cloud Storage tant que vous n'avez pas appelé Writer.Close() et reçu une réponse positive. Writer.Close renvoie une erreur si la requête échoue.

Java

La bibliothèque cliente Java dispose de méthodes distinctes pour les importations en plusieurs parties et avec reprise. Les méthodes suivantes effectuent toujours une importation avec reprise :

La taille de la mémoire tampon par défaut est de 15 Mio. Vous pouvez définir la taille de la mémoire tampon à l'aide de la méthode WriteChannel#setChunkSize(int) ou en transmettant un paramètre bufferSize à la méthode Storage#createFrom. La taille de la mémoire tampon présente un seuil minimum strict de 256 Kio. Lorsque vous appelez WriteChannel#setChunkSize(int) en interne, la taille de la mémoire tampon passe à un multiple de 256 Kio.

La mise en mémoire tampon pour les importations avec reprise fonctionne comme un seuil de vidage minimal : les écritures inférieures à la taille de la mémoire tampon sont mises en mémoire tampon jusqu'à ce qu'une écriture fasse passer le nombre d'octets mis en mémoire tampon au-dessus de la taille de celle-ci.

Si vous importez de plus petites quantités de données, envisagez d'utiliser Storage#create(BlobInfo, byte[], Storage.BlobTargetOption...) ou Storage#create(BlobInfo, byte[], int, int, Storage.BlobTargetOption...).

Node.js

Les importations avec reprise s'effectuent automatiquement. Vous pouvez désactiver les importations avec reprise en définissant resumable sur UploadOptions sur false. Les importations avec reprise sont automatiquement gérées lorsque vous utilisez la méthode createWriteStream.

Il n'y a pas de taille de mémoire tampon par défaut, et les importations fragmentées doivent être appelées manuellement en définissant l'option chunkSize sur CreateResumableUploadOptions. Si chunkSize est spécifié, les données sont envoyées dans des requêtes HTTP distinctes, chacune avec une charge utile de taille chunkSize. Si aucun chunkSize n'est spécifié et que la bibliothèque effectue une importation avec reprise, toutes les données sont insérées par flux dans une seule requête HTTP.

La bibliothèque cliente Node.js utilise une taille de mémoire tampon égale à la taille des fragments. La taille de la mémoire tampon doit être un multiple de 256 Kio (256 x 1 024 octets). Les tailles de mémoire tampon plus importantes accélèrent généralement les importations, mais notez qu'un compromis est appliqué entre la vitesse et l'utilisation de mémoire.

PHP

Par défaut, les importations avec reprise s'effectuent automatiquement lorsque la taille du fichier dépasse 5 Mio. Sinon, les importations s'effectuent en plusieurs parties. Ce seuil ne peut pas être modifié. Vous pouvez forcer une importation avec reprise en définissant l'option resumable dans la fonction upload.

La bibliothèque cliente PHP utilise une taille de mémoire tampon égale à la taille des fragments. La taille de la mémoire tampon par défaut pour une importation avec reprise est de 256 Kio. Vous pouvez modifier la taille de la mémoire tampon en définissant la propriété chunkSize. La taille de la mémoire tampon doit être un multiple de 256 Kio (256 x 1 024 octets). Les tailles de mémoire tampon plus importantes accélèrent généralement les importations, mais notez qu'un compromis est appliqué entre la vitesse et l'utilisation de mémoire.

Python

Les importations avec reprise s'effectuent lorsque l'objet dépasse 8 Mio et les importations en plusieurs parties lorsque l'objet est inférieur à 8 Mio. Ce seuil ne peut pas être modifié. La bibliothèque cliente Python utilise une taille de mémoire tampon égale à la taille des fragments. La taille de la mémoire tampon par défaut utilisée pour une importation avec reprise est de 100 Mio. Vous pouvez modifier la taille de la mémoire tampon en définissant la propriété blob.chunk_size.

Pour toujours effectuer une importation avec reprise, quelle que soit la taille de l'objet, utilisez la classe storage.BlobWriter ou la méthode storage.Blob.open(mode='w'). Pour ces méthodes, la taille de la mémoire tampon par défaut est de 40 Mio. Vous pouvez également gérer les importations avec reprise à l'aide de Resumable Media.

La taille des fragments doit être un multiple de 256 Kio (256 x 1 024 octets). Les tailles de fragments plus importantes accélèrent généralement les importations, mais notez qu'un compromis est appliqué entre vitesse et utilisation de la mémoire.

Ruby

La bibliothèque cliente Ruby traite toutes les importations comme des importations avec reprise non fragmentées.

API REST

API JSON

L'API JSON Cloud Storage utilise une requête POST Object, qui inclut le paramètre de requête uploadType=resumable pour lancer l'importation avec reprise. Cette requête renvoie sous la forme d'URI de session que vous utilisez ensuite dans une ou plusieurs requêtes PUT Object pour importer les données d'objet. Pour suivre un guide par étapes sur la création de votre propre logique d'importation avec reprise, consultez la page Effectuer des importations avec reprise.

API XML

L'API XML Cloud Storage utilise une requête POST Object, qui inclut l'en-tête x-goog-resumable: start pour lancer l'importation avec reprise. Cette requête renvoie sous la forme d'URI de session que vous utilisez ensuite dans une ou plusieurs requêtes PUT Object pour importer les données d'objet. Pour suivre un guide par étapes sur la création de votre propre logique d'importation avec reprise, consultez la page Effectuer des importations avec reprise.

Importations avec reprise de taille inconnue

Le système d'importation avec reprise accepte les transferts de fichiers dont la taille n'est pas connue à l'avance. Par exemple, cela peut être utile pour compresser un objet à la volée pendant l'importation, car il est difficile de prédire la taille exacte du fichier compressé au début du transfert. Le système peut également s'avérer utile si vous souhaitez diffuser un transfert qui peut être réactivé après avoir été interrompu ou si l'encodage de transfert fragmenté ne fonctionne pas pour votre application.

Pour en savoir plus, consultez la section Importations en flux continu.

Performances des importations

Choisir les régions de session

Les importations avec reprise sont épinglées dans la région où vous les lancez. Par exemple, si vous lancez une importation avec reprise aux États-Unis et que vous transmettez l'URI de session à un client en Asie, l'importation transitera toujours par les États-Unis. Pour réduire le trafic interrégional et améliorer les performances, vous devez conserver une session d'importation avec reprise dans la région dans laquelle elle a été créée.

Si vous utilisez une instance Compute Engine pour lancer une importation avec reprise, l'instance doit se trouver au même emplacement que le bucket Cloud Storage vers lequel vous effectuez l'importation. Vous pouvez ensuite faire appel à un service de géolocalisation IP pour sélectionner la région Compute Engine vers laquelle vous redirigez les requêtes des clients, ce qui vous aidera à garder le trafic localisé dans une région géographique.

Importation par fragments

Si possible, évitez de fractionner un transfert en plusieurs fragments. Importez plutôt l'intégralité du contenu dans un seul fragment. En évitant la fragmentation, vous éliminez les coûts de latence et les frais d'opération supplémentaires liés à l'interrogation du décalage persistant de chaque fragment, ainsi que l'amélioration du débit. Cependant, vous devriez envisager d'importer les données par fragments dans les cas suivants :

  • Vos données source sont générées de façon dynamique et vous souhaitez limiter la quantité de données dont vous avez besoin pour mettre en mémoire tampon côté client en cas d'échec de l'importation.

  • Vos clients ont des limites de taille de requêtes, comme c'est le cas pour de nombreux navigateurs.

Si vous utilisez l'API JSON ou XML et que votre client reçoit une erreur, il peut interroger le serveur pour obtenir le décalage persistant et reprendre l'importation des octets restants à partir de ce décalage. La console Google Cloud, Google Cloud CLI et les bibliothèques clientes s'en chargent automatiquement en votre nom. Pour en savoir plus sur la fragmentation pour des bibliothèques clientes spécifiques, consultez la page Comment les outils et les API utilisent les importations avec reprise.

Remarques

Cette section est utile si vous créez votre propre client qui envoie des requêtes d'importation avec reprise directement à l'API JSON ou XML.

URI de session

Lorsque vous lancez une importation avec reprise, Cloud Storage renvoie un URI de session, que vous utilisez dans les requêtes suivantes pour importer les données réelles. Voici un exemple d'URI de session dans l'API JSON :

https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=resumable&name=my-file.jpg&upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

Voici un exemple d'URI de session dans l'API XML :

 https://storage.googleapis.com/my-bucket/my-file.jpg?upload_id=ABg5-UxlRQU75tqTINorGYDgM69mX06CzKO1NRFIMOiuTsu_mVsl3E-3uSVz65l65GYuyBuTPWWICWkinL1FWcbvvOA

Cet URI de session sert de jeton d'authentification. Par conséquent, les requêtes qui l'utilisent n'ont pas besoin d'être signées et peuvent être utilisées par n'importe quel utilisateur pour importer des données dans le bucket cible sans aucune autre authentification. De ce fait, soyez prudent lorsque vous partagez l'URI de session et ne le partagez que via HTTPS.

Un URI de session est valable une semaine. Il peut être annulé avant d'expirer. Si vous envoyez une requête à l'aide d'un URI de session qui n'est plus valide, vous recevez l'une des erreurs suivantes :

  • Un code d'état 410 Gone s'il y a moins d'une semaine que l'importation a été lancée.
  • Un code d'état 404 Not Found s'il y a plus d'une semaine que l'importation a été lancée.

Dans les deux cas, vous devez lancer une nouvelle importation avec reprise, obtenir un nouvel URI de session et reprendre l'importation depuis le début à l'aide du nouvel URI de session.

Vérifications de l'intégrité

Nous vous recommandons de demander une vérification de l'intégrité de l'objet final importé, afin de vous assurer qu'il correspond au fichier source. Pour ce faire, calculez le condensé MD5 du fichier source, puis ajoutez-le à l'en-tête de requête Content-MD5.

La vérification de l'intégrité du fichier importé est particulièrement importante si vous importez un fichier volumineux sur une longue période, car il est plus probable que le fichier source soit modifié au cours de l'importation.

Lors du lancement d'une importation avec reprise, la valeur x-goog-content-sha256 est ignorée. Par conséquent, il est recommandé de définir la valeur x-goog-content-sha256 sur UNSIGNED-PAYLOAD.

Nouvelles tentatives et renvoi des données

Une fois que Cloud Storage a conservé les octets lors d'une importation avec reprise, ceux-ci ne peuvent pas être écrasés. Cloud Storage ignore les tentatives d'écrasement. Par conséquent, vous ne devez pas envoyer de données différentes lors de la relance d'un décalage que vous avez envoyé précédemment.

Par exemple, supposons que vous importiez un objet de 100 000 octets, et que votre connexion soit interrompue. Lorsque vous vérifiez l'état, vous constatez que 50 000 octets ont bien été importés et conservés. Si vous essayez de redémarrer l'importation à 40 000 octets, Cloud Storage ignore les octets envoyés de 40 000 à 50 000. Cloud Storage commence à conserver les données que vous envoyez à l'octet 50 001.

Étape suivante