Cette page explique comment envoyer une requête d'importation avec reprise à l'API Google Photos Library via le protocole REST. Ce protocole vous permet de reprendre une opération d'importation après un échec de communication ayant interrompu le flux de données.
Si vous êtes développeur et que vous utilisez des bibliothèques clientes, notez que certaines bibliothèques clientes offrent une compatibilité native avec les importations avec reprise.
Utilisez l'option d'importation avec reprise si:
- 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 défaillance du 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
Démarrez une session d'importation avec reprise en envoyant une requête POST à https://photoslibrary.googleapis.com/v1/uploads. À l'aide de l'URL d'importation avec reprise 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 cette valeur 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érer. |
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: Enregistrer l'URL de la session
En cas de succès, 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 des 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ée en plusieurs fragments, toutes les importations, à l'exception de la dernière, doivent être effectuées par multiples de cette valeur. Autrement dit, les octets d'importation du fichier doivent être alignés sur cette valeur. Dans le dernier fragment, 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 via toutes les requêtes restantes. Copiez et enregistrez cette URL de session avec reprise afin de pouvoir l'utiliser pour les requêtes ultérieures.
Étape 3: Importez 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 sont effectuées en plusieurs requêtes par fragmentation des données. Les données sont divisées par multiples de
x-goog-upload-chunk-granularity. Si nécessaire, vous pouvez relancer les requêtes en bloc.Utilisez cette approche dans les cas suivants :
- Vous devez réduire la quantité de données transférées dans une même 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 :
- 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 du fichier.- Définissez
X-Goog-Upload-Commandsurupload, finalize.
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.
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 les autres fragments par multiples de la taille acceptée. La taille des fragments doit être aussi grande que possible pour que l'importation soit efficace.
-
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 fragment, définissez la valeur surupload, 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. Le premier décalage est de0.
- 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. - Répétez les étapes ci-dessus 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éez l'élément multimédia à l'aide de ce jeton d'importation.
Exemple
Demande simple
L'exemple suivant montre une requête avec reprise permettant d'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 montre une requête avec reprise permettant d'importer un fichier JPEG de 3 039 417 octets en plusieurs fragments, en utilisant l'URL de la session avec reprise et la précision de taille de fragment acceptée obtenue à l'étape précédente.
Cet exemple utilise une taille de fragment de 262 144 octets qui a été renvoyée dans le champ d'en-tête, x-goog-upload-chunk-granularity, lors de l'initialisation de la session d'importation. Notez que chaque importation contient des octets qui sont des multiples de 262 144.
Initialisez 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 fragment:
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 connaître le pourcentage de réussite de l'importation.
Voici une requête POST envoyée à l'URL de la session avec reprise. X-Goog-Upload-Command doit être défini 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 pourrez ensuite reprendre l'importation à ce décalage. Vous devez reprendre au décalage fourni par le serveur, sauf si vous envoyez une commande combinée d'importation et de finalisation, 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, cela signifie que l'importation a déjà été terminée.