Effectuer des importations avec reprise

Présentation

Cette page explique comment effectuer une requête d'importation avec reprise dans les API JSON et XML de Cloud Storage. Ce protocole vous permet de reprendre une opération d'importation après un échec de communication ayant interrompu le flux de données.

Pour en savoir plus sur l'utilisation des importations avec reprise dans Google Cloud CLI et les bibliothèques clientes, consultez la page Comment les outils et les API utilisent les importations avec reprise.

Rôles requis

Pour obtenir les autorisations nécessaires pour effectuer une importation avec reprise, demandez à votre administrateur de vous attribuer l'un des rôles suivants :

• Pour les importations qui incluent un verrou de conservation des objets, demandez à votre administrateur de vous attribuer le rôle IAM d'administrateur des objets de l'espace de stockage (roles/storage.objectAdmin) pour le bucket.

• Dans tous les autres cas, demandez à votre administrateur de vous attribuer le rôle IAM "Utilisateur des objets de l'espace de stockage" (roles/storage.objectUser) pour le bucket.

Ces rôles prédéfinis contiennent les autorisations requises pour importer un objet dans un bucket pour leurs cas respectifs. Pour afficher les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

• storage.objects.create
• storage.objects.delete
• Cette autorisation n'est requise que pour les importations qui écrasent un objet existant.
• storage.objects.setRetention
  • Cette autorisation n'est requise que pour les importations comprenant un verrou de conservation des objets.

Vous pouvez également obtenir ces autorisations en utilisant d'autres rôles prédéfinis ou des rôles personnalisés.

Pour en savoir plus sur l'attribution de rôles dans des buckets, consultez la page Utiliser IAM avec des buckets.

Lancer une session d'importation avec reprise

Pour lancer une session d'importation avec reprise, procédez comme suit :

API JSON

1. Vous devez installer et initialiser gcloud CLI afin de générer un jeton d'accès pour l'en-tête Authorization.

   Vous pouvez également créer un jeton d'accès à l'aide d'OAuth 2.0 Playground et l'inclure dans l'en-tête Authorization.

2. Vous pouvez également créer un fichier JSON contenant les métadonnées que vous souhaitez définir sur l'objet que vous importez. Par exemple, le fichier JSON suivant définit les métadonnées contentType de l'objet que vous souhaitez importer dans image/png :

   {
       "contentType": "image/png"
   }

3. Exécutez la commande cURL pour appeler l'API JSON avec une requête POST Object :

   curl -i -X POST --data-binary @METADATA_LOCATION \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json" \
       -H "Content-Length: INITIAL_REQUEST_LENGTH" \
       "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=resumable&name=OBJECT_NAME"

   Où :

   • METADATA_LOCATION correspond au chemin d'accès local au fichier JSON contenant les métadonnées facultatives spécifiées à l'étape précédente. Si vous n'incluez pas de fichier de métadonnées, excluez ce paramètre, ainsi que --data-binary @ et l'en-tête Content-Type.
   • INITIAL_REQUEST_LENGTH correspond au nombre d'octets dans le corps de cette requête initiale, par exemple 79. Ce paramètre n'est pas nécessaire si vous utilisez l'encodage de transfert fragmenté.
   • BUCKET_NAME correspond au nom du bucket dans lequel vous importez votre objet. Par exemple, my-bucket.
   • OBJECT_NAME correspond au nom encodé en URL que vous souhaitez attribuer à l'objet. Par exemple, pets/dog.png, encodé au format URL sous la forme pets%2Fdog.png. Ce paramètre n'est pas obligatoire si vous avez inclus un name dans le fichier de métadonnées de l'objet à l'étape 2.

   Si vous avez activé le partage des ressources entre origines multiples, vous devez également inclure un en-tête Origin dans cette requête et dans les requêtes d'importation suivantes.

   Les en-têtes facultatifs que vous pouvez ajouter à la requête incluent X-Upload-Content-Type et X-Upload-Content-Length.

   Si la requête aboutit, la réponse inclut un code d'état 200.

4. Enregistrez l'URI de session avec reprise fourni dans l'en-tête Location de la réponse à votre requête d'objet POST.

   Cet URI est utilisé dans les requêtes suivantes pour importer les données d'objet.

   Attention : Soyez prudent lorsque vous partagez l'URI de session avec reprise, car il peut être utilisé par n'importe quel utilisateur pour importer des données dans le bucket cible sans aucune autre authentification.

API XML

1. Vous devez installer et initialiser gcloud CLI afin de générer un jeton d'accès pour l'en-tête Authorization.

   Vous pouvez également créer un jeton d'accès à l'aide d'OAuth 2.0 Playground et l'inclure dans l'en-tête Authorization.

2. Exécutez cURL pour appeler l'API XML avec une requête d'objet POST dont le corps est vide :

   curl -i -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Length: 0" \
       -H "Content-Type: OBJECT_CONTENT_TYPE" \
       -H "x-goog-resumable: start" \
       "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

   Où :

   • OBJECT_CONTENT_TYPE correspond au type de contenu de l'objet. Par exemple, image/png. Si vous ne spécifiez pas de type de contenu, le système Cloud Storage définit les métadonnées Content-Type de l'objet sur application/octet-stream.
   • BUCKET_NAME correspond au nom du bucket dans lequel vous importez votre objet. Par exemple, my-bucket.
   • OBJECT_NAME correspond au nom encodé en URL que vous souhaitez attribuer à l'objet. Par exemple, pets/dog.png, encodé au format URL : pets%2Fdog.png.

   Si vous avez activé le partage des ressources entre origines multiples, vous devez également inclure un en-tête Origin dans cette requête et dans les requêtes d'importation suivantes.

   Si la requête aboutit, la réponse inclut un code d'état 201.

3. Enregistrez l'URI de session avec reprise fourni dans l'en-tête Location de la réponse à votre requête d'objet POST.

   Cet URI est utilisé dans les requêtes suivantes pour importer les données d'objet.

   Attention : Soyez prudent lorsque vous partagez l'URI de session avec reprise, car il peut être utilisé par n'importe quel utilisateur pour importer des données dans le bucket cible sans aucune autre authentification.

Importer les données

Une fois que vous avez lancé une importation avec reprise, vous pouvez importer les données de l'objet de deux manières :

• En un seul fragment : cette approche est généralement la meilleure car elle nécessite moins de requêtes et offre donc de meilleures performances.
• Par fragments : utilisez cette approche si vous devez réduire la quantité de données transférées dans une seule requête, par exemple lorsqu'il existe une limite temporelle fixe pour chaque requête, ou si vous ne connaissez pas la taille totale de l'importation au démarrage du processus.

Importation en un seul fragment

Pour importer les données en un seul fragment, procédez comme suit :

API JSON

1. Exécutez cURL pour appeler l'API JSON avec une requête d'objet PUT :

   curl -i -X PUT --data-binary @OBJECT_LOCATION \
       -H "Content-Length: OBJECT_SIZE" \
       "SESSION_URI"

   Où :

   • OBJECT_LOCATION correspond au chemin d'accès local à votre objet. Par exemple, Desktop/dog.png.
   • OBJECT_SIZE correspond au nombre d'octets dans votre objet. Par exemple, 20000000.
   • SESSION_URI correspond à la valeur renvoyée dans l'en-tête Location lorsque vous avez lancé l'importation avec reprise.

   Vous pouvez éventuellement inclure des en-têtes précédés du préfixe X-Goog-Meta- afin d'ajouter des métadonnées personnalisées pour l'objet dans le cadre de cette requête.

API XML

1. Exécutez cURL pour appeler l'API XML avec une requête d'objet PUT :

   curl -i -X PUT --data-binary @OBJECT_LOCATION \
       -H "Content-Length: OBJECT_SIZE" \
       "SESSION_URI"

   Où :

   • OBJECT_LOCATION correspond au chemin d'accès local à votre objet. Par exemple, Desktop/dog.png.
   • OBJECT_SIZE correspond au nombre d'octets dans votre objet. Par exemple, 20000000.
   • SESSION_URI correspond à la valeur renvoyée dans l'en-tête Location lorsque vous avez lancé l'importation avec reprise.

Si l'importation se termine intégralement, vous recevez une réponse 200 OK ou 201 Created, ainsi que toutes les métadonnées associées à la ressource.

Si la requête d'importation est interrompue ou si vous recevez une réponse 5xx, suivez la procédure indiquée dans la section Reprendre une importation interrompue.

Importation par fragments

Pour importer les données en plusieurs fragments, procédez comme suit :

API JSON

1. Créez un fragment de données à partir de l'ensemble des données que vous souhaitez importer.

   La taille des fragments doit être un multiple de 256 Kio (256 x 1 024 octets), à l'exception du fragment final qui termine l'importation. 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. Il est recommandé d'utiliser une taille de fragments d'au moins 8 Mio.

2. Exécutez cURL pour appeler l'API JSON avec une requête d'objet PUT :

   curl -i -X PUT --data-binary @CHUNK_LOCATION \
       -H "Content-Length: CHUNK_SIZE" \
       -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
       "SESSION_URI"

   Où :

   • CHUNK_LOCATION correspond au chemin d'accès local au fragment que vous importez actuellement.
   • CHUNK_SIZE correspond au nombre d'octets que vous importez dans la requête actuelle. Par exemple, 8388608.
   • CHUNK_FIRST_BYTE correspond à l'octet de début dans l'objet global que le fragment que vous importez contient.
   • CHUNK_LAST_BYTE correspond à l'octet de fin dans l'objet global que le fragment que vous importez contient.
   • TOTAL_OBJECT_SIZE correspond à la taille totale de l'objet que vous importez.
   • SESSION_URI correspond à la valeur renvoyée dans l'en-tête Location lorsque vous avez lancé l'importation avec reprise.

   Exemple de Content-Range : Content-Range: bytes 0-8388607/20000000 Pour en savoir plus sur cet en-tête, consultez Content-Range.

   Si la requête aboutit, le serveur envoie une réponse 308 Resume Incomplete. La réponse contient un en-tête Range.

3. Répétez les étapes ci-dessus pour chaque fragment de données restant à importer, en utilisant la valeur supérieure contenue dans l'en-tête Range de chaque réponse pour déterminer où démarrer chaque fragment successif. Ne partez pas du principe que le serveur a reçu tous les octets envoyés dans une requête donnée.

   Si vous le souhaitez, dans la requête finale de l'importation avec reprise, vous pouvez inclure des en-têtes précédés du préfixe X-Goog-Meta- pour ajouter des métadonnées personnalisées à l'objet.

API XML

1. Créez un fragment de données à partir de l'ensemble des données que vous souhaitez importer.

   La taille des fragments doit être un multiple de 256 Kio (256 x 1 024 octets), à l'exception du fragment final qui termine l'importation. 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. Il est recommandé d'utiliser une taille de fragments d'au moins 8 Mio.

2. Exécutez cURL pour appeler l'API XML avec une requête d'objet PUT :

   curl -i -X PUT --data-binary @CHUNK_LOCATION \
       -H "Content-Length: CHUNK_SIZE" \
       -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
       "SESSION_URI"

   Où :

   • CHUNK_LOCATION correspond au chemin d'accès local au fragment que vous importez actuellement.
   • CHUNK_SIZE correspond au nombre d'octets que vous importez dans la requête actuelle. Par exemple, 8388608.
   • CHUNK_FIRST_BYTE correspond à l'octet de début dans l'objet global que le fragment que vous importez contient.
   • CHUNK_LAST_BYTE correspond à l'octet de fin dans l'objet global que le fragment que vous importez contient.
   • TOTAL_OBJECT_SIZE correspond à la taille totale de l'objet que vous importez.
   • SESSION_URI correspond à la valeur renvoyée dans l'en-tête Location lorsque vous avez lancé l'importation avec reprise.

   Exemple de Content-Range : Content-Range: bytes 0-8388607/20000000 Pour en savoir plus sur cet en-tête, consultez Content-Range.

   Si la requête aboutit, le serveur envoie une réponse 308 Resume Incomplete. La réponse contient un en-tête Range.

3. Répétez les étapes ci-dessus pour chaque fragment de données restant à importer, en utilisant la valeur supérieure contenue dans l'en-tête Range de chaque réponse pour déterminer où démarrer chaque fragment successif. Ne partez pas du principe que le serveur a reçu tous les octets envoyés dans une requête donnée.

Une fois l'importation terminée, une réponse 200 OK ou 201 Created s'affiche, ainsi que toutes les métadonnées associées à la ressource.

Si l'une des importations de fragments est interrompue ou si vous recevez une erreur 5xx, vous devez renvoyer le fragment interrompu dans son intégralité ou reprendre l'importation interrompue là où elle s'est arrêtée.

Vérifier l'état d'une importation avec reprise

Si votre importation avec reprise est interrompue ou si vous n'êtes pas certain que celle-ci est terminée, vous pouvez vérifier son état :

API JSON

1. Exécutez cURL pour appeler l'API JSON avec une requête d'objet PUT :

   curl -i -X PUT \
       -H "Content-Length: 0" \
       -H "Content-Range: bytes */OBJECT_SIZE" \
       "SESSION_URI"

   Où :

   • OBJECT_SIZE correspond au nombre total d'octets dans votre objet. Si vous ne connaissez pas la taille totale de votre objet, utilisez * pour cette valeur.
   • SESSION_URI correspond à la valeur renvoyée dans l'en-tête Location lorsque vous avez lancé l'importation avec reprise.

API XML

1. Exécutez cURL pour appeler l'API XML avec une requête d'objet PUT :

   curl -i -X PUT \
       -H "Content-Length: 0" \
       -H "Content-Range: bytes */OBJECT_SIZE" \
       "SESSION_URI"

   Où :

   • OBJECT_SIZE correspond au nombre total d'octets dans votre objet. Si vous ne connaissez pas la taille totale de votre objet, utilisez * pour cette valeur.
   • SESSION_URI correspond à la valeur renvoyée dans l'en-tête Location lorsque vous avez lancé l'importation avec reprise.

Une réponse 200 OK ou 201 Created indique que l'importation a été effectuée et qu'aucune autre action n'est requise.

Une réponse 308 Resume Incomplete indique que vous devez poursuivre l'importation des données.

• Si Cloud Storage n'a pas encore conservé d'octets, la réponse 308 ne comporte pas d'en-tête Range. Dans ce cas, vous devez démarrer votre importation depuis le début.
• Sinon, la réponse 308 comporte un en-tête Range, qui spécifie les octets que Cloud Storage a conservés jusqu'à présent. Utilisez cette valeur lorsque vous reprenez une importation interrompue.

Reprendre une importation interrompue

Important : Cloud Storage ignore tous les octets que vous envoyez à un décalage que Cloud Storage a déjà conservé.

Si une requête d'importation se termine avant de recevoir une réponse, ou si une réponse 503 ou 500 s'affiche, vous devez reprendre l'importation interrompue là où elle s'est arrêtée. Pour reprendre une importation interrompue, procédez comme suit :

API JSON

1. Vérifiez l'état de l'importation avec reprise.

2. Enregistrez la valeur supérieure de l'en-tête Range contenu dans la réponse à votre vérification d'état. Si la réponse ne comporte pas d'en-tête Range, Cloud Storage n'a pas encore conservé d'octets et vous devez importer depuis le début.

3. Vérifiez que les données de l'objet que vous allez importer commencent à l'octet suivant la valeur supérieure de l'en-tête Range.

4. Si la requête interrompue contenait des en-têtes précédés du préfixe X-Goog-Meta-, incluez ces en-têtes dans la requête pour reprendre l'importation.

5. Utilisez cURL pour appeler l'API JSON avec une requête d'objet PUT qui récupère les données à l'octet suivant la valeur dans l'en-tête Range :

   curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
       -H "Content-Length: UPLOAD_SIZE_REMAINING" \
       -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
       "SESSION_URI"

   Où :

   • PARTIAL_OBJECT_LOCATION correspond au chemin d'accès local à la partie de données restante que vous souhaitez importer.
   • UPLOAD_SIZE_REMAINING correspond au nombre d'octets que vous importez dans la requête actuelle. Par exemple, l'importation du reste d'un objet ayant une taille totale de 20 000 000 octets qui a été interrompue après l'importation des octets 0 à 42 aurait une valeur UPLOAD_SIZE_REMAINING de 19999957.
   • NEXT_BYTE correspond au nombre entier qui suit la valeur que vous avez enregistrée à l'étape 2. Par exemple, si la valeur supérieure à l'étape 2 est 42, la valeur de NEXT_BYTE est 43.
   • LAST_BYTE correspond à l'octet de fin contenu dans cette requête PUT. Par exemple, pour terminer l'importation d'un objet dont la taille totale est 20000000, la valeur de LAST_BYTE est 19999999.
   • TOTAL_OBJECT_SIZE correspond à la taille totale de l'objet que vous importez. Par exemple, 20000000.
   • SESSION_URI correspond à la valeur renvoyée dans l'en-tête Location lorsque vous avez lancé l'importation avec reprise.

API XML

1. Vérifiez l'état de l'importation avec reprise.

2. Enregistrez la valeur supérieure de l'en-tête Range contenu dans la réponse à votre vérification d'état. Si la réponse ne comporte pas d'en-tête Range, Cloud Storage n'a pas encore conservé d'octets et vous devez importer depuis le début.

3. Vérifiez que les données de l'objet que vous allez importer commencent à l'octet suivant la valeur supérieure de l'en-tête Range.

4. Utilisez cURL pour appeler l'API XML avec une requête d'objet PUT, qui récupère les données à l'octet suivant la valeur dans l'en-tête Range :

   curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
       -H "Content-Length: UPLOAD_SIZE_REMAINING" \
       -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
       "SESSION_URI"

   Où :

   • PARTIAL_OBJECT_LOCATION correspond au chemin d'accès local à la partie de données restante que vous souhaitez importer.
   • UPLOAD_SIZE_REMAINING correspond au nombre d'octets que vous importez dans la requête actuelle. Par exemple, l'importation du reste d'un objet ayant une taille totale de 20 000 000 octets qui a été interrompue après l'importation des octets 0 à 42 aurait une valeur UPLOAD_SIZE_REMAINING de 19999957.
   • NEXT_BYTE correspond au nombre entier qui suit la valeur que vous avez enregistrée à l'étape 2. Par exemple, si la valeur supérieure à l'étape 2 est 42, la valeur de NEXT_BYTE est 43.
   • LAST_BYTE correspond à l'octet de fin contenu dans cette requête PUT. Par exemple, pour terminer l'importation d'un objet dont la taille totale est 20000000, la valeur de LAST_BYTE est 19999999.
   • TOTAL_OBJECT_SIZE correspond à la taille totale de l'objet que vous importez. Par exemple, 20000000.
   • SESSION_URI correspond à la valeur renvoyée dans l'en-tête Location lorsque vous avez lancé l'importation avec reprise.

Vous pouvez reprendre les importations autant de fois que nécessaire lorsque l'URI de session est actif ; l'URI de la session expire au bout d'une semaine. Une fois les données importées, Cloud Storage répond avec un code d'état 200 OK ou 201 created.

Annuler une importation

Pour annuler une importation avec reprise et éviter toute autre action à ce niveau, procédez comme suit :

API JSON

1. Exécutez cURL pour appeler l'API JSON avec une requête DELETE :

   curl -i -X DELETE -H "Content-Length: 0" \
     "SESSION_URI"

   Où :

   • SESSION_URI correspond à la valeur renvoyée dans l'en-tête Location lorsque vous avez lancé l'importation avec reprise.

Si la requête aboutit, la réponse contient un code d'état 499. Les tentatives ultérieures d'interrogation ou de reprise de l'importation se traduiront par une réponse 4xx.

API XML

1. Exécutez cURL pour appeler l'API XML avec une requête DELETE :

   curl -i -X DELETE -H "Content-Length: 0" \
     "SESSION_URI"

   Où :

   • SESSION_URI correspond à la valeur renvoyée dans l'en-tête Location lorsque vous avez lancé l'importation avec reprise.

Si la requête aboutit, la réponse contient un code d'état 204 et les tentatives futures d'interrogation ou de reprise de l'importation se traduisent également par une réponse 204.

Étape suivante

• Obtenez plus d'informations sur les importations avec reprise.
• Consultez la présentation de l'API JSON et de l'API XML.
• Importations de flux de taille inconnue.
• Regroupez plusieurs requêtes dans l'API JSON de Cloud Storage.