Importer l'élément multimédia

L'importation d'éléments multimédias s'effectue en deux étapes :

1. Importez les octets de vos fichiers multimédias sur un serveur Google à l'aide du point de terminaison uploads. Cela 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 comment importer un seul élément multimédia. Si vous importez plusieurs éléments multimédias (ce qui est très probable pour toute application de production), consultez les bonnes pratiques pour les importations afin d'améliorer l'efficacité de vos importations.

Avant de commencer

Niveaux d'accès requis pour les autorisations

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 niveaux d'accès, consultez Niveaux d'accès.

Types et tailles de fichiers acceptés

Vous pouvez importer les types de fichiers listés dans ce tableau.

Étape 1 : Importez des octets

Importez des octets sur 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.

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 susceptibles d'entraîner des problèmes de performances.

L'API Library de Google Photos est compatible avec les importations pouvant être reprises. L'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 de mise en ligne est valable 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 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, ainsi qu'une description facultative qui est affichée à l'utilisateur.

Le champ de description est limité à 1 000 caractères et ne doit contenir que du texte pertinent 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 d'autres textes générés automatiquement.

Pour des performances optimales, 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 que la demande précédente soit traitée 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 de 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 de création d'un é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 newMediaItemResults indique l'état et inclut le uploadToken de la demande. 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é, contenant son mediaItemId, son productUrl et son 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'élément mediaItem contient un élément status dans son élément mediaMetadata qui décrit l'état de traitement du fichier vidéo. Un fichier récemment importé renvoie d'abord l'état PROCESSING avant d'être READY pour utilisation. 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 d'envoyer votre demande. 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 Créer des albums.

Les résultats sont toujours renvoyés dans le même ordre que celui dans lequel les jetons d'importation ont été envoyés.

Bonnes pratiques pour les importations

Les bonnes pratiques et ressources suivantes vous aideront à améliorer l'efficacité globale de vos 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 a été épuisé ou que vous êtes limité en débit pour avoir effectué 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 de réessayer. 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 de plusieurs appels d'écriture (comme batchCreate) pour le même utilisateur en même temps. Vérifiez les détails de votre demande 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 vous permettant de reprendre les importations partiellement effectuées. Cela est important lorsque vous importez des fichiers depuis des appareils mobiles clients ou lorsque vous importez des 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.

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 à batchCreate pour un seul utilisateur.

  • Pour chaque utilisateur, effectuez des appels à batchCreate les uns après les autres (en 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 différents utilisateurs en parallèle.

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

• Définissez un texte descriptif pertinent créé par vos utilisateurs. N'incluez pas de métadonnées telles que des noms de fichiers, des balises programmatiques ou d'autres textes générés automatiquement dans le champ de description.

Exemple de procédure

Cet exemple utilise un 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 les octets bruts

Commencez par créer une file d'attente pour importer les octets bruts des éléments multimédias de tous vos utilisateurs. Suivez chaque uploadToken renvoyé par utilisateur. Voici les points clés à retenir :

• Le nombre de threads d'importation simultanés dépend de votre environnement d'exploitation.
• Réorganisez la file 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 d'un 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 par 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.

Continuez ce processus jusqu'à ce que tous les appels d'importation et de création de contenus multimédias soient terminés.