Accéder aux éléments multimédias

Après avoir appelé le répertorier le contenu d'une bibliothèque ou d'un album photo ; au lieu de stocker les éléments multimédias renvoyés, votre application doit stocker Identifiants des éléments multimédias. En effet, le contenu des éléments multimédias changent et, après un certain temps, les URL incluses dans la réponse expirent. La L'ID d'élément multimédia identifie de manière unique un élément multimédia, comme 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 trop longtemps. périodes. Toutefois, selon votre cas d'utilisation, vous pouvez stocker ou stocker en cache l'ID de l'élément multimédia long que nécessaires. Notez également que l'accès aux données sont régies par la confidentialité obligations de chacun.

Champs d'application des autorisations requis

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

  • photoslibrary.readonly autorise l'accès à tous les éléments multimédias dans bibliothèque
  • photoslibrary.readonly.appcreateddata n'autorise l'accès qu'aux éléments multimédias qui ont été créés par l'application

Éléments multimédias

A mediaItem est une représentation d'un contenu multimédia, tel qu'une photo ou une vidéo mise en ligne sur la bibliothèque Google Photos. Il s'agit d'un objet de niveau supérieur dont les propriétés diffèrent en fonction du type de support sous-jacent.

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

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

Lien vers l'image dans Google Photos. Ce lien ne peut pas être ouvert par le développeur, uniquement par l'utilisateur. Les URL renvoient vers un élément multimédia dans la bibliothèque. Si l'URL provient d'une recherche d'album, elle pointe vers l'élément de l'album.

mimeType Type d'élément multimédia permettant d'identifier facilement le type de contenu (par exemple: image/jpg).
filename Nom de fichier de l'élément multimédia présenté à l'utilisateur dans Google Photos (dans la section contenant les informations de l'article).
mediaMetadata Varie en fonction du type de support sous-jacent (par exemple, photo) ou video. Pour réduire la charge utile, des masques de champ peuvent être utilisés.
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é l'accès photoslibrary.sharing.

Contient des informations sur le contributeur qui a ajouté ce contenu multimédia élément. 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 la méthode 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. La les informations supplémentaires dans photo ou video sont basées sur les métadonnées dans le fichier. Tous les établissements peuvent ne pas être présents. ContributorInfo contient des métadonnées pour les éléments d'un album partagé. Ce champ n'est inclus que si répertorier le contenu d'un album partagé dans lequel l'utilisateur a accordé le photoslibrary.sharing champ d'application de l'autorisation.

Si l'élément multimédia est une vidéo, le fichier vidéo doit d'abord être traité. La mediaItem contient un champ status dans mediaMetadata qui décrit le de traitement du fichier vidéo. Un fichier nouvellement importé renvoie videoProcessingStatus avec la valeur PROCESSING avant d'être READY. 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 pour un élément multimédia photo ressemble à ceci. La photo contient des métadonnées pour les éléments de 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 pour un élément multimédia vidéo se présente comme suit : La vidéo 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 en fonction de leurs identifiants, appelez mediaItems.batchGet à l'aide des mediaItemId.

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

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

REST

Voici une demande GET qui montre un accès réussi et échoué à éléments multimédias. Spécifier chaque identifiant d'élément multimédia en tant que nouvel identifiant 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 contenus multimédias. éléments. À l'aide des différentes URL de base, votre application peut télécharger les éléments multimédias ou afficher les éléments multimédias dans votre application. Les URL de base sont des chaînes incluses dans la réponse lorsque vous répertoriez des albums ou accédez à des éléments multimédias. Il s'agit valides pendant 60 minutes et nécessitent des paramètres supplémentaires, car ils ne peuvent pas être utilisés l'adresse IP interne.

Les différentes URL de base sont les suivantes:

  • baseUrl: accédez directement à la photo, à la miniature d'une vidéo ou au téléchargement d'octets de vidéo.
  • coverPhotoBaseUrl: accédez directement à la photo de couverture de l'album.
  • profilePictureBaseUrl: accédez 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

La largeur (w) et la hauteur (h) paramètres.

Pour accéder à un élément multimédia d'une image, tel qu'une photo ou une vignette pour vidéo, vous devez spécifier les dimensions dans lesquelles vous prévoyez de l'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 ne dépasse pas 2 048 pixels, et pas de plus de 1 024 pixels:

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

Description

Paramètre c de recadrage.

Si vous souhaitez recadrer l'image à la largeur et à la hauteur exactes que vous avez spécifiées, concaténez l'URL de base avec les le paramètre -c facultatif ainsi que le paramètre obligatoire Paramètres w et h.

La taille (en pixels) doit être comprise dans la plage [1, 16 383]. Si l'un des la largeur ou la hauteur de l'image dépasse la taille demandée, le l'image est réduite et recadrée (en conservant les proportions).

Exemples :

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

Dans cet exemple, l'application affiche un élément multimédia exactement de 256 pixels de large sur 256 pixels de haut, miniature:

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

Description

Paramètre d de téléchargement.

Si vous voulez télécharger l’image en conservant toutes les métadonnées Exif à l'exception des métadonnées de l'établissement, concaténez l'URL de base avec Paramètre d.

Exemples :

base-url=d

Dans cet exemple, l'application télécharge une image contenant à l'exception des métadonnées de lieu:

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

URL de base de la vidéo

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

Paramètre
dv

Description

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

Le paramètre dv demande une résolution transcodée de la vidéo d'origine. Le paramètre n'est pas compatible avec w et h paramètres.

Quelques secondes peuvent être nécessaires pour que les URL de base des téléchargements de vidéos renvoient des octets. Par défaut, les téléchargements de vidéos utilisent l'encodage H.264. En cas d'échec de l'encodage H.264, le format VP9 est utilisé.

Avant d'utiliser ce paramètre, vérifiez que le paramètre Le champ mediaMetadata.status est READY. Sinon, si votre élément multimédia n'a pas le traitement terminé, il se peut que vous receviez .

Exemples :

base-url=dv

L'exemple suivant vous montre comment télécharger les octets d'un 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 d'image.

Par défaut, toutes les miniatures de vidéos s'affichent en superposition sur la vidéo . Reportez-vous au paramètre -no pour supprimer cette superposition.

Exemples :

Consultez le tableau des URL de base d'images. pour obtenir des exemples.

no

Description

Suppression de la superposition de vignette, paramètre no.

Pour récupérer la miniature d'une vidéo sans superposition d'un bouton de lecture, concaténez l'URL de base avec le caractère no .

Le paramètre no doit être utilisé avec au moins l'une des valeurs suivantes : la paramètres de l'URL de base de l'image.

Exemples :

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

L'exemple suivant présente une miniature de vidéo mesurant exactement 1 280 x 720 pixels de haut et sans bouton de lecture en superposition:

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 des URL de base d'image ou URL de base de vidéo pour les requêtes de photos animées baseUrl.

Paramètre
dv

Description

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

w, h, c et d

Description

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