Después de realizar llamadas para enumerar el contenido de una biblioteca o un álbum de fotos, en lugar de almacenar los elementos multimedia que se muestran, tu aplicación debe almacenar los IDs de los elementos multimedia. Esto se debe a que el contenido de los elementos multimedia puede cambiar y, después de un tiempo determinado, vencen las URLs incluidas en la respuesta. Este ID identifica de forma única un elemento multimedia, como una foto o un video, dentro de la biblioteca de un usuario.
Permisos de autorización obligatorios
El acceso a los elementos multimedia creados por la app requiere el permiso photoslibrary.readonly.appcreateddata. Para obtener más información sobre los permisos, consulta Permisos de autorización.
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 contenido multimedia 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 URL 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 del álbum, apunta al elemento dentro del álbum. |
mimeType |
Es el tipo de elemento multimedia que ayuda 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 subyacente del contenido multimedia, como photo o video.
Para reducir la carga útil, se pueden usar máscaras de campo.
|
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.
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 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 el video.
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 de un elemento multimedia de foto se ve de la siguiente manera. La propiedad de fotos contiene metadatos para los 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 de 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"
}
}
Cómo obtener varios elementos multimedia
Para recuperar varios elementos multimedia por 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 50. La lista de elementos multimedia no debe contener identificadores duplicados ni estar vacía.
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."
}
}
]
}
URL base
Las URLs de base de las APIs de Google Fotos proporcionan acceso a los bytes sin procesar de los elementos multimedia, lo que permite que tu app los descargue o muestre. Estas URLs se incluyen en las respuestas cuando se enumeran álbumes (API de Library) o se accede a elementos multimedia (APIs de Library y Picker). Recuerda que las URLs base requieren parámetros adicionales para funcionar correctamente.
Para la API de Selector:
Todos los objetos PickedMediaItem.mediaFile incluyen un baseUrl.
Las URLs base permanecen activas durante 60 minutos, pero pueden vencer antes si el usuario revoca los permisos de la app a través de la configuración de su Cuenta de Google.
Para la API de Library:
Las URLs base permanecen activas durante 60 minutos.
Las diferentes URLs base son las siguientes:
baseUrl: Accede directamente a una foto, a la miniatura de un video o descarga los bytes de un video.coverPhotoBaseUrl: Accede directamente a la foto de portada del álbum.profilePictureBaseUrl: Acceder directamente a la foto de perfil del propietario de unmediaItem
URLs base de las imágenes
Esta es la lista de opciones que puedes usar con las URLs de base de las imágenes:
| Parámetro | |
|---|---|
w, h |
Descripción Los parámetros de ancho, 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 se pueda ajustar a esas dimensiones y, al mismo tiempo, se conserve 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 que no tenga más de 2,048 px de ancho ni más de 1,024 px de alto: https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
Descripción El parámetro de recorte, Si deseas recortar la imagen al ancho y la altura exactos que especificaste, concatena la URL base con el parámetro opcional El tamaño (en píxeles) debe estar en el rango [1, 16383]. Si el ancho o la altura de la imagen superan el tamaño solicitado, la imagen se reducirá y se recorta (se mantendrá la relación de aspecto). Ejemplos: base-url=wmax-width-hmax-height-c En este ejemplo, la aplicación muestra un elemento multimedia que mide exactamente 256 px de ancho y 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 de Exif, excepto los metadatos 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 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 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 videos pueden tardar unos segundos en mostrar bytes. Antes de usar este parámetro, verifica 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, usa cualquiera de los parámetros de la URL base de la imagen. De manera predeterminada, todas las miniaturas de videos 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 utilizarse 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 y 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 las URLs de base de imágenes o de las URLs de base de videos para las solicitudes de baseUrl de fotos en movimiento.
| Parámetro | |
|---|---|
dv |
Descripción Para recuperar el elemento de video de un elemento multimedia de una 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 de las URLs de imagen base. |