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 des importations. Cette opération renvoie un jeton d'importation qui identifie les octets importés.
  2. Exécutez un appel batchCreate avec le jeton d'importation pour créer un élément multimédia dans le compte Google Photos de l'utilisateur.

La procédure suivante permet d'importer un seul élément multimédia. Si vous importez plusieurs éléments multimédias (très probable pour une application de production), consultez les bonnes pratiques concernant les importations pour améliorer l'efficacité de vos importations.

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 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 appli 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 BMP, GIF, HEIC, ICO, JPG, PNG, TIFF, WEBP et certains fichiers RAW. 200 Mo
Vidéos 3GP, 3G2, ASF, AVI, DIVX, M2T, M2TS, M4V, MKV, MMV, MOD, MOV, MP4, MPG, MTS, TOD et WMV. 20 Go

Étape 1: Importer 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.

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 les plus courants sont 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 forme de chaîne de texte brute est renvoyé en tant que corps de 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 supérieurs à 50 Mo peuvent entraîner 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 scinder 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 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 une simpleMediaItem et une description facultative 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. Par exemple, "Notre voyage au parc" ou "Dîner de vacances". 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 optimiser les performances, réduisez le nombre d'appels à mediaItems.batchCreate en incluant plusieurs éléments multimédias dans un appel. Attendez toujours que la requête précédente soit terminé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:

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 d'un album dépassant 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 enrichissements.

Réponse à la création d'é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 pour la requête. Un code d'état différent de zéro 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 qu'elle a partiellement réussi.

{
  "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 est ajouté avec succès, un message mediaItem contenant ses attributs mediaItemId, productUrl et mediaMetadata est renvoyé. Pour en savoir plus, consultez la section 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 mediaMetadata, qui décrit l'état de traitement du fichier vidéo. Un fichier nouvellement importé renvoie d'abord l'état PROCESSING, avant que son état ne soit défini sur 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 d'envoyer votre requête. Vous pouvez effectuer le suivi des ajouts réussis afin que l'image puisse être insérée à l'emplacement approprié lors de la requête suivante. Pour en savoir plus, consultez la page Créer des albums.

Les résultats sont toujours renvoyés dans le même ordre que celui utilisé pour l'envoi des jetons d'importation.

Bonnes pratiques pour les importations

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

  • Utilisez l'une des bibliothèques clientes compatibles.
  • Suivez les bonnes pratiques en matière de traitement des tentatives et des erreurs, en tenant compte des points suivants :
    • Les erreurs 429 peuvent se produire lorsque votre quota est épuisé ou que votre débit est limité pour effectuer 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 lors des nouvelles tentatives de requêtes.
    • Les erreurs 500 se produisent lorsque le serveur rencontre une erreur. Cela est probablement dû à plusieurs appels en écriture (tels que batchCreate) effectués en même temps pour le même utilisateur. Vérifiez les détails de votre requête et n'effectuez pas d'appels vers batchCreate en parallèle.
  • Utilisez le flux d'importation avec reprise pour renforcer la robustesse de vos importations en cas d'interruption du réseau, en réduisant l'utilisation de la bande passante en permettant de reprendre des importations partiellement terminées. C'est important lorsque vous importez des données 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 : importer des octets, puis créer des éléments multimédias.

Importation d'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 correct 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, effectuez des appels vers batchCreate l'un après l'autre (en série).
    • Pour plusieurs utilisateurs, effectuez toujours des appels batchCreate pour chaque utilisateur l'un après l'autre. 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 passer. Vous ne pouvez pas inclure plus de 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 un pseudo-code pour importer les éléments multimédias de plusieurs utilisateurs. L'objectif est de décrire les deux étapes du processus d'importation (importer des octets bruts et créer des éléments multimédias) et de détailler les bonnes pratiques pour concevoir une intégration d'importation efficace et résiliente.

Étape 1: Importez les octets bruts

Créez d'abord une file d'attente pour importer les octets bruts de vos éléments multimédias provenant de tous vos utilisateurs. Suivez chaque uploadToken renvoyé par utilisateur. N'oubliez pas les points clés suivants:

  • Le nombre de threads d'importation simultanés dépend de votre environnement d'exploitation.
  • Vous pouvez 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éer des éléments multimédias

À l'étape 1, vous pouvez importer en parallèle plusieurs octets de plusieurs utilisateurs. En revanche, à l'étape 2, vous ne pouvez effectuer qu'un seul appel pour chaque utilisateur à la fois.

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'à la fin de toutes les importations et de tous les appels de création de contenus multimédias.