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 depuis 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 à 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éfinissez 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éfinissez le type MIME des données du 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 dans le fichier 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

La section Enregistrer l'URL de la session avec reprise explique comment gérer la réponse à la requête permettant de lancer 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épondra 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 finaliser l'importation dans 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 précision de la 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. Utilisez 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é pour les requêtes individuelles.
    • Vous devez fournir un indicateur personnalisé affichant la progression de l'importation.
    • Vous devez savoir quand il est possible de supprimer des données.

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 : définissez-le sur 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 bloc.
    • Définissez X-Goog-Upload-Command sur upload. Pour le dernier bloc, définissez la valeur sur upload, finalize.
    • X-Goog-Upload-Offset : définissez 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 décrite 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 blocs, à l'aide de l'URL de la session avec reprise et de la précision de la taille obtenues à l'étape précédente. Cet exemple utilise une taille de bloc 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 quelle partie de 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 pourrez ensuite reprendre l'importation à ce décalage. Vous devez reprendre l'importation à l'offset fourni par le serveur, sauf si vous envoyez une commande combinée d'importation et de finalisation. Dans ce cas, vous pouvez également reprendre l'importation à l'offset 0.

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