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. 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 et l'efficacité de vos mises en ligne.

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, vous devez utiliser photoslibrary.appendonly ou photoslibrary.

Vous pouvez également créer des éléments multimédias à l'aide du champ d'application photoslibrary.sharing. À créer des éléments avec le niveau d'accès photoslibrary.sharing, vous devez d'abord créer un et le marquer comme partagé à l'aide de shareAlbum. Vous pouvez ensuite créer des éléments multimédias qui sont partagés dans l'album avec l'utilisateur. Vous ne pouvez pas créer d'éléments directement dans dans la bibliothèque de l'utilisateur ou dans des albums que votre application n'a pas partagés.

Lorsque vous répertoriez des albums, la propriété isWriteable indique si votre a accès à la création de contenu média dans un album spécifique.

Types et tailles de fichiers acceptés

Vous pouvez importer les types de fichiers indiqués dans le tableau ci-dessous.

Étape 1: Importer des octets

Importez des octets vers Google à l'aide de requêtes d'importation. Une demande 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.

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

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

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 suggérée pour les images est inférieure à 50 Mo. Les fichiers de plus de 50 Mo sont sujettes à des problèmes de performances.

L'API Library de Google Photos est compatible avec importations avec reprise. Une instance avec reprise vous permet de diviser un fichier multimédia en plusieurs sections et d'en 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 que fichiers multimédias éléments dans Google Photos à l'aide de jetons d'importation. Jeton d'importation valide pendant un jour après leur création. Un élément multimédia est toujours ajouté bibliothèque. Les éléments multimédias ne peuvent être ajouté aux albums créés par votre application. Pour en savoir plus, consultez 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 une importation spécifié à l'intérieur d'un 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 de texte significatif 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 à mediaItems.batchCreate vous devez effectuer en incluant plusieurs éléments multimédias dans un seul appel. Toujours attendre tant que la requête précédente n'est pas terminée avant d'effectuer un appel ultérieur pour la 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"
      }
    }
   , ...
  ]
}

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
}

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 les album id. Pour en savoir plus, consultez Créer des albums

Chaque album peut contenir jusqu'à 20 000 éléments multimédias. Demandes de création d'éléments multimédias éléments d'un album qui dépassent cette limite échouent.

{
  "albumId": "album-id",
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
   , ...
  ]
}

try {
  // Create new media items in a specific album
  BatchCreateMediaItemsResponse response = photosLibraryClient
      .batchCreateMediaItems(albumId, newItems);
  // Check the response
} catch (ApiException e) {
  // Handle error
}

try {
    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems, ['albumId' => $albumId]);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Vous pouvez également spécifier albumId et albumPosition pour d'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"
  }
}

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
}

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 éléments enrichis

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 .

{
  "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"
      }
    }
  ]
}

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();
    // ...
  }
}

// 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é, un mediaItem contenant les 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, 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 l'état PROCESSING avant de passer à READY. Pour en savoir plus, consultez Accéder aux éléments multimédias

Si vous rencontrez une erreur lors de cet appel, suivez les instructions Bonnes pratiques, puis réessayez d'envoyer votre requête. Vous pouvez effectuer le suivi des ajouts réussis afin de pouvoir insérer l'image. dans l'album à la bonne position lors de la prochaine requête. Pour plus 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é.

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:

• Utilisez l'une des bibliothèques clientes compatibles.
• Suivez les bonnes pratiques en matière de gestion des nouvelles tentatives et des erreurs. en gardant à l'esprit les points suivants: <ph type="x-smartling-placeholder">
  </ph>
  • Des erreurs 429 peuvent se produire lorsque vous avez dépassé votre quota ou votre débit est limité, car vous passez trop d'appels trop rapidement. Assurez-vous que vous n'appelez batchCreate pour le même utilisateur qu'à la a été traitée.
  • Les erreurs 429 nécessitent un délai minimal de 30s avant toute nouvelle tentative. Utilisez un intervalle exponentiel entre les tentatives lors de nouvelles tentatives de 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 (comme batchCreate) 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.
• Utilisez le parcours d'importation avec reprise pour vos importations en cas d'interruption du réseau, ce qui réduit l'utilisation de la bande passante en vous permettant de reprendre des importations partiellement terminées. Ceci est important lorsque vous importez des données à partir d'appareils mobiles clients. lors de l'importation de fichiers volumineux.

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

Importation des octets...

• L'importation d'octets (pour récupérer les jetons d'importation) peut être effectuée en parallèle.
• Vous devez toujours définir 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 (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.

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

• 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 un pseudo-code 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étaillent les bonnes pratiques pour mettre en place un processus d'importation efficace et résilient. l'intégration.

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

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 en parallèle, À l'étape 2, vous ne pouvez effectuer qu'un seul appel à la fois pour chaque utilisateur.

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