L'importation d'éléments multimédias s'effectue en deux étapes:
- Importez les octets de vos fichiers multimédias sur un serveur Google à l'aide de la fonction uploads point de terminaison unique. 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 ;
Cette procédure décrit le processus d'importation d'un seul élément multimédia. Si vous utilisez importer plusieurs éléments multimédias (très probablement pour les applications de production) ; Consultez les bonnes pratiques de mise en ligne afin d'améliorer votre processus de mise en ligne. l'efficacité.
Avant de commencer
Champs d'application des autorisations requis
Pour importer des éléments multimédias dans la bibliothèque ou l'album d'un utilisateur,
photoslibrary.appendonly
. Pour en savoir plus sur les champs d'application, consultez
Champs d'application des autorisations
Types et tailles de fichiers acceptés
Vous pouvez importer les types de fichiers répertoriés dans ce tableau.
Type de contenu | Types de fichiers acceptés | Taille maximale du fichier |
---|---|---|
Photos | AVIF, BMP, GIF, HEIC, ICO, JPG, PNG, TIFF, WEBP, ainsi que 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 des octets
Importez des octets vers 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 brute. Utiliser ces importations
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 sur 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 sous la forme d'une chaîne de texte brut est renvoyé en tant que corps de la réponse. Pour créer des contenus multimédias
, utilisez ces chaînes de texte dans l'appel batchCreate
.
upload-token
La taille de fichier suggérée pour les images est inférieure à 50 Mo. Fichiers de plus de 50 Mo sont sujettes à des problèmes de performances.
L'API Library de Google Photos prend en charge les objets avec reprise mises en ligne. Une importation avec reprise permet scindez un fichier multimédia en plusieurs sections et importez 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 que fichiers multimédias éléments dans Google Photos à l'aide de jetons d'importation. Un jeton d'importation est valide pendant un jour après sa création. Un élément multimédia est toujours ajouté bibliothèque. Les éléments multimédias ne peuvent être ajoutés qu'à albums créés par votre l'application. Pour en savoir plus, consultez la page Autorisation champs d'application.
Pour créer des éléments multimédias, appelez mediaItems.batchCreate
en spécifiant une liste de newMediaItems
. Chaque newMediaItem
contient une importation
spécifié à l'intérieur d'un élément simpleMediaItem
, ainsi qu'une description facultative
qui est présentée à l’utilisateur.
Le champ de description est limité à 1 000 caractères et ne doit inclure que du texte pertinent créé par les utilisateurs. Exemple : "Notre voyage au parc". ou "Dîner de Noël". N'incluez pas de métadonnées telles que des noms de fichiers, ou tout autre texte généré automatiquement.
Pour optimiser les performances, réduisez le nombre d'appels vers votre mediaItems.batchCreate
en incluant plusieurs éléments
médias dans un seul appel. Toujours attendre jusqu'à
la requête précédente s'est terminée avant d'effectuer un appel ultérieur pour la même requête
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" } } , ... ] }
Vous pouvez également spécifier albumId
et albumPosition
pour insérer des éléments multimédias à un emplacement spécifique dans 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" } }
Pour en savoir plus sur le positionnement dans les albums, consultez la section Ajouter des enrichissements.
Réponse à la création de l'élément
L'appel mediaItems.batchCreate
renvoie le résultat de chacun des éléments multimédias.
que vous avez essayé de créer. La liste de newMediaItemResults
indique l'état et
inclut l'élément uploadToken
de la requête. Un code d'état différent de zéro indique
.
REST
Si tous les éléments multimédias ont été créés, la requête renvoie
É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
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" } } ] }
Si un élément a bien été ajouté, un mediaItem
contenant les
mediaItemId
, productUrl
et mediaMetadata
. Pour en savoir plus, consultez la section Accéder aux éléments multimédias.
Si l'élément multimédia est une vidéo, elle doit d'abord être traitée. mediaItem
contient un élément status
dans son mediaMetadata
qui décrit le traitement
l'état du fichier vidéo. Un fichier nouvellement importé renvoie d'abord l'état PROCESSING
, avant d'être disponible à l'utilisation en tant qu'READY
. Pour en savoir plus, consultez Accéder aux fichiers multimédias
éléments.
Si vous rencontrez une erreur lors de cet appel, suivez les Consignes pratiques et relancez votre requête. Toi peut vouloir garder une trace des ajouts réussis, afin que l'image puisse être insérée dans l'album à la bonne position lors de la prochaine requête. Pour plus d'informations, consultez la section Créer albums.
Les résultats sont toujours renvoyés dans le même ordre que celui dans lequel les jetons d'importation ont été envoyé.
Bonnes pratiques pour la mise en ligne de vidéos
Les bonnes pratiques et ressources suivantes vous aident à améliorer votre efficacité globale avec les importations:
- Suivez les bonnes pratiques de nouvelle tentative et de gestion des erreurs, en gardant à l'esprit les points suivants :
- Des erreurs
429
peuvent se produire lorsque votre quota est épuisé ou que vous êtes limité en débit en raison d'un nombre d'appels trop élevé et trop rapide. Assurez-vous que vous n'appelez pasbatchCreate
pour le même utilisateur avant l'appel a été traitée. - Les erreurs
429
nécessitent un délai minimal de30s
avant toute nouvelle tentative. Utilisez une stratégie d'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û au fait d'effectuer plusieurs appels d'écriture (commebatchCreate
) pour le même utilisateur à la fois. Vérifiez les détails de votre requête et n'effectuez pas d'appels àbatchCreate
en parallèle.
- Des erreurs
- Utilisez le flux d'importation avec reprise pour rendre vos importations plus robustes en cas d'interruption du réseau. Vous réduirez ainsi l'utilisation de la bande passante en pouvant reprendre les importations partiellement terminées. Ce est important lors de l'importation à partir des appareils mobiles clients les fichiers volumineux.
Tenez également compte des conseils suivants à chaque étape du processus de mise en ligne: importation d'octets, puis création de contenus multimédias éléments.
Importation des octets...
- 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 le
X-Goog-Upload-Content-Type
en-tête pour chaque appel d'importation.
Créer des éléments multimédias
Ne passez pas d'appels en parallèle de
batchCreate
pour un seul utilisateur.- Pour chaque utilisateur, appelez
batchCreate
l'un après l'autre (dans de série). - Pour plusieurs utilisateurs, effectuez toujours des appels
batchCreate
pour chaque utilisateur les uns après les autres. N'effectuez des appels que pour des utilisateurs différents en parallèle.
- Pour chaque utilisateur, appelez
Incluez autant de
NewMediaItems
que possible dans chaque appel àbatchCreate
pour réduire le nombre total d'appels créer. Vous ne pouvez inclure au maximum que 50 éléments.Définissez un texte descriptif pertinent. créés par vos utilisateurs. N'incluez pas de métadonnées telles que des noms de fichiers, des tags programmatiques ou tout autre texte généré automatiquement de la description.
Exemple de tutoriel
Cet exemple utilise du pseudocode pour expliquer comment importer des éléments multimédias pour plusieurs utilisateurs. L'objectif est de décrire les deux étapes du processus de mise en ligne (importation de fichiers octets et création d'éléments multimédias) et détailler les bonnes pratiques pour mettre en place un processus d'importation efficace et résilient. l'intégration.
Étape 1 : Importez des octets bruts
Commencez par créer une file d'attente pour importer les octets bruts de vos éléments multimédias
utilisateurs. Suivez chaque uploadToken
renvoyé par utilisateur. N'oubliez pas les points clés suivants:
- Le nombre de threads d'importation simultanée dépend de votre système d'exploitation environnement.
- Pensez à réorganiser la file d'attente d'importation si nécessaire. Par exemple, vous pouvez hiérarchiser les mises en ligne en fonction du nombre d'importations restantes par utilisateur ; 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 dans 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 ainsi jusqu'à ce que toutes les importations et tous les appels de création de contenu multimédia soient terminés.