Accéder aux éléments multimédias

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Après avoir effectué des appels pour répertorier le contenu d'un album ou d'une bibliothèque de photos, au lieu de stocker les éléments multimédias renvoyés, votre application doit stocker les ID des éléments multimédias. En effet, le contenu des éléments multimédias peut changer et, après un certain temps, les URL incluses dans la réponse expirent. L'ID d'élément multimédia identifie de manière unique un élément multimédia, tel qu'une photo ou une vidéo dans la bibliothèque d'un utilisateur.

Notez que votre application ne doit pas mettre en cache la photo ou la vidéo d'un utilisateur pendant de longues périodes, mais, en fonction de votre cas d'utilisation, vous pouvez stocker ou mettre en cache l'ID d'élément multimédia aussi longtemps que nécessaire. Notez également que l'accès aux données utilisateur est régi par des obligations de confidentialité.

Champs d'application des autorisations requis

Pour accéder aux éléments multimédias, votre application doit demander au moins l'un des champs d'application des autorisations suivants. L'accès aux éléments multimédias renvoyés dans la réponse dépend des champs d'application demandés.

  • photoslibrary.readonly permet d'accéder à tous les éléments multimédias de la bibliothèque de l'utilisateur
  • photoslibrary.readonly.appcreateddata n'autorise l'accès qu'aux éléments multimédias créés par l'application

Éléments multimédias

Un mediaItem est une représentation d'un support tel qu'une photo ou une vidéo qui a été importée dans la bibliothèque Google Photos. Il s'agit d'un objet de niveau supérieur et ses propriétés peuvent varier en fonction du type de support sous-jacent.

Le tableau suivant répertorie les propriétés mediaItem:

Propriétés
id ID permanent stable permettant d'identifier l'objet.
description Description de l'élément multimédia tel qu'il apparaît dans Google Photos.
baseUrl Permet d'accéder aux octets bruts. Pour en savoir plus, consultez URL de base.
productUrl

Lien vers l'image dans Google Photos. Ce lien ne peut pas être ouvert par le développeur, mais uniquement par l'utilisateur. Les URL pointent vers un élément multimédia de la bibliothèque. Si l'URL a été récupérée à partir d'une recherche d'album, elle pointe vers l'élément dans l'album.

mimeType Type d'élément multimédia permettant d'identifier facilement le type de support (par exemple, image/jpg).
filename Nom de fichier de l'élément multimédia présenté à l'utilisateur dans l'application Google Photos (dans la section d'informations de l'élément).
mediaMetadata Varie en fonction du type de support sous-jacent, tel que photo ou video. Pour réduire la charge utile, vous pouvez utiliser des masques de champ.
contributorInfo

Ce champ n'est renseigné que si l'élément multimédia se trouve dans un album partagé créé par cette application et que l'utilisateur a accordé le champ d'application photoslibrary.sharing.

Contient des informations sur le contributeur qui a ajouté cet élément multimédia. Pour en savoir plus, consultez Partager des contenus multimédias.

Obtenir un élément multimédia

Pour récupérer un élément multimédia, appelez mediaItems.get à l'aide de mediaItemId. La requête renvoie un seul élément multimédia.

mediaItem contient des propriétés telles que l'ID, la description et l'URL. Les informations supplémentaires dans photo ou video sont basées sur les métadonnées contenues dans le fichier. Il est possible que certaines propriétés ne soient pas présentes. ContributorInfo contient les métadonnées des éléments faisant partie d'un album partagé. Ce champ n'est inclus que lorsqu'il répertorie le contenu d'un album partagé où l'utilisateur a accordé le champ d'application des autorisations photoslibrary.sharing.

Si l'élément multimédia est une vidéo, le fichier vidéo doit d'abord être traité. mediaItem contient un champ status dans mediaMetadata, qui décrit l'état de traitement du fichier vidéo. Un fichier nouvellement importé renvoie d'abord la valeur videoProcessingStatus avec la valeur PROCESSING, avant qu'il ne soit utilisé pour READY. L'élément baseUrl d'un élément multimédia vidéo n'est pas disponible tant que la vidéo n'a pas été traitée.

REST

Voici une requête GET:

GET https://photoslibrary.googleapis.com/v1/mediaItems/media-item-id
Content-type: application/json
Authorization: Bearer oauth2-token

La réponse à un élément multimédia multimédia se présente comme suit : La propriété "photo" contient des métadonnées pour les éléments photo.

{
  "id": "media-item-id",
  "description": "item-description",
  "productUrl": "url-to-open-in-google-photos",
  "baseUrl": "base-url_do-not-use-directly",
  "mimeType": "mime-type-of-media",
  "filename": "item-filename",
  "mediaMetadata": {
    "width": "media-item-width",
    "height": "media-item-height",
    "creationTime": "media-item-creation-time",
    "photo": {
       "cameraMake": "make-of-the-camera",
       "cameraModel": "model-of-the-camera",
       "focalLength": "focal-length-of-the-camera-lens",
       "apertureFNumber": "aperture-f-number-of-the-camera-lens",
       "isoEquivalent": "iso-of-the-camera",
       "exposureTime": "exposure-time-of-the-camera-aperture"
    }
  },
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
    "displayName": "name-of-user"
  }
}

La réponse à un élément multimédia vidéo se présente comme suit : La propriété "video" contient des métadonnées pour les éléments vidéo.

{
  "id": "media-item-id",
  "description": "item-description",
  "productUrl": "url-to-open-in-google-photos",
  "baseUrl": "base-url_do-not-use-directly",
  "mimeType": "mime-type-of-media",
  "filename": "item-filename",
  "mediaMetadata": {
    "width": "media-item-width",
    "height": "media-item-height",
    "creationTime": "media-item-creation-time",
    "video": {
     "cameraMake": "make-of-the-camera",
     "cameraModel": "model-of-the-camera",
     "fps": "frame-rate-of-the-video",
     "status": "READY"
    },
  },
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_do-not-use-directly",
    "displayName": "name-of-user"
  }
}

Java

La propriété "photo" contient des métadonnées pour les éléments photo.

try {
  // Get a media item using its ID
  String mediaItemId = "...";
  MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
  // Get some properties from the retrieved media item
  String id = item.getId();
  String description = item.getDescription();
  String baseUrl = item.getBaseUrl();
  String productUrl = item.getProductUrl();
  // ...
  if (item.hasMediaMetadata()) {
    // The media item contains additional metadata, such as the height and width
    MediaMetadata metadata = item.getMediaMetadata();
    long height = metadata.getHeight();
    long width = metadata.getWidth();
    Timestamp creationTime = metadata.getCreationTime();
    // ...
    if (metadata.hasPhoto()) {
      // This media item is a photo and has additional photo metadata
      Photo photoMetadata = metadata.getPhoto();
      String cameraMake = photoMetadata.getCameraMake();
      String cameraModel = photoMetadata.getCameraModel();
      float aperture = photoMetadata.getApertureFNumber();
      int isoEquivalent = photoMetadata.getIsoEquivalent();
      // ...
    }
  }
  if (item.hasContributorInfo()) {
    // A user has contributed this media item  to a shared album
    ContributorInfo contributorInfo = item.getContributorInfo();
    String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
    String displayName = contributorInfo.getDisplayName();
  }
} catch (ApiException e) {
  // Handle error
}

La propriété "video" contient des métadonnées pour les éléments vidéo.

try {
  // Get a media item using its ID
  String mediaItemId = "...";
  MediaItem item = photosLibraryClient.getMediaItem(mediaItemId);
  // Get some properties from the retrieved media item
  String id = item.getId();
  String description = item.getDescription();
  String baseUrl = item.getBaseUrl();
  String productUrl = item.getProductUrl();
  // ...
  if (item.hasMediaMetadata()) {
    // The media item contains additional metadata, such as the height and width
    MediaMetadata metadata = item.getMediaMetadata();
    long height = metadata.getHeight();
    long width = metadata.getWidth();
    Timestamp creationTime = metadata.getCreationTime();
    // ...

    if (metadata.hasVideo()) {
      // This media item is a video and has additional video metadata
      Video videoMetadata = metadata.getVideo();
      VideoProcessingStatus status = videoMetadata.getStatus();
      if (status.equals(VideoProcessingStatus.READY)) {
        // This video media item has been processed
        String cameraMake = videoMetadata.getCameraMake();
        String cameraModel = videoMetadata.getCameraModel();
        double fps = videoMetadata.getFps();
        // ...
      }
    }
  }

  if (item.hasContributorInfo()) {
    // A user has contributed this media item  to a shared album
    ContributorInfo contributorInfo = item.getContributorInfo();
    String profilePictureBaseUrl = contributorInfo.getProfilePictureBaseUrl();
    String displayName = contributorInfo.getDisplayName();
  }
} catch (ApiException e) {
  // Handle error
}

PHP

La propriété "photo" contient des métadonnées pour les éléments photo.

try {
    // Get a media item using its ID
    $mediaItemId = "...";
    $item = $photosLibraryClient->getMediaItem($mediaItemId);
    // Get some properties from the retrieved media item
    $id = $item->getId();
    $description = $item->getDescription();
    $baseUrl = $item->getBaseUrl();
    $productUrl = $item->getProductUrl();
    // ...
    $metadata = $item->getMediaMetadata();
    if (!is_null($metadata)) {
        // The media item contains additional metadata, such as the height and width
        $height = $metadata->getHeight();
        $width = $metadata->getWidth();
        $creationTime = $metadata->getCreationTime();
        // ...
        $photoMetadata = $metadata->getPhoto();
        if (!is_null($photoMetadata)) {
            // This media item is a photo and has additional photo metadata
            $cameraMake = $photoMetadata->getCameraMake();
            $cameraModel = $photoMetadata->getCameraModel();
            $aperture = $photoMetadata->getApertureFNumber();
            $isoEquivalent = $photoMetadata->getIsoEquivalent();
            // ...
        }
    }
    $contributorInfo = $item->getContributorInfo();
    if (!is_null($contributorInfo)) {
        // A user has contributed this media item to a shared album
        $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
        $displayName = $contributorInfo->getDisplayName();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

La propriété "video" contient des métadonnées pour les éléments vidéo.

  try {
    // Get a media item using its ID
    $mediaItemId = "...";
    $item = $photosLibraryClient->getMediaItem($mediaItemId);
    // Get some properties from the retrieved media item
    $id = $item->getId();
    $description = $item->getDescription();
    $baseUrl = $item->getBaseUrl();
    $productUrl = $item->getProductUrl();
    // ...
    $metadata = $item->getMediaMetadata();
    if (!is_null($metadata)) {
        // The media item contains additional metadata, such as the height and width
        $height = $metadata->getHeight();
        $width = $metadata->getWidth();
        $creationTime = $metadata->getCreationTime();
        // ...
        $videoMetadata = $metadata->getVideo();
        if (!is_null($videoMetadata)) {
            // This media item is a video and has additional video metadata
            if (VideoProcessingStatus::READY == $videoMetadata->getStatus()) {
            // This video media item has been processed
                $cameraMake = $videoMetadata->getCameraMake();
                $cameraModel = $videoMetadata->getCameraModel();
                $fps = $videoMetadata->getFps();
                // ...
            }
        }
    }
    $contributorInfo = $item->getContributorInfo();
    if (!is_null($contributorInfo)) {
        // A user has contributed this media item to a shared album
        $profilePictureBaseUrl = $contributorInfo->getProfilePictureBaseUrl();
        $displayName = $contributorInfo->getDisplayName();
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

Obtenir plusieurs éléments multimédias

Pour récupérer plusieurs éléments multimédias à l'aide de leurs identifiants, appelez mediaItems.batchGet à l'aide des mediaItemId.

La requête renvoie une liste de MediaItemResults dans l'ordre des identifiants d'éléments multimédias fournis. Chaque résultat contient un MediaItem ou un Status en cas d'erreur.

Vous ne pouvez pas demander plus de 50 éléments multimédias par appel. La liste des éléments multimédias ne doit pas contenir d'identifiants en double et ne peut pas être vide.

REST

Voici une requête GET qui montre l'accès réussi et ayant échoué aux éléments multimédias. Spécifiez chaque identifiant d'élément multimédia en tant que nouveau paramètre de requête mediaItemIds dans la requête:

GET https://photoslibrary.googleapis.com/v1/mediaItems:batchGet?mediaItemIds=media-item-id&mediaItemIds=another-media-item-id&mediaItemIds=incorrect-media-item-id
Content-type: application/json
Authorization: Bearer oauth2-token

La requête GET renvoie la réponse suivante:

{
  "mediaItemResults": [
    {
      "mediaItem": {
        "id": "media-item-id",
        ...
      }
    },
    {
      "mediaItem": {
        "id": "another-media-item-id",
        ...
      }
    },
    {
      "status": {
        "code": 3,
        "message": "Invalid media item ID."
      }
    }
  ]
}

Java

try {
  // List of media item IDs to retrieve
  List<String> mediaItemIds = Arrays
      .asList("MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID");

  // Get a list of media items using their IDs
  BatchGetMediaItemsResponse response = photosLibraryClient
      .batchGetMediaItems(mediaItemIds);

  // Loop over each result
  for (MediaItemResult result : response.getMediaItemResultsList()) {

    // Each MediaItemresult contains a status and a media item
    if (result.hasMediaItem()) {
      // The media item was successfully retrieved, get some properties
      MediaItem item = result.getMediaItem();
      String id = item.getId();
      // ...
    } else {
      // If the media item is not set, an error occurred and the item could not be loaded
      // Check the status and handle the error
      Status status = result.getStatus();
      // ...
    }

  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {

    // List of media item IDs to retrieve
    $mediaItemIds = ["MEDIA_ITEM_ID", "ANOTHER_MEDIA_ITEM_ID", "INCORRECT_MEDIA_ITEM_ID"];

    // Get a list of media items using their IDs
    $response = $photosLibraryClient->batchGetMediaItems($mediaItemIds);

    // Loop over each result
    foreach ($response->getMediaItemResults() as $itemResult) {

        // Each MediaItemresult contains a status and a media item
        $mediaItem = $itemResult->getMediaItem();

        if(!is_null($mediaItem)){
            // The media item was successfully retrieved, get some properties
            $id = $mediaItem->getId();
            // ...
        } else {
            // If the media item is null, an error occurred and the item could not be loaded
        }
    }

} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

URL de base

Les URL de base dans l'API Library de Google Photos vous permettent d'accéder aux octets des éléments multimédias. Avec les différentes URL de base, votre application peut télécharger les éléments multimédias ou les afficher. Les URL de base sont des chaînes qui sont incluses dans la réponse lorsque vous répertoriez des albums ou que vous accédez à des éléments multimédias. Elles sont valides pendant 60 minutes et nécessitent des paramètres supplémentaires, car elles ne peuvent pas être utilisées telles quelles.

Les différentes URL de base sont les suivantes:

  • baseUrl: permet d'accéder directement à la photo ou à la miniature d'une vidéo ou de télécharger des octets de vidéo.
  • coverPhotoBaseUrl: permet d'accéder directement à la photo de couverture de l'album.
  • profilePictureBaseUrl: permet d'accéder directement à la photo de profil du propriétaire d'un mediaItem.

URL de base d'images

Voici la liste des options que vous pouvez utiliser avec les URL de base d'images:

Paramètre
w, h

Description

Les paramètres de largeur, w et de hauteur, h.

Pour accéder à un élément multimédia d'image, tel qu'une photo ou une miniature de vidéo, vous devez spécifier les dimensions que vous prévoyez d'afficher dans votre application (afin que l'image puisse être mise à l'échelle tout en conservant les proportions). Pour ce faire, concaténez l'URL de base avec les dimensions requises, comme indiqué dans les exemples.

Exemples :

base-url=wmax-width-hmax-height

Voici un exemple d'affichage d'un élément multimédia dont la largeur est comprise entre 2 048 pixels et 1 024 pixels:

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

Description

Le paramètre de recadrage c.

Si vous souhaitez recadrer l'image selon la largeur et la hauteur exactes que vous avez spécifiées, concaténez l'URL de base avec les paramètres facultatifs -c et w, et h.

La taille (en pixels) doit être comprise dans la plage [1, 16383]. Si la largeur ou la hauteur de l'image dépasse la taille demandée, l'image est réduite et recadrée (conservée).

Exemples :

base-url=wmax-width-hmax-height-c

Dans cet exemple, l'application affiche un élément multimédia de exactement 256 x 256 pixels de large, tel qu'une vignette:

https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c
d

Description

Le paramètre de téléchargement, d.

Si vous souhaitez télécharger l'image en conservant toutes les métadonnées Exif, à l'exception des métadonnées de localisation, concaténez l'URL de base avec le paramètre d.

Exemples :

base-url=d

Dans cet exemple, l'application télécharge une image avec toutes les métadonnées, à l'exception des métadonnées de localisation:

https://lh3.googleusercontent.com/p/Az....XabC=d

URL de base des vidéos

Voici la liste des options que vous pouvez utiliser avec les URL de base de la vidéo:

Paramètre
dv

Description

Pour accéder aux octets d'une vidéo mediaItem, concaténez l'élément baseUrl avec le paramètre de téléchargement de la vidéo, dv.

Le paramètre dv demande une version transcodée de haute qualité de la vidéo d'origine. Ce paramètre n'est pas compatible avec les paramètres w et h.

Le transfert des URL de base pour le téléchargement de vidéos peut prendre quelques secondes.

Avant d'utiliser ce paramètre, vérifiez que le champ mediaMetadata.status de l'élément multimédia est READY. Sinon, un message d'erreur peut s'afficher si l'élément multimédia n'est pas terminé.

Exemples :

base-url=dv

L'exemple suivant montre comment télécharger les octets d'une vidéo:

https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w, h, c et d

Description

Pour accéder à la miniature de la vidéo, utilisez l'un des paramètres d'URL de base de l'image.

Par défaut, toutes les miniatures de vidéo incluent un bouton de lecture en superposition. Consultez la section concernant le paramètre -no pour supprimer cette superposition.

Exemples :

Pour obtenir des exemples, reportez-vous au tableau des URL de base des images.

no

Description

Le paramètre no de la superposition des vignettes,

Si vous souhaitez récupérer la miniature d'une vidéo sans bouton de lecture en superposition, concaténez l'URL de base avec le paramètre no.

Le paramètre no ne doit pas être utilisé avec au moins un des paramètres d'URL de base d'image.

Exemples :

base-url=wmax-width-hmax-height-no

L'exemple suivant montre une miniature de vidéo d'une largeur de 1 280 x 720 pixels, sans bouton de lecture.

https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

URL de base des photos animées

Les photos animées contiennent à la fois des éléments photo et vidéo. Vous pouvez utiliser des paramètres à partir d'URL de base d'images ou d'URL de base de vidéos pour les requêtes baseUrl de photo animée.

Paramètre
dv

Description

Pour récupérer l'élément vidéo d'un élément multimédia associé à une photo animée, utilisez le paramètre dv comme vous le feriez pour le téléchargement à partir des URL de base de la vidéo.

w, h, c et d

Description

Pour récupérer l'élément photo d'un élément multimédia associé à une photo animée, utilisez le format des URL de base d'images.