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.
Utilisez l'option d'importation avec reprise dans les cas suivants:
- 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.
Étape 1 : Lancer une session d'importation
Lancez une session d'importation avec reprise en envoyant une requête POST à
https://photoslibrary.googleapis.com/v1/uploads Importez le fichier à l'aide de l'URL d'importation avec reprise renvoyée dans cette requête.
La requête POST doit inclure les en-têtes suivants:
| Champs d'en-tête | |
|---|---|
Content-Length |
Défini 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 sur 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 restants.
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 cette URL de session avec reprise afin de pouvoir 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 :
- 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.
-
En plusieurs fragments. Dans 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é 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 :
- Créez une requête
POSTvers l'URL de la session avec reprise. - Ajoutez les données du fichier au corps de la requête.
Ajoutez les en-têtes HTTP suivants :
Content-Length: défini sur le nombre d'octets dans le .- Définissez
X-Goog-Upload-Commandsurupload, finalize.
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 un code d'état HTTP 200 OK et un jeton d'importation dans le corps de la réponse.
Créez 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 :
- Créez une requête
POSTvers l'URL de la session avec reprise. -
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. La taille des fragments doit être aussi grande que possible pour maintenir l'efficacité de l'importation.
-
Ajoutez les en-têtes HTTP suivants :
Content-Length: défini sur le nombre d'octets du fragment.- Définissez
X-Goog-Upload-Commandsurupload. Pour le dernier bloc, définissez cette valeur surupload, 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 de manière séquentielle. Le premier décalage est0.
- 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. - Répétez ces étapes pour chaque fragment restant dans le fichier.
Si la requête aboutit, vous recevez un code d'é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 permettant d'importer un fichier JPEG de 3 039 417 octets en 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
Requête 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 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 code d'état HTTP autre que 200, interrogez le serveur pour savoir dans quelle mesure l'importation a réussi.
Voici une requête POST vers 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 à partir de ce décalage. 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 est présent dans la réponse HTTP de votre commande de requête et que la valeur n'est pas active, cela signifie que l'importation a déjà été arrêtée.