Importations avec reprise

Cette page explique comment envoyer une demande d'importation avec reprise à l'API Library de Google Photos via le protocole REST. Ce protocole vous permet de reprendre une opération d'importation après un échec de communication interrompt le flux de données.

Si vous êtes un développeur utilisant des bibliothèques clientes, notez que certaines offrent une compatibilité native avec les importations avec reprise.

Utilisez l'option d'importation avec reprise dans les cas suivants:

  • Vous importez des fichiers volumineux.
  • La probabilité d’une interruption du réseau ou d’un autre échec de transmission est élevée (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 réseau car il n'est pas nécessaire de relancer les importations de fichiers volumineux depuis la à partir de zéro.

Étape 1: Lancez une session d'importation

Lancez une session d'importation avec reprise en envoyant une requête POST à https://photoslibrary.googleapis.com/v1/uploads Utiliser l'importation avec reprise URL renvoyée dans cette requête, importez le fichier.

La requête POST doit inclure les en-têtes suivants:

Champs d'en-tête
Content-Length Définissez ce paramètre sur 0, car le corps de la requête est vide.
X-Goog-Upload-Command Définissez cet élément sur start.
X-Goog-Upload-Content-Type Définissez le type MIME du fichier, par exemple, image/jpeg
X-Goog-Upload-Protocol Définissez cet élément sur resumable.
X-Goog-Upload-Raw-Size Définissez le nombre total d'octets des données du fichier à transférées.

Voici un en-tête de requête POST:

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer oauth2-token
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: mime-type
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: bytes-of-file

Étape 2: Enregistrez l'URL de la session

Si l'opération réussit, la requête POST renvoie un code d'état HTTP 200 OK, incluant l'en-tête suivant.

X-Goog-Upload-URL: url-to-make-uploads-to
X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes

Le champ d'en-tête x-goog-upload-chunk-granularity contient l'alignement d'octets et la précision de la taille pour tous les fragments de données envoyés par le client. Si l'importation est effectué en plusieurs fragments, toutes les importations, à l'exception de la dernière, doit être un multiple de cette valeur. c'est-à-dire les octets importés du fichier doit être alignée sur cette valeur. Dans le dernier bloc, vous pouvez importer les octets.

Le champ d'en-tête X-Goog-Upload-URL contient une URL unique qui doit être utilisée pour terminer l'importation avec toutes les demandes restantes. Copiez et enregistrez ceci l'URL de la session avec reprise, ce qui vous permet de l'utiliser pour les requêtes ultérieures.

Étape 3: 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. Avec cette approche, les importations dans plusieurs requêtes en fragmentant les données. Les données sont fragmentées multiples de x-goog-upload-chunk-granularity. Si nécessaire, les requêtes fragmentées peuvent être relancées.

    Utilisez cette approche dans les cas suivants :

    • Vous devez réduire la quantité de données transférées requête. Vous devrez peut-être le faire lorsqu'il y a une limite de temps fixe pour des requêtes individuelles.
    • Vous devez fournir un indicateur personnalisé indiquant l'importation la progression.
    • Vous devez savoir quand supprimer des 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 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éfini sur le nombre d'octets dans le .
    • Définissez X-Goog-Upload-Command sur upload, finalize.

  4. Envoyez la requête.

Si la demande d'importation est interrompue ou si vous recevez une 5xx , suivez la procédure décrite dans la section Réactiver une lors de l'interruption de l'importation.

Si la requête aboutit, vous recevez l'état HTTP 200 OK. et un jeton d'importation dans le corps de la réponse. Créer l'élément multimédia à l'aide de ce jeton d'importation.

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.

    À l'exception du fragment final qui termine l'importation, créez d'autres fragments par multiples de la taille acceptée de fragments. Gardez le soit la plus grande possible pour que l'importation soit efficace.

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

    • Content-Length: défini sur le nombre d'octets dans le bloc.
    • Définissez X-Goog-Upload-Command sur upload. Pour le dernier fragment, définissez la valeur sur upload, finalize.
    • X-Goog-Upload-Offset: définie sur le décalage auquel la octets doivent être écrits. Notez que les octets doivent être importés en série. Le premier décalage est de 0.
  4. Envoyez la requête.

    Si la demande d'importation est interrompue ou si vous recevez une 5xx , suivez la procédure décrite dans la section Réactiver une lors de l'interruption de l'importation.

  5. Répétez les étapes ci-dessus pour chaque fragment restant du fichier.

Si la requête aboutit, vous recevez l'état HTTP 200 OK. et un jeton d'importation dans le corps de la réponse. Créer l'élément multimédia à l'aide de ce jeton d'importation.

Exemple

Demande simple

L'exemple suivant illustre une requête avec reprise pour importer un Fichier JPEG de 3 039 417 octets dans une seule requête.

POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: image/jpeg
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: 3039417
[no body]

La réponse contient l'URL d'importation et la taille de fragment attendue:

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable
X-Goog-Upload-Chunk-Granularity: 262144

La demande d'importation finale:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 3039417
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

Plusieurs fragments

L'exemple suivant illustre une requête avec reprise pour importer un Fichier JPEG de 3 039 417 octets en plusieurs fragments, en utilisant la session avec reprise URL et la précision de taille de fragment acceptée obtenue à l'étape précédente. Cet exemple utilise une taille de segment de 262 144 octets,qui a été renvoyée dans le d'en-tête, x-goog-upload-chunk-granularity, lorsque le a été initialisée. Notez que chaque importation contient des octets sont des multiples de 262 144.

Initialiser la session d'importation pour recevoir l'URL d'importation et la taille des fragments comme décrit à l'étape précédente:

POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: image/jpeg
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: 3039417
[no body]

La réponse contient l'URL d'importation et la taille de fragment attendue:

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable
X-Goog-Upload-Chunk-Granularity: 262144

Premier bloc:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 1048576
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0

[BYTES 0-1048575]

Deuxième bloc:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 1048576
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 1048576

[BYTES 1048576-2097151]

Dernier bloc:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 942265
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 2097152

[BYTES 2097152-4200000]

Reprendre une importation interrompue

Si la requête d'importation est interrompue ou si vous recevez un état HTTP autre que 200 , interrogez le serveur pour connaître le pourcentage de l'importation.

Voici une requête POST envoyée à l'URL de la session avec reprise. X-Goog-Upload-Command doit être définie sur query.

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: query

La réponse du serveur inclut 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 à ce délai. Vous devez reprendre au décalage fournies par le serveur, sauf si vous envoyez une commande combinée d'importation et de finalisation, auquel cas vous pouvez aussi reprendre avec un 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, ce qui indique que l'importation comporte a déjà été clôturée.