Effectuer une importation avec reprise

Cette page explique comment effectuer une requête d'importation avec reprise dans l'API Street View Publishing. 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.
  • Le risque d'interruption du réseau ou d'un autre échec de transmission est élevé (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 défaillance du réseau, car vous n'avez pas besoin de redémarrer les importations de fichiers volumineux dès le départ.

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

Lancer une session d'importation avec reprise

Après avoir obtenu un uploadUrl, vous pouvez lancer une session d'importation avec reprise:

  1. Créez une requête POST pour 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, qui seront transférés dans les requêtes ultérieures.
    • X-Goog-Upload-Header-Content-Type: défini sur 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 son 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

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

Enregistrer l'URL de la session avec reprise

Pour que 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, qui comprend l'en-tête suivant:

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

Copiez et enregistrez l'URL de résolution avec reprise afin de pouvoir l'utiliser pour les requêtes ultérieures.

Exemple: Enregistrer l'URL de la session avec reprise

L'exemple suivant montre 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 dans les cas suivants :
    • Vous devez réduire la quantité de données transférées par 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é indiquant la progression de l'importation.
    • Vous devez savoir quand supprimer les données en toute sécurité.

Demande simple

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

  1. Créez une requête POST pour 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 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 décrite dans la section Reprendre une importation interrompue.

Friandises à plusieurs morceaux

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

  1. Créez une requête POST pour 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 que l'importation soit efficace.

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

    • Content-Length: définissez 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éfini sur le décalage auquel les octets doivent être écrits. Notez que les octets doivent être importés en série.

  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

Demande simple

L'exemple suivant montre une requête avec reprise permettant d'importer un fichier JPEG complet de 4 200 000 octets en une seule requête, en utilisant l'URL de 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.

Friandises à plusieurs morceaux

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

Premier fragment :

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

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

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 non-200, interrogez le serveur pour connaître le pourcentage de réussite de l'importation:

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

Le serveur renvoie 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 au décalage fourni par le serveur, sauf si vous envoyez une commande d'importation et de finalisation combinée, auquel cas vous pouvez également reprendre au décalage de 0.

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