L'importation des éléments multimédias s'effectue en deux étapes:
- Importez les octets de vos fichiers multimédias sur un serveur Google à l'aide du point de terminaison des importations. Cela renvoie un jeton d'importation qui identifie les octets importés.
- Utilisez un appel batchCreate avec le jeton d'importation pour créer un élément multimédia dans le compte Google Photos de l'utilisateur.
Ces étapes décrivent le processus d'importation d'un seul élément multimédia. Si vous importez plusieurs éléments multimédias (très probablement pour toute application de production), consultez les bonnes pratiques concernant les importations pour améliorer l'efficacité de l'importation.
Avant de commencer
Champs d'application des autorisations requis
L'importation d'éléments multimédias dans la bibliothèque ou l'album d'un utilisateur nécessite le champ d'application photoslibrary.appendonly
ou photoslibrary
.
Vous pouvez également créer des éléments multimédias à l'aide du champ d'application photoslibrary.sharing
. Pour créer des éléments avec le champ d'application photoslibrary.sharing
, vous devez d'abord créer un album et le marquer comme partagé à l'aide de shareAlbum
. Vous pouvez ensuite créer des éléments multimédias
qui sont partagés avec l'utilisateur dans l'album. Vous ne pouvez pas créer d'éléments directement dans la bibliothèque de l'utilisateur ni dans des albums que votre application n'a pas partagés.
Lorsque vous répertoriez des albums, la propriété isWriteable
indique si votre application est autorisée à créer des contenus multimédias dans un album particulier.
Types et tailles de fichiers acceptés
Vous pouvez importer les types de fichiers répertoriés dans le tableau ci-dessous.
Type de contenu | Types de fichiers acceptés | Taille maximale du fichier |
---|---|---|
Photos | AVIF, BMP, GIF, HEIC, ICO, JPG, PNG, TIFF, WEBP, certains fichiers RAW. | 200 Mo |
Vidéos | 3GP, 3G2, ASF, AVI, DIVX, M2T, M2TS, M4V, MKV, MMV, MOD, MOV, MP4, MPG, MTS, TOD, WMV. | 20 Go |
Étape 1: Importer les octets
Importez des octets dans Google à l'aide de requêtes d'importation. Une requête d'importation réussie renvoie un jeton d'importation sous la forme d'une chaîne de texte brut. Utilisez ces jetons d'importation pour créer des éléments multimédias avec l'appel batchCreate
.
REST
Incluez les champs suivants dans l'en-tête de requête POST:
Champs d'en-tête | |
---|---|
Content-type |
Définissez cet élément sur application/octet-stream . |
X-Goog-Upload-Content-Type |
Recommandé. Définissez le type MIME des octets que vous importez.
Les types MIME courants incluent image/jpeg , image/png et image/gif .
|
X-Goog-Upload-Protocol |
Définissez cet élément sur raw . |
Voici un en-tête de requête POST:
POST https://photoslibrary.googleapis.com/v1/uploads Authorization: Bearer oauth2-token Content-type: application/octet-stream X-Goog-Upload-Content-Type: mime-type X-Goog-Upload-Protocol: raw
Dans le corps de la requête, incluez le binaire du fichier:
media-binary-data
Si cette requête POST aboutit, un jeton d'importation se présentant sous la forme d'une chaîne de texte brut est renvoyé dans le corps de la réponse. Pour créer des éléments multimédias, utilisez ces chaînes de texte dans l'appel batchCreate
.
upload-token
Java
// Open the file and automatically close it after upload try (RandomAccessFile file = new RandomAccessFile(pathToFile, "r")) { // Create a new upload request UploadMediaItemRequest uploadRequest = UploadMediaItemRequest.newBuilder() // The media type (e.g. "image/png") .setMimeType(mimeType) // The file to upload .setDataFile(file) .build(); // Upload and capture the response UploadMediaItemResponse uploadResponse = photosLibraryClient.uploadMediaItem(uploadRequest); if (uploadResponse.getError().isPresent()) { // If the upload results in an error, handle it Error error = uploadResponse.getError().get(); } else { // If the upload is successful, get the uploadToken String uploadToken = uploadResponse.getUploadToken().get(); // Use this upload token to create a media item } } catch (ApiException e) { // Handle error } catch (IOException e) { // Error accessing the local file }
PHP
try { // Create a new upload request by opening the file // and specifying the media type (e.g. "image/png") $uploadToken = $photosLibraryClient->upload(file_get_contents($localFilePath), null, $mimeType); } catch (\GuzzleHttp\Exception\GuzzleException $e) { // Handle error }
La taille de fichier recommandée pour les images est inférieure à 50 Mo. Les fichiers d'une taille supérieure à 50 Mo sont susceptibles de rencontrer des problèmes de performances.
L'API Library de Google Photos est compatible avec les importations avec reprise. Une importation avec reprise vous permet de diviser un fichier multimédia en plusieurs sections et d'importer une section à la fois.
Étape 2: Créer un élément multimédia
Après avoir importé les octets de vos fichiers multimédias, vous pouvez les créer en tant qu'éléments multimédias dans Google Photos à l'aide de jetons d'importation. Un jeton d'importation est valide un jour après sa création. Un élément multimédia est toujours ajouté à la bibliothèque de l'utilisateur. Les éléments multimédias ne peuvent être ajoutés qu'aux albums créés par votre application. Pour en savoir plus, consultez la section Champs d'application des autorisations.
Pour créer des éléments multimédias, appelez mediaItems.batchCreate
en spécifiant une liste de newMediaItems
. Chaque newMediaItem
contient un jeton d'importation spécifié dans un simpleMediaItem
et une description facultative visible par l'utilisateur.
Le champ de description est limité à 1 000 caractères et ne doit inclure que du texte pertinent créé par les utilisateurs. Par exemple, "Notre voyage au parc" ou "Dîner de Noël". N'incluez pas de métadonnées telles que les noms de fichiers, les tags programmatiques ou tout autre texte généré automatiquement.
Pour de meilleures performances, réduisez le nombre d'appels à mediaItems.batchCreate
que vous devez effectuer en incluant plusieurs éléments multimédias dans un seul appel. Attendez toujours la fin de la requête précédente avant d'effectuer un appel ultérieur pour le même utilisateur.
Vous pouvez créer un ou plusieurs éléments multimédias dans la bibliothèque d'un utilisateur en spécifiant les descriptions et les jetons d'importation correspondants:
REST
Voici l'en-tête de requête POST:
POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate Content-type: application/json Authorization: Bearer oauth2-token
Le corps de la requête doit spécifier une liste de newMediaItems
.
{ "newMediaItems": [ { "description": "item-description", "simpleMediaItem": { "fileName": "filename", "uploadToken": "upload-token" } } , ... ] }
Java
try { // Create a NewMediaItem with the following components: // - uploadToken obtained from the previous upload request // - filename that will be shown to the user in Google Photos // - description that will be shown to the user in Google Photos NewMediaItem newMediaItem = NewMediaItemFactory .createNewMediaItem(uploadToken, fileName, itemDescription); List<NewMediaItem> newItems = Arrays.asList(newMediaItem); BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems); for (NewMediaItemResult itemsResponse : response.getNewMediaItemResultsList()) { Status status = itemsResponse.getStatus(); if (status.getCode() == Code.OK_VALUE) { // The item is successfully created in the user's library MediaItem createdItem = itemsResponse.getMediaItem(); } else { // The item could not be created. Check the status and try again } } } catch (ApiException e) { // Handle error }
PHP
try { $newMediaItems = []; // Create a NewMediaItem with the following components: // - uploadToken obtained from the previous upload request // - filename that will be shown to the user in Google Photos // - description that will be shown to the user in Google Photos $newMediaItems[0] = PhotosLibraryResourceFactory::newMediaItemWithDescriptionAndFileName( $uploadToken, $itemDescription, $fileName); $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems); foreach ($response->getNewMediaItemResults() as $itemResult) { $status = $itemResult->getStatus(); if ($status->getCode() != Code::OK) { // Error while creating the item. } } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Vous pouvez ajouter des éléments multimédias à la bibliothèque et à un album en spécifiant l'album id
. Pour en savoir plus, consultez Créer des albums.
Chaque album peut contenir jusqu'à 20 000 éléments multimédias. Les requêtes de création d'éléments multimédias dans un album qui dépassent cette limite échoueront.
REST
{ "albumId": "album-id", "newMediaItems": [ { "description": "item-description", "simpleMediaItem": { "fileName": "filename", "uploadToken": "upload-token" } } , ... ] }
Java
try { // Create new media items in a specific album BatchCreateMediaItemsResponse response = photosLibraryClient .batchCreateMediaItems(albumId, newItems); // Check the response } catch (ApiException e) { // Handle error }
PHP
try { $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems, ['albumId' => $albumId]); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Vous pouvez également spécifier albumId
et albumPosition
pour insérer des éléments multimédias à un emplacement spécifique de l'album.
REST
{ "albumId": "album-id", "newMediaItems": [ { "description": "item-description", "simpleMediaItem": { "fileName": "filename", "uploadToken": "upload-token" } } , ... ], "albumPosition": { "position": "after-media-item", "relativeMediaItemId": "media-item-id" } }
Java
try { // Create new media items in a specific album, positioned after a media item AlbumPosition positionInAlbum = AlbumPositionFactory.createFirstInAlbum(); BatchCreateMediaItemsResponse response = photosLibraryClient .batchCreateMediaItems(albumId, newItems, positionInAlbum); // Check the response } catch (ApiException e) { // Handle error }
PHP
try { $albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId); $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems, ['albumId' => $albumId, 'albumPosition' => $albumPosition]); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Pour en savoir plus sur le positionnement dans les albums, consultez Ajouter des informations enrichies.
Réponse à la création de l'élément
L'appel mediaItems.batchCreate
renvoie le résultat pour chacun des éléments multimédias que vous avez essayé de créer. La liste des newMediaItemResults
indique l'état et inclut les uploadToken
de la requête. Un code d'état non nul indique une erreur.
REST
Si tous les éléments multimédias ont bien été créés, la requête renvoie l'état HTTP 200 OK
. Si certains éléments multimédias ne peuvent pas être créés, la requête renvoie l'état HTTP 207 MULTI-STATUS
pour indiquer un succès partiel.
{ "newMediaItemResults": [ { "uploadToken": "upload-token", "status": { "message": "Success" }, "mediaItem": { "id": "media-item-id", "description": "item-description", "productUrl": "https://photos.google.com/photo/photo-path", "mimeType": "mime-type", "mediaMetadata": { "width": "media-width-in-px", "height": "media-height-in-px", "creationTime": "creation-time", "photo": {} }, "filename": "filename" } }, { "uploadToken": "upload-token", "status": { "code": 13, "message": "Internal error" } } ] }
Java
BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems); // The response contains a list of NewMediaItemResults for (NewMediaItemResult result : response.getNewMediaItemResultsList()) { // Each result item is identified by its uploadToken String uploadToken = result.getUploadToken(); Status status = result.getStatus(); if (status.getCode() == Code.OK_VALUE) { // If the request is successful, a MediaItem is returned MediaItem mediaItem = result.getMediaItem(); String id = mediaItem.getId(); String productUrl = mediaItem.getProductUrl(); // ... } }
PHP
// The response from a call to batchCreateMediaItems returns a list of NewMediaItemResults foreach ($response->getNewMediaItemResults() as $itemResult) { // Each result item is identified by its uploadToken $itemUploadToken = $itemResult->getUploadToken(); // Verify the status of each entry to ensure that the item has been uploaded correctly $itemStatus = $itemResult->getStatus(); if ($itemStatus->getCode() != Code::OK) { // Error when item is being created } else { // Media item is successfully created // Get the MediaItem object from the response $mediaItem = $itemResult->getMediaItem(); // It contains details such as the Id of the item, productUrl $id = $mediaItem->getId(); $productUrl = $mediaItem->getProductUrl(); // ... } }
Si un élément a bien été ajouté, une mediaItem
est renvoyée contenant ses éléments mediaItemId
, productUrl
et mediaMetadata
. Pour en savoir plus, consultez Accéder aux éléments multimédias.
Si l'élément multimédia est une vidéo, il doit d'abord être traité. L'mediaItem
contient un status
dans son mediaMetadata
qui décrit l'état de traitement du fichier vidéo. Un fichier nouvellement importé renvoie d'abord l'état PROCESSING
, avant l'état READY
. Pour en savoir plus, consultez Accéder aux éléments multimédias.
Si vous rencontrez une erreur lors de cet appel, suivez les bonnes pratiques et relancez votre requête. Vous pouvez effectuer le suivi des ajouts réussis afin que l'image puisse être insérée dans l'album à la bonne position lors de la requête suivante. Pour en savoir plus, consultez Créer des albums.
Les résultats sont toujours renvoyés dans l'ordre dans lequel les jetons d'importation ont été soumis.
Bonnes pratiques concernant les importations
Les bonnes pratiques et ressources suivantes vous aident à améliorer votre efficacité globale avec les importations:
- utiliser l'une de nos bibliothèques clientes compatibles ;
- Suivez les bonnes pratiques concernant les nouvelles tentatives et la gestion des erreurs, en gardant à l'esprit les points suivants :
- Des erreurs
429
peuvent se produire lorsque votre quota a été épuisé ou que vous êtes limité en raison d'un nombre excessif d'appels trop rapides. Assurez-vous de ne pas appelerbatchCreate
pour le même utilisateur tant que la requête précédente n'est pas terminée. - Les erreurs
429
nécessitent un délai minimal de30s
avant toute nouvelle tentative. Utilisez un intervalle exponentiel entre les tentatives lorsque vous relancez des requêtes. - Les erreurs
500
se produisent lorsque le serveur rencontre une erreur. Lors de l'importation, cela est probablement dû à plusieurs appels en écriture (tels quebatchCreate
) pour le même utilisateur en même temps. Vérifiez les détails de votre requête et n'appelez pasbatchCreate
en parallèle.
- Des erreurs
- Utilisez le flux d'importation avec reprise pour renforcer vos importations en cas d'interruptions du réseau, ce qui réduit l'utilisation de la bande passante en vous permettant de reprendre des importations partiellement terminées. Cette étape est importante lors de l'importation à partir d'appareils mobiles clients ou de fichiers volumineux.
Pensez également aux conseils suivants pour chaque étape du processus d'importation : importer des octets, puis créer des éléments multimédias.
Octets importés
- L'importation d'octets (pour récupérer les jetons d'importation) peut être effectuée en parallèle.
- Définissez toujours le type MIME approprié dans l'en-tête
X-Goog-Upload-Content-Type
pour chaque appel d'importation.
Créer des éléments multimédias
N'effectuez pas d'appels en parallèle de
batchCreate
pour un seul utilisateur.- Pour chaque utilisateur, appelez
batchCreate
l'un après l'autre (en série). - Si vous avez plusieurs utilisateurs, effectuez toujours des appels
batchCreate
pour chacun d'eux, l'un après l'autre. Vous ne pouvez appeler que différents utilisateurs en parallèle.
- Pour chaque utilisateur, appelez
Incluez autant d'
NewMediaItems
que possible dans chaque appel àbatchCreate
afin de réduire le nombre total d'appels à effectuer. Vous ne pouvez pas inclure plus de 50 éléments.Définissez un texte de description pertinent qui a été créé par vos utilisateurs. N'incluez pas de métadonnées telles que des noms de fichier, des tags programmatiques ou d'autres textes générés automatiquement dans le champ de description.
Exemple de tutoriel
Cet exemple utilise un pseudo-code pour suivre l'importation d'éléments multimédias pour plusieurs utilisateurs. L'objectif est de décrire les deux étapes du processus d'importation (importation d'octets bruts et création d'éléments multimédias), ainsi que les bonnes pratiques à suivre pour créer une intégration d'importation efficace et résiliente.
Étape 1: Importer les octets bruts
Commencez par créer une file d'attente pour importer les octets bruts de vos éléments multimédias à partir de tous vos utilisateurs. Suivez chacun des uploadToken
renvoyés par utilisateur. N'oubliez pas ces points clés:
- Le nombre de threads d'importation simultanés dépend de votre environnement d'exploitation.
- Envisagez de réorganiser la file d'attente d'importation si nécessaire. Par exemple, vous pouvez hiérarchiser les importations en fonction du nombre d'importations restantes par utilisateur, de la progression globale de l'utilisateur ou d'autres exigences.
Pseudo-code
CREATE uploadQueue FROM users, filesToUpload // Upload media bytes in parallel. START multiple THREADS WHILE uploadQueue is not empty POP uploadQueue UPLOAD file for user GET uploadToken CHECK and HANDLE errors STORE uploadToken for user in uploadTokensQueue END
Étape 2: Créez des éléments multimédias
À l'étape 1, vous pouvez importer plusieurs octets de plusieurs utilisateurs en parallèle, mais à l'étape 2, vous ne pouvez effectuer qu'un seul appel à la fois pour chaque utilisateur.
Pseudo-code
// For each user, create media items once 50 upload tokens have been // saved, or no more uploads are left per user. WHEN uploadTokensQueue for user is >= 50 OR no more pending uploads for user // Calls can be made in parallel for different users, // but only make a single call per user at a time. START new thread for (this) user if there is no thread yet POP 50 uploadTokens from uploadTokensQueue for user CALL mediaItems.batchCreate with uploadTokens WAIT UNTIL batchCreate call has completed CHECK and HANDLE errors (retry as needed) DONE.
Continuez jusqu'à ce que toutes les importations et tous les appels de création multimédia soient terminés.