Importer l'élément multimédia

L'importation d'éléments multimédias se fait en deux étapes :

1. Importez les octets de vos fichiers multimédias sur un serveur Google à l'aide du point de terminaison des importations. Cette opération renvoie un jeton d'importation qui identifie les octets importés.
2. 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 la procédure d'importation d'un seul élément multimédia. Si vous importez plusieurs éléments multimédias (très probablement pour les applications de production), consultez les bonnes pratiques d'importation afin d'améliorer votre efficacité.

Avant de commencer

Champs d'application d'autorisation 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. Pour en savoir plus sur les champs d'application, consultez la section 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.

É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. Utilisez ces jetons d'importation pour créer des éléments multimédias avec l'appel batchCreate.

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

media-binary-data

upload-token

La taille de fichier suggérée pour les images est inférieure à 50 Mo. Les fichiers de plus de 50 Mo sont sujets à des problèmes de performances.

L'API Library de Google Photos prend en charge les importations récapitulatives. 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 pendant 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 de l'autorisation.

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 qui s'affiche pour l'utilisateur.

Le champ de description est limité à 1 000 caractères et ne doit inclure que du texte significatif créé par les utilisateurs. Par exemple, "Notre sortie au parc" ou "Dîner de Noël". N'incluez pas de métadonnées telles que des noms de fichiers, des 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 demande 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 :

POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate
Content-type: application/json
Authorization: Bearer oauth2-token

{
  "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.

{
  "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 Ajouter des enrichissements.

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 de newMediaItemResults indique l'état et inclut le uploadToken de la requête. Un code d'état non nul indique une erreur.

{
  "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 est ajouté, un mediaItem est renvoyé, qui contient ses 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 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 d'être disponible à l'utilisation en tant qu'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 réessayez votre requête. Vous pouvez suivre les 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 en savoir plus, consultez la section Créer des albums.

Les résultats sont toujours renvoyés dans l'ordre dans lequel les jetons d'importation ont été envoyés.

Bonnes pratiques concernant les importations

Les bonnes pratiques et les ressources suivantes vous aideront à améliorer votre efficacité globale lors des importations :

• 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 est épuisé ou que vous êtes limité en débit pour avoir passé trop d'appels trop rapidement. Assurez-vous de ne pas appeler batchCreate 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 de 30s 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û à l'exécution simultanée de plusieurs appels d'écriture (par exemple, batchCreate) pour le même utilisateur. Vérifiez les détails de votre requête et n'effectuez pas d'appels à batchCreate en parallèle.
• 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. Cela est important lorsque vous importez des fichiers à partir d'appareils mobiles clients ou de fichiers volumineux.

Tenez également compte des conseils suivants pour chaque étape du processus d'importation : importation d'octets, puis création d'éléments multimédias.

Importer des octets

• L'importation d'octets (pour récupérer des 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

• Ne passez pas d'appels en parallèle de batchCreate pour un seul utilisateur.

  • Pour chaque utilisateur, effectuez des appels à batchCreate l'un après l'autre (en série).
  • S'il y a plusieurs utilisateurs, effectuez toujours des appels batchCreate pour chaque utilisateur l'un après l'autre. N'effectuez des appels que pour des utilisateurs différents en parallèle.

• Incluez autant de NewMediaItems que possible dans chaque appel à batchCreate pour réduire le nombre total d'appels que vous devez effectuer. Vous ne pouvez inclure au maximum 50 éléments.

• Définissez un texte de description pertinent créé 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 dans le champ de 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 d'importation (importation d'octets bruts et création d'éléments multimédias) et de détailler les bonnes pratiques pour créer une intégration d'importation efficace et résiliente.

É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 à partir de tous vos utilisateurs. Suivez chaque uploadToken renvoyée par utilisateur. N'oubliez pas les points clés suivants:

• Le nombre de threads d'importation simultanés dépend de votre environnement d'exécution.
• Pensez à 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.

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 pour chaque utilisateur à la fois.

// 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.

Poursuivez ce processus jusqu'à ce que toutes les importations et les appels de création de contenu multimédia soient terminés.