Permisos de autorización obligatorios
Para mostrar contenido creado por la app, se requiere el permiso photoslibrary.readonly.appcreateddata. Para obtener más información sobre los permisos, consulta Permisos de autorización.
Descripción general
La API de la Biblioteca te permite enumerar los elementos multimedia que creó tu aplicación y acceder a ellos.
Estas son algunas de las funciones clave de las fichas de elementos multimedia:
- Enumera elementos multimedia de álbumes específicos creados por la app o de toda la biblioteca creada por la app
Aplica filtros (fecha, categoría de contenido, tipo de medio) cuando generes listas para acotar los resultados.
Recupera objetos
mediaItemcon detalles esenciales, como vínculos directos y metadatos.
Si enumeras el contenido de la biblioteca y del álbum, se muestra una lista de elementos multimedia.
No se incluyen los enriquecimientos que forman parte de un álbum. Los elementos multimedia describen una foto, un video o algún otro contenido multimedia. Un mediaItem incluye un vínculo directo al elemento, un vínculo al elemento en Google Fotos y otros metadatos relevantes. Para obtener más información, consulta Cómo acceder a elementos multimedia y mediaItems.
Cómo mostrar una lista de álbumes creados por la app
Puedes generar una lista de los álbumes que creó tu app con albums.list.
REST
A continuación, se muestra una solicitud de ejemplo:
GET https://photoslibrary.googleapis.com/v1/albums
La solicitud muestra el siguiente resultado:
{
"albums": [
{
"id": "album-id",
"title": "album-title",
"productUrl": "album-product-url",
"coverPhotoBaseUrl": "album-cover-base-url_do-not-use-directly",
"coverPhotoMediaItemId": "album-cover-media-item-id",
"isWriteable": "whether-you-can-write-to-this-album",
"mediaItemsCount": "number-of-media-items-in-album"
},
...
],
"nextPageToken": "token-for-pagination"
}Cada álbum que se muestra tiene un ID que se puede usar para recuperar el contenido del álbum, como se muestra en Cómo mostrar el contenido de un álbum. También incluye el título y la cantidad de elementos multimedia que contiene.
El productUrl apunta al álbum de Google Fotos que el usuario puede abrir.
coverPhotoMediaItemId contiene el ID del elemento de media que representa la foto de portada de este álbum. Para acceder a esta imagen de portada, usa coverPhotoBaseUrl.
No debes usar coverPhotoBaseUrl directamente sin especificar parámetros adicionales.
La respuesta también contiene un nextPageToken. Para obtener más información, consulta Paginación.
La respuesta de los álbumes vacíos varía en que mediaItemsCount y coverPhotoMediaItemId se establecen en 0 de forma predeterminada y se omiten de la respuesta de REST. También ten en cuenta que coverPhotoBaseUrl apunta a una imagen de marcador de posición predeterminada.
Enumera el contenido de la biblioteca creado por la app
Puedes enumerar todos los elementos multimedia de la biblioteca de Google Fotos del usuario que se crearon con tu app. Esto excluye los elementos archivados y borrados. Puedes aplicar filtros para mostrar elementos multimedia según su contenido, fecha y otras propiedades.
Para enumerar los elementos multimedia, llama a mediaItems.list.
REST
A continuación, se muestra una solicitud de ejemplo:
GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
"pageSize": "100",
}La solicitud GET muestra la siguiente respuesta:
{
"mediaItems": [
...
],
"nextPageToken": "token-for-pagination"
}La respuesta contiene una lista de elementos multimedia, ordenados de los más recientes a los menos recientes.
Para obtener más información, consulta mediaItems También contiene un nextPageToken, que se describe con más detalle en Paginación.
Cómo mostrar el contenido de un álbum
Para enumerar todos los elementos multimedia de un álbum, agrega el campo albumId a tu solicitud de búsqueda. Para obtener más información sobre albumId, consulta Cómo mostrar álbumes. Si el albumId no es válido, se muestra un error Bad Request. Si el ID es válido, pero el álbum no existe para el usuario autenticado, se muestra un error Not Found. Para obtener más detalles sobre el manejo de errores, consulta Sugerencias de rendimiento y Prácticas recomendadas.
REST
A continuación, se muestra una solicitud de ejemplo:
POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
"pageSize": "100",
"albumId": "album-id"
}La solicitud POST muestra la siguiente respuesta:
{
"mediaItems": [
...
],
"nextPageToken": "token-for-pagination"
}La respuesta contiene una nextPageToken y la lista de elementos multimedia. A diferencia de lo que sucede cuando se enumera el contenido de la biblioteca, los elementos multimedia se muestran según su orden en el álbum. Para obtener más información, consulta mediaItems y Paginación. El usuario puede editar el pedido en la interfaz de Google Fotos.
Si se establece albumId, no podrás aplicar un filtro cuando enumeres el contenido de los álbumes.
Si lo haces, se generará un error Bad Request.
Paginación para REST
Para mejorar el rendimiento, los métodos que muestran una gran cantidad de resultados (como los métodos de lista) pueden paginar la respuesta. El parámetro pageSize proporciona la cantidad máxima de resultados en cada página.
Para las llamadas a mediaItems.search y mediaItems.list, el tamaño de página predeterminado es de 25 elementos. Recomendamos este tamaño de página porque logra un equilibrio entre el tamaño de la respuesta y la tasa de relleno. El tamaño máximo de las páginas para las solicitudes de búsqueda y lista de elementos multimedia es de 100 elementos.
El tamaño de página predeterminado y recomendado cuando se muestran los álbumes es de 20, con un máximo de 50.
Cuando la cantidad de resultados disponibles es mayor que el tamaño de la página, la respuesta incluye un nextPageToken, que le indica a tu aplicación que hay más resultados para recuperar del servidor.
Ejemplo
Debes agregar el nextPageToken a las solicitudes posteriores en el parámetro pageToken, como se muestra en el siguiente ejemplo. Especifica pageToken junto con los otros parámetros necesarios para la operación, ya sea en el cuerpo de la solicitud o como un parámetro de consulta.
Solicitud 1
{
"pageSize": "5",
"filters": { … }
}Respuesta n° 1
{
"mediaItem": [ … ],
"nextPageToken": "next-page-token"
}Solicitud n° 2
{
"pageSize": "5",
"filters": { … },
"pageToken": "page-token"
}Respuesta n° 2
{
"mediaItem": [ … ],
"nextPageToken": "next-page-token"
}Continúa este patrón hasta que no queden más objetos nextPageToken.
El nextPageToken solo es válido para la misma solicitud. Si se cambia alguno de los parámetros, no se debe usar un nextPageToken que se haya usado anteriormente en la misma solicitud.