Después de realizar llamadas para enumerar el contenido de una biblioteca de fotos o un álbum, en lugar de almacenar los elementos multimedia que se muestran, la aplicación debe almacenar 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, vencen las URLs incluidas en la respuesta. Este identifica de forma exclusiva un elemento multimedia, como una foto o un video, que se encuentra en 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 largos períodos, pero, según tu caso de uso, puedes almacenar o almacenar en caché el ID de elemento multimedia por el tiempo según sea necesario. También debes tener en cuenta que el acceso a los datos del usuario se rige por obligaciones de privacidad.
Alcances de autorización obligatorios
Para acceder a los elementos multimedia, tu app debe solicitar al menos uno de los siguientes permisos de autorización. El acceso a los elementos multimedia que se muestran en la respuesta depende de los alcances que hayas solicitado.
photoslibrary.readonlypermite el acceso a todos los elementos multimedia de la biblioteca del usuario.photoslibrary.readonly.appcreateddatapermite el acceso solo a los elementos multimedia que creó la app.
Elementos multimedia
Un objeto 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 diferir 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 |
Descripción del elemento multimedia como se ve en Google Fotos. |
baseUrl |
Se usa para acceder a los bytes sin procesar. Para obtener más información, consulta URL base. |
productUrl |
Un vínculo a la imagen en Google Fotos El desarrollador no puede abrir este vínculo, sino el usuario. Las URLs apuntan a un elemento multimedia de la biblioteca. Si la URL se recuperó de una búsqueda de álbumes, apunta al elemento dentro del álbum. |
mimeType |
Es el tipo de elemento multimedia que ayuda a identificar con facilidad 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 subyacente del contenido multimedia, como photo o video.
Para reducir la carga útil, se pueden usar máscaras de campo.
|
contributorInfo |
Este campo solo se propaga si el elemento multimedia está en un álbum compartido creado por esta app y si el usuario otorgó el alcance Contiene información sobre el colaborador que agregó este elemento multimedia. Para obtener más detalles, consulta Cómo compartir contenido multimedia. |
Obtener un elemento multimedia
Para recuperar un elemento multimedia, llama a mediaItems.get con el mediaItemId. La solicitud muestra un solo elemento multimedia.
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 dentro del archivo. Es posible que no estén todas las propiedades. ContributorInfo contiene metadatos para los elementos que forman parte de un álbum compartido. Este campo solo se incluye cuando se enumera el contenido de un álbum compartido en el que el usuario otorgó el alcance de autorización photoslibrary.sharing.
Si el elemento multimedia es un video, primero se debe procesar el archivo de video. mediaItem contiene un campo status dentro de mediaMetadata, que describe el estado de procesamiento del archivo de video. Un archivo recién subido muestra videoProcessingStatus con el valor PROCESSING primero, antes de que sea READY para su uso. El baseUrl de un elemento multimedia de video no estará disponible hasta que este se haya procesado.
REST
A continuación, se muestra 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 foto se ve de la siguiente manera: La propiedad de foto contiene metadatos de elementos de fotos.
{
"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 de video contiene metadatos para 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 de foto contiene metadatos de elementos de fotos.
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 foto contiene metadatos de elementos de fotos.
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
}
Obtén varios elementos multimedia
Para recuperar varios elementos multimedia según sus identificadores, llama a mediaItems.batchGet con los mediaItemId.
La solicitud muestra una lista de MediaItemResults en el orden de los identificadores de 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 elementos multimedia no debe contener identificadores duplicados y no puede estar vacía.
REST
Esta es una solicitud GET que muestra el acceso correcto y no exitoso a los elementos multimedia. Especifica cada identificador de elementos 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 dentro de la API de la Biblioteca de Google Fotos te permiten acceder a los bytes de los elementos multimedia. Con las diversas URLs base, tu app puede descargar los elementos multimedia o mostrar los elementos multimedia dentro de ella. Las URLs base son cadenas que se incluyen en la respuesta cuando generas una lista de álbumes o accedes a elementos multimedia. Son válidas durante 60 minutos y requieren parámetros adicionales, ya que no se pueden usar tal como están.
Las distintas URLs base son las siguientes:
baseUrl: Accede directamente a la foto, 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 unmediaItem.
URLs base de imágenes
Esta es la lista de opciones que puedes usar con las URLs base de imágenes:
| Parámetro | |
|---|---|
w, h |
Descripción Los parámetros Para acceder a un elemento multimedia de imagen, como una foto o una miniatura de un video, debes especificar las dimensiones que planeas mostrar en tu aplicación (para que la imagen pueda escalarse a estas 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 A continuación, te mostramos un ejemplo de cómo mostrar un elemento multimedia con un ancho máximo de 2,048 px y una altura máxima de 1,024 px: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
Descripción El parámetro Si quieres recortar la imagen con las dimensiones de ancho y altura exactas que especificaste, concatena la URL base con el parámetro opcional El tamaño (en píxeles) debe estar entre [1, 16383]. Si el ancho o la altura de la imagen exceden el tamaño solicitado, la imagen se reduce y se recorta (manteniendo la relación de aspecto). Ejemplos: base-url=wmax-width-hmax-height-c En este ejemplo, la app muestra un elemento multimedia de 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 de descarga Si deseas descargar la imagen y conservar todos los metadatos EXIF, excepto los de ubicación, concatena la URL base con el parámetro Ejemplos: base-url=d En este ejemplo, la aplicación descarga una imagen con todos los metadatos, excepto los de ubicación: https://lh3.googleusercontent.com/p/Az....XabC=d |
URLs base de videos
Esta es la lista de opciones que puedes usar con las URLs base de videos:
| Parámetro | |
|---|---|
dv |
Descripción Para acceder a los bytes de un El parámetro dv solicita una versión transcodificada y de alta calidad del video original. Este parámetro no es compatible con los parámetros w y h. Las URLs base para descargas de video pueden tardar hasta unos segundos en mostrar bytes. Antes de usar este parámetro, comprueba que el campo 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, utiliza cualquiera de los parámetros de URL base de la imagen. De manera predeterminada, todas las miniaturas de video incluyen una superposición de un botón de 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 Si deseas recuperar la miniatura de un video sin la superposición de un botón de reproducción, concatena la URL base con el parámetro no. El parámetro no debe usarse con al menos uno de los parámetros de URL base de 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 URLs base de imágenes o URLs base de video para solicitudes baseUrl de fotos en movimiento.
| Parámetro | |
|---|---|
dv |
Descripción Para recuperar el elemento de video de un elemento multimedia de foto en movimiento, usa el parámetro |
w, h, c y d |
Descripción Para recuperar el elemento de foto de un elemento multimedia de foto en movimiento, usa el formato para las URLs base de imágenes. |