Cómo acceder a los elementos multimedia

Después de realizar llamadas a enumerar el contenido de una biblioteca de fotos o un álbum en lugar de almacenar los elementos multimedia que se muestran, tu aplicación debe almacenar el Son los ID de los elementos multimedia. Esto se debe a que el contenido de los elementos multimedia puede cambiar y, después de un tiempo determinado, las URLs incluidas en la respuesta vencen. El ID del elemento multimedia identifica de forma única un elemento multimedia, como una foto o un video, dentro de la biblioteca de un usuario.

Ten en cuenta que tu aplicación no debe almacenar en caché la foto o el video de un usuario durante períodos prolongados, pero, según tu caso de uso, puedes almacenar o almacenar en caché el ID del elemento multimedia durante el tiempo que sea necesario. También debes tener en cuenta que el acceso a los datos del usuario se rige por obligaciones de privacidad.

Permisos de autorización obligatorios

Para acceder a los elementos multimedia, tu app debe solicitar al menos una de las siguientes opciones permisos de autorización. El acceso a los elementos multimedia que se muestran en la respuesta depende de los permisos que que solicitaron.

  • photoslibrary.readonly permite el acceso a todos los elementos multimedia de la biblioteca del usuario.
  • photoslibrary.readonly.appcreateddata solo permite el acceso a elementos multimedia que fueron creados por la app

Elementos multimedia

R mediaItem es una representación de contenido multimedia, como una foto o un video que se subió a la biblioteca de Google Fotos. Es un objeto de nivel superior y sus propiedades pueden difieren según el tipo de medio subyacente.

En la siguiente tabla, se enumeran las propiedades de mediaItem:

Propiedades
id Un ID permanente y estable que se usa para identificar el objeto.
description Es la descripción del elemento multimedia tal como se ve en Google Fotos.
baseUrl Se usa para acceder a los bytes sin procesar. Para obtener más información, consulta URLs base.
productUrl

Un vínculo a la imagen en Google Fotos. El desarrollador no puede abrir este vínculo, solo el usuario. Las URLs dirigen a un elemento multimedia en la biblioteca. Si la URL se recuperó de una búsqueda de álbum, apunta al elemento dentro del álbum.

mimeType Es el tipo de elemento multimedia para ayudar a identificar fácilmente el tipo de contenido multimedia. (por ejemplo: image/jpg).
filename Es el nombre de archivo del elemento multimedia que se muestra al usuario en la app de Google Fotos (dentro de la sección de información del elemento).
mediaMetadata Varía según el tipo de medio subyacente, como photo. o video. Para reducir la carga útil, se pueden usar máscaras de campo.
contributorInfo

Este campo solo se completa si el elemento multimedia se encuentra en un álbum compartido que creó esta app y el usuario otorgó el permiso photoslibrary.sharing.

Contiene información sobre el colaborador que agregó este contenido multimedia elemento. Para obtener más detalles, consulta Cómo compartir contenido multimedia.

Cómo obtener un elemento multimedia

Para recuperar un elemento multimedia, llama a mediaItems.get con mediaItemId. La solicitud muestra un solo elemento multimedia.

El mediaItem contiene propiedades, como el ID, la descripción y la URL. La información adicional dentro de photo o video se basa en los metadatos del archivo. Es posible que no estén presentes todas las propiedades. ContributorInfo contiene metadatos para los elementos que forman parte de un álbum compartido. Este campo solo se incluye cuando enumerar el contenido de un álbum compartido en el que el usuario otorgó el permiso photoslibrary.sharing permiso de la autorización.

Si el elemento multimedia es un video, primero se debe procesar el archivo de video. El mediaItem contiene un campo status dentro de mediaMetadata que describe la procesamiento del archivo de video. Un archivo subido recientemente muestra primero el videoProcessingStatus con el valor PROCESSING, antes de que sea READY para su uso. El baseUrl de un elemento multimedia de video no estará disponible hasta que se procese.

REST

Esta es una solicitud GET:

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

La respuesta para un elemento multimedia de fotos se ve de la siguiente manera. La foto contiene metadatos para elementos de foto.

{
  "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 respuesta para un elemento multimedia de video se ve de la siguiente manera. La propiedad video contiene metadatos de los elementos de video.

{
  "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 propiedad photo contiene metadatos para los elementos de foto.

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 propiedad de video contiene metadatos para elementos de video.

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 propiedad de fotos contiene metadatos para los elementos de foto.

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 propiedad de video contiene metadatos para elementos de video.

  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
}

Cómo obtener varios elementos multimedia

Para recuperar varios elementos multimedia por sus identificadores, llama a mediaItems.batchGet con los mediaItemId.

La solicitud devuelve una lista de MediaItemResults según los identificadores de los elementos multimedia proporcionados en la solicitud. Cada resultado contiene un MediaItem o un Status si hubo un error.

La cantidad máxima de elementos multimedia que puedes solicitar en una llamada es de 50. La lista de los elementos multimedia no deben contener identificadores duplicados ni estar vacíos.

REST

Esta es una solicitud GET que muestra el acceso exitoso y no exitoso a los elementos multimedia. Especifica cada identificador de elemento multimedia como un nuevo parámetro de consulta mediaItemIds como parte de la solicitud:

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 solicitud GET muestra la siguiente respuesta:

{
  "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 base

Las URLs base de la API de la Biblioteca de Google Fotos te permiten acceder a los bytes del contenido multimedia elementos. Con las distintas URLs base, tu app puede descargar los elementos multimedia o mostrar los elementos multimedia dentro de tu app. Las URLs base son cadenas que se se incluye en la respuesta cuando enumeras álbumes o accedes a elementos multimedia. Son son válidas por 60 minutos y requieren parámetros adicionales, ya que no se pueden usar como en la nube.

Las diferentes URLs base son las siguientes:

  • baseUrl: Accede directamente a la foto o la miniatura de un video, o descarga los bytes de este.
  • coverPhotoBaseUrl: Accede directamente a la foto de portada del álbum.
  • profilePictureBaseUrl: Accede directamente a la foto de perfil del propietario de una mediaItem

URLs base de imágenes

A continuación, se muestra la lista de opciones que puedes usar con las URL base de imágenes:

Parámetro
w, h

Descripción

Los parámetros de ancho, w, y de altura, h.

Para acceder a un elemento multimedia de imagen, como una foto o una miniatura de un video, debes especificar las dimensiones en las que planeas mostrarlos tu aplicación (para que la imagen se pueda escalar a estos dimensiones y, al mismo tiempo, conservar la relación de aspecto). Para ello, concatena la URL base con las dimensiones requeridas, como se muestra en los ejemplos.

Ejemplos:

base-url=wmax-width-hmax-height

Este es un ejemplo para mostrar un elemento multimedia cuyo ancho no sea Debe ser de 2,048 px y una altura inferior a 1,024 px:

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

Descripción

El parámetro de recorte c.

Si deseas recortar la imagen al ancho y la altura exactos dimensiones que hayas especificado, concatena la URL base con el el parámetro opcional -c junto con el valor Parámetros w y h

El tamaño (en píxeles) debe estar dentro del rango [1, 16383]. Si el ancho o la altura de la imagen superan el tamaño solicitado, la imagen se reduce y se recorta (se mantiene la relación de aspecto).

Ejemplos:

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

En este ejemplo, la aplicación muestra un elemento multimedia que está exactamente 256 px de ancho por 256 px de alto, como una miniatura:

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

Descripción

El parámetro d de descarga.

Si quieres descargar la imagen con todos los metadatos EXIF excepto los metadatos de ubicación, concatena la URL base con el Parámetro d.

Ejemplos:

base-url=d

En este ejemplo, la aplicación descarga una imagen con todos metadatos, excepto los metadatos de ubicación:

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

URL base de video

Esta es la lista de opciones que puedes usar con las URLs base de los videos:

Parámetro
dv

Descripción

Para acceder a los bytes de un video mediaItem, concatena el baseUrl con el video descargado, dv parámetro.

El parámetro dv solicita una versión transcodificada de alta calidad del video original. El parámetro no es compatible con los parámetros w y h.

Las URLs base para las descargas de video pueden tardar unos segundos en mostrar bytes.

Antes de usar este parámetro, verifica que el campo mediaMetadata.status de los elementos multimedia sea READY. De lo contrario, si tu elemento multimedia no terminó de procesarse, es posible que recibas un error.

Ejemplos:

base-url=dv

En el siguiente ejemplo, se muestra cómo descargar los bytes de un video:

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

Descripción

Para acceder a la miniatura del video, usa cualquiera de los parámetros de la URL base de la imagen.

De forma predeterminada, todas las miniaturas de videos incluyen una superposición de una reproducción. . Consulta el parámetro -no para quitar esta superposición.

Ejemplos:

Consulta la tabla de URLs base de imágenes. para ver ejemplos.
no

Descripción

El parámetro no para quitar la superposición de miniaturas.

Si quieres recuperar la miniatura de un video sin la superposición de un botón de reproducción, concatena la URL base con el comando no parámetro.

El parámetro no se debe usar con al menos uno de los parámetros de la URL base de la imagen.

Ejemplos:

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

En el siguiente ejemplo, se muestra una miniatura de video que tiene exactamente 1280 px de ancho por 720 px de alto y no incluye una superposición de botones de reproducción:

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

URLs base de fotos en movimiento

Las fotos en movimiento contienen elementos de fotos y videos. Puedes usar parámetros de ya sea URL base de imágenes o URL base de videos para solicitudes de fotos en movimiento baseUrl.

Parámetro
dv

Descripción

Para recuperar el elemento de video de un elemento multimedia de foto en movimiento, usa el parámetro dv como lo harías para descargar desde las URLs de base de video.
w, h, c y d

Descripción

Para recuperar el elemento de foto de un elemento multimedia de una foto en movimiento, usa el formato para las URL base de imágenes.