Importations avec reprise

Accéder aux exemples

Cette page présente les importations avec reprise de Cloud Storage dans les API JSON et XML. Étant donné qu'il n'est pas nécessaire de redémarrer les importations de fichiers volumineux depuis le début, vous pouvez réduire l'utilisation de la bande passante en cas de panne réseau. Une importation avec reprise terminée est considérée comme une opération de classe A.

Présentation

Cloud Storage intègre une fonctionnalité de transfert de données avec reprise qui vous permet de reprendre les opérations d'importation après un échec de communication ayant interrompu le flux de données. Les importations avec reprise sont utiles si vous transférez des fichiers volumineux, car les risques d'interruption du réseau ou d'échec de transmission sont élevés. La fonctionnalité d'importation avec reprise vous permet de réduire l'utilisation de la bande passante, et donc son coût, car il n'est pas nécessaire de redémarrer les importations de fichiers volumineux depuis le début. Pour obtenir des conseils sur l'importation dans Cloud Storage, consultez les bonnes pratiques.

Les API JSON et XML de Cloud Storage fournissent deux méthodes HTTP standards pour importer des données : l'objet POST et l'objet PUT. Pour effectuer une importation avec reprise, vous devez utiliser ces deux méthodes avec différents en-têtes et paramètres de chaîne de requête.

Si vous envoyez de petits fichiers via une connexion réseau fiable, vous pouvez effectuer une importation simple.

URI de requête

Lorsque vous importez des objets avec l'API JSON, vous utilisez un URI spécial qui diffère de l'URI que vous utilisez pour la plupart des requêtes d'API JSON, telles que les requêtes d'importation de métadonnées d'objet :

  • Pour les importations d'objets, utilisez l'URI /upload. Le format du point de terminaison /upload correspond à l'URI de ressource standard avec un préfixe /upload. Utilisez cet URI lors du transfert des données d'objet.

    Par exemple, pour un bucket nommé myBucket, procédez comme suit :

    POST /upload/storage/v1/b/myBucket/o
  • Pour les autres requêtes, utilisez l'URI de ressource standard. Il inclut l'ajout ou la mise à jour des valeurs de métadonnées d'un objet existant.

    Par exemple, pour ajouter un correctif de métadonnées à un objet nommé myObject dans le bucket myBucket, procédez comme suit :

    PATCH /storage/v1/b/myBucket/o/myObject

En-tête Content-Type en XML

Vous pouvez ajouter un en-tête de requête Content-Type si vous souhaitez spécifier le type de contenu du fichier que vous importez. Si vous ne spécifiez pas de type de contenu, le système Cloud Storage définit le type de contenu sur application/octet-stream lorsqu'il diffuse l'objet que vous importez.

L'en-tête x-goog-resumable est un en-tête d'extension personnalisé de Cloud Storage. L'en-tête informe le système Cloud Storage que vous souhaitez lancer une importation avec reprise. Il ne peut être utilisé qu'avec une requête d'objet POST pour les importations avec reprise.

De plus, vous devez utiliser le nom d'hôte Cloud Storage standard dans la requête et authentifier la requête d'objet POST comme vous le feriez pour toute requête authentifiée. Pour en savoir plus, consultez les pages Points de terminaison de requêtes et Authentification Cloud Storage.

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.

Pratiques recommandées

  • Un URI de session est valable une semaine. Nous vous recommandons de démarrer une importation avec reprise dès que vous obtenez l'URI d'importation et de reprendre votre importation peu après son interruption.

  • Si vous envoyez une requête avec un URI de session arrivé à expiration, vous recevez un code d'état 400 Bad Request. Dans ce 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 de ce nouvel URI.

  • Lorsque vous lancez une session d'importation avec reprise, vous recevez un URI de session permettant de créer et de reprendre des importations. Cet URI de session sert de jeton d'authentification. Par conséquent, il n'est pas nécessaire de signer les requêtes d'importation PUT. Soyez prudent lorsque vous partagez l'URI de session. Transmettez-le uniquement via HTTPS, car il peut être utilisé par n'importe quel utilisateur pour importer des données dans le bucket cible sans aucune autre authentification.

  • Vous devez également relancer les requêtes qui renvoient les codes d'état suivants :

    • 408 Request Timeout
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • Lorsque vous effectuez une importation avec reprise, traitez les erreurs 404 Not Found en recommençant l'importation depuis le début.

Lorsque vous relancez des requêtes, utilisez un intervalle exponentiel entre les tentatives tronqué.

  • En outre, 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.

  • Les importations avec reprise sont rattachées à la région dans laquelle elles démarrent. Par exemple, si vous créez une URL d'importation avec reprise aux États-Unis et que vous la transmettez à un client en Asie, l'importation transitera toujours par les États-Unis. L'exécution d'une importation avec reprise dans une région autre que celle de son lancement initial peut entraîner des ralentissements.

  • Si vous utilisez des instances Compute Engine avec des processus qui envoient des requêtes POST à Cloud Storage pour lancer une importation avec reprise, vous devez utiliser des instances Compute Engine situées aux mêmes emplacements que vos buckets Cloud Storage. Vous pouvez ensuite faire appel à un service de géolocalisation IP pour sélectionner la région Compute Engine vers laquelle vous acheminez les requêtes des clients, ce qui vous aidera à garder le trafic localisé dans une région géographique.

Optimisation facultative

Si vous recevez une réponse 308 Resume Incomplete sans en-tête Range, il se peut que Cloud Storage ait reçu quelques octets qui n'ont pas encore été conservés au moment de la réception de la requête. Dans ce cas, il n'est pas utile d'importer à nouveau le fichier depuis le début. Pour minimiser ce risque, vous pouvez attendre quelques secondes après la première réponse 308, puis envoyer une deuxième requête. À ce stade, vous pouvez recevoir un en-tête Range, ce qui vous évite d'importer à nouveau le début du fichier. Si vous ne recevez pas d'en-tête Range lors de cette deuxième tentative, n'attendez pas et essayez une troisième fois, car l'envoi d'une nouvelle requête peut bloquer l'importation si Cloud Storage n'a reçu aucune donnée pour l'importation.

Étape suivante