Effectuer une importation avec reprise

Cette page explique comment effectuer une requête d'importation avec reprise dans l'API Street View Publish. Ce protocole vous permet de reprendre une opération d'importation après un échec de communication ayant interrompu le flux de données. Utilisez cette option si :

  • Vous importez des fichiers volumineux.
  • Les risques d'interruption du réseau ou d'échec de transmission sont élevés (par exemple, si vous importez un fichier à partir d'une application mobile).

Les importations avec reprise peuvent également réduire l'utilisation de la bande passante en cas de panne réseau, car vous n'avez pas besoin de redémarrer les importations de fichiers volumineux depuis le début.

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

Lancer une session d'importation avec reprise

Une fois que vous avez obtenu un uploadUrl, vous pouvez lancer une session d'importation avec reprise :

  1. Envoyez une requête POST à uploadUrl.

  2. Ajoutez les en-têtes HTTP suivants :

    • Définissez X-Goog-Upload-Protocol sur resumable.
    • X-Goog-Upload-Header-Content-Length : définit le nombre total d'octets des données du fichier à transférer dans les requêtes ultérieures.
    • X-Goog-Upload-Header-Content-Type : défini sur le type MIME des données de fichier.
    • Définissez X-Goog-Upload-Command sur start.

  3. Envoyez la requête.

Exemple : Lancer une session d'importation avec reprise

L'exemple suivant montre comment lancer une session avec reprise pour importer un nouveau fichier. Dans ce cas, le fichier est une image et le nombre total d'octets est de 4 200 000. Notez que le corps de la requête est vide. Par conséquent, l'en-tête Content-Length est défini sur 0.

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234 HTTP/1.1
Authorization: Bearer [YOUR_AUTH_TOKEN]
Content-Length: 0
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Header-Content-Length: 4200000
X-Goog-Upload-Header-Content-Type: image/jpeg
X-Goog-Upload-Command: start

Enregistrer l'URL de la session avec reprise explique comment gérer la réponse à la requête de lancement de la session d'importation avec reprise.

Enregistrer l'URL de la session avec reprise

Pour la requête envoyée afin de lancer une session d'importation avec reprise, le serveur répond avec un code d'état HTTP 200 OK, y compris l'en-tête suivant :

  • X-Goog-Upload-URL: URL unique qui doit être utilisée pour terminer l'importation avec toutes les requêtes restantes.

Copiez et enregistrez l'URL de la session avec reprise afin de pouvoir l'utiliser dans les requêtes ultérieures.

Exemple : Enregistrer l'URL de la session avec reprise

L'exemple suivant illustre une réponse qui inclut une URL de session avec reprise et une exigence de granularité de taille.

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable

Importer le fichier

Il existe deux façons d'importer un fichier dans le cadre d'une session avec reprise :

  1. Via une requête unique. Cette approche est généralement la meilleure, car elle nécessite moins de requêtes et offre donc de meilleures performances.
  2. En plusieurs fragments. Suivez cette approche si :
    • Vous devez réduire la quantité de données transférées dans chaque requête. Vous devrez peut-être effectuer cette opération lorsque le temps imparti à chaque requête est limité.
    • Vous devez fournir un indicateur personnalisé affichant la progression de l'importation.
    • Vous devez savoir quand vous pouvez supprimer des données en toute sécurité.

Requête unique

Pour importer le fichier via une seule requête, procédez comme suit :

  1. Créez une requête POST vers l'URL de la session avec reprise.
  2. Ajoutez les données du fichier au corps de la requête.

  3. Ajoutez les en-têtes HTTP suivants :

    • Content-Length : spécifiez-y le nombre d'octets du fichier.
    • Définissez X-Goog-Upload-Command sur upload, finalize.

  4. Envoyez la requête.

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.

Plusieurs fragments

Pour importer le fichier en plusieurs fragments, procédez comme suit :

  1. Créez une requête POST vers l'URL de la session avec reprise.
  2. Ajoutez les données du fragment au corps de la requête. Créez des fragments par multiples de 2 Mio (mébioctets), à l'exception du fragment final qui termine l'importation. La taille des fragments doit être aussi grande que possible pour maintenir l'efficacité de l'importation.

  3. Ajoutez les en-têtes HTTP suivants :

    • Content-Length: défini sur le nombre d'octets du fragment.
    • Définissez X-Goog-Upload-Command sur upload. Pour le dernier fragment, définissez la valeur sur upload, finalize.
    • X-Goog-Upload-Offset : définit le décalage auquel les octets doivent être écrits. Notez que les octets doivent être importés de manière séquentielle.

  4. Envoyez la requête. 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.

  5. Répétez les étapes 1 à 4 pour chaque fragment restant dans le fichier.

Exemple : Importer le fichier

Requête unique

L'exemple suivant illustre une requête avec reprise permettant d'importer un fichier JPEG de 4 200 000 octets en une seule requête, à l'aide de l'URL de la session avec reprise obtenue à l'étape précédente :

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 4200000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

Si la requête aboutit, vous recevez un code d'état HTTP 200 OK.

Plusieurs fragments

L'exemple suivant illustre une requête avec reprise permettant d'importer un fichier JPEG de 4 200 000 octets en plusieurs segments, à l'aide de l'URL de la session avec reprise et de la granularité de taille obtenue à l'étape précédente. Cet exemple utilise une taille de fragment de 2 097 000 octets, qui est un multiple de 2 Mio (mébioctets).

Premier bloc : 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0



[BYTES 0-2096999]

Deuxième bloc : 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 2097000



[BYTES 2097000-4193999]

Dernier bloc: 

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 6000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 4194000



[BYTES 4194000-4200000]

Reprendre une importation interrompue

Si la requête d'importation est interrompue ou si vous recevez un code d'état HTTP autre que 200, interrogez le serveur pour savoir dans quelle mesure l'importation a réussi :

  1. Créez une requête POST vers l'URL de la session avec reprise.
  2. Définissez X-Goog-Upload-Command sur query.
  3. Envoyez la requête.

Le serveur répond avec un code d'état HTTP 200 OK et la taille actuelle de l'importation :

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-Size-Received: 100

Vous pouvez ensuite reprendre l'importation à partir de ce décalage. Vous devez reprendre à l'offset fourni par le serveur, sauf si vous envoyez une commande d'importation et de finalisation combinée, auquel cas vous pouvez également reprendre à l'offset 0.

Si l'en-tête X-Goog-Upload-Status de la réponse HTTP de votre commande de requête est présent et que la valeur n'est pas active, cela signifie que l'importation a déjà été interrompue.