Effectuer des importations avec reprise

Accéder aux concepts

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.

Lancer une session d'importation avec reprise

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

API JSON

  1. Obtenez un jeton d'autorisation d'accès sur la page OAuth 2.0 Playground. Configurez Playground pour utiliser vos propres identifiants OAuth. Pour obtenir des instructions, consultez la page Authentification des API.
  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.

  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 OAUTH2_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.
    • OAUTH2_TOKEN correspond au jeton d'accès que vous avez généré à l'étape 1.
    • 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. Exemple : my-bucket.
    • OBJECT_NAME correspond au nom que vous souhaitez attribuer à l'objet. Exemple :pets/dog.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.

API XML

  1. Obtenez un jeton d'autorisation d'accès sur la page OAuth 2.0 Playground. Configurez Playground pour utiliser vos propres identifiants OAuth. Pour obtenir des instructions, consultez la page Authentification des API.
  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 OAUTH2_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ù :

    • OAUTH2_TOKEN correspond au jeton d'accès que vous avez généré à l'étape 1.
    • 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. Exemple :my-bucket
    • OBJECT_NAME correspond au nom que vous souhaitez attribuer à l'objet. Exemple :pets/dog.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.

Importer le fichier

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 le fichier 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. Exemple :Desktop/dog.png
    • OBJECT_SIZE correspond au nombre d'octets dans votre objet. 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. 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. Exemple :Desktop/dog.png
    • OBJECT_SIZE correspond au nombre d'octets dans votre objet. 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 le fichier en plusieurs fragments, procédez comme suit :

API JSON

  1. Créez un fragment de données à partir du fichier 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 grandes améliorent généralement l'efficacité des importations. Nous vous recommandons d'utiliser au moins 8 Mio pour la taille des fragments.

  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. Exemple :524288
    • 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-524287/2000000 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. Utilisez la valeur supérieure de cet en-tête pour déterminer où démarrer le prochain fragment. Ne partez pas du principe que le serveur a reçu tous les octets envoyés dans la requête précédente.

  3. Répétez les étapes ci-dessus pour chaque fragment de données à importer.

API XML

  1. Créez un fragment de données à partir du fichier 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 grandes améliorent généralement l'efficacité des importations. Nous vous recommandons d'utiliser au moins 8 Mio pour la taille des fragments.

  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. Exemple :524288
    • 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-524287/2000000 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. Utilisez la valeur supérieure de cet en-tête pour déterminer où démarrer le prochain fragment. Ne partez pas du principe que le serveur a reçu tous les octets envoyés dans la requête précédente.

  3. Répétez les étapes ci-dessus pour chaque fragment de données à importer.

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 une réponse 5xx s'affiche, suivez la procédure décrite dans la section Reprendre une importation interrompue.

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 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ù :

    • OBEJCT_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ù :

    • OBEJCT_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 du fichier.

  • 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

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. 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 1999957.
    • 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 1999999.
    • TOTAL_OBJECT_SIZE correspond à la taille totale de l'objet que vous importez. 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 1999957.
    • 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 1999999.
    • TOTAL_OBJECT_SIZE correspond à la taille totale de l'objet que vous importez. 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 le fichier importé, 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ù :

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ù :

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