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 la Google Cloud CLI et les bibliothèques clientes, consultez Utilisation des importations avec reprise par les outils et les API.

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 "Administrateur des objets Storage" (roles/storage.objectAdmin) pour le bucket.

  • Dans tous les autres cas, demandez à votre administrateur de vous attribuer le rôle IAM "Utilisateur d'objets Storage" (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 d'utilisation respectifs. Pour connaître 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 sur des buckets, consultez Définir et gérer des stratégies IAM sur des buckets.

Lancer une session d'importation avec reprise

Pour lancer une session d'importation avec reprise :

API JSON

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

  2. Vous pouvez également créer un fichier 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. Utilisez 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.
    • 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. 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é Cross-Origin Resource Sharing, vous devez également inclure un en-tête Origin dans cette requête et 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 et ressemble à ce qui suit :

    HTTP/2 200
content-type: text/plain; charset=utf-8
x-guploader-uploadid: ABgVH8_jqDHM_KOvNAJCx73r9v5fINktk9U-pXana1szCM5803tlJ7CKsRbDxkyYCrfEiNqzcZ6B7DfoDtc-bdzpH-SpVTAMEO9EQV34qG0-0yk
location: https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=resumable&name=cat-pic.jpeg&upload_id=ABgVH8_jqDHM_KOvNAJCx73r9v5fINktk9U-pXana1szCM5803tlJ7CKsRbDxkyYCrfEiNqzcZ6B7DfoDtc-bdzpH-SpVTAMEO9EQV34qG0-0yk
date: Mon, 07 Jul 2025 14:57:21 GMT
vary: Origin
vary: X-Origin
cache-control: no-cache, no-store, max-age=0, must-revalidate
expires: Mon, 01 Jan 1990 00:00:00 GMT
pragma: no-cache
content-length: 0
server: UploadServer
alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000

  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.

API XML

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

  2. Utilisez cURL pour appeler l'API XML avec une requête POST Object 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é Cross-Origin Resource Sharing, vous devez également inclure un en-tête Origin dans cette requête et 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.

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 une fois : 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 des données à importer au démarrage du processus.

Importation en une fois

Pour importer les données en une fois, procédez comme suit :

API JSON

  1. Utilisez 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. Utilisez 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 s'effectue intégralement, vous recevez une réponse 200 OK ou 201 Created, accompagnée de 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 Reprendre une importation interrompue.

Importation par fragments

Pour importer les données en plusieurs fragments :

API JSON

  1. Créez un fragment de données à partir du jeu de données que vous souhaitez importer.

    La taille des fragments doit être un multiple de 256 Kio (256 x 1 024 octets), exception faite du fragment final qui termine l'importation. Des 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. Utilisez 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. 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.

    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 renvoie 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 nouveau fragment. 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 du jeu de données que vous souhaitez importer.

    La taille des fragments doit être un multiple de 256 Kio (256 x 1 024 octets), exception faite du fragment final qui termine l'importation. Des 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. Utilisez 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. 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.

    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 renvoie 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 nouveau fragment. 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, vous recevez une réponse 200 OK ou 201 Created s'affiche, accompagnée de toutes les métadonnées associées à la ressource.

Si l'une des importations de fragments est interrompue ou si une erreur 5xx vous est renvoyée, 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. Utilisez 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. Utilisez 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 avec succès et qu'aucune autre action n'est requise.

Une réponse 308 Resume Incomplete indique que vous devez poursuivre l'importation du fichier.

  • Si Cloud Storage n'a pas encore reçu et 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

Si une requête d'importation se termine avant que vous receviez 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 :

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 pu conserver d'octets et vous devez reprendre l'importation 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 spécifiée 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. 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. 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 pu conserver d'octets et vous devez reprendre l'importation 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 spécifiée 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. 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.

Vous pouvez reprendre les importations autant de fois que nécessaire tant que l'URI de session est actif. L'URI de 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 non achevée et éviter toute autre action sur celle-ci :

API JSON

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

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

    Où :

Si la requête aboutit, la réponse contient un code d'état 499. Les tentatives ultérieures d'envoi de requête ou de reprise de l'importation entraîneront une réponse 4xx.

API XML

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

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

    Où :

Si la requête aboutit, la réponse contient un code d'état 204 et les tentatives futures d'envoi de requête ou de reprise de l'importation entraîneront également une réponse 204.

Gestion des échecs

Dans de rares cas, une requête de reprise d'une importation interrompue peut échouer avec une erreur "4xx" (non récupérable), du fait que les autorisations sur le bucket ont été modifiées ou que le contrôle d'intégrité a détecté une incohérence sur l'objet final importé. Si cela se produit, réessayez d'importer l'ensemble des données en lançant une nouvelle session d'importation avec reprise.

Étapes suivantes