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 alcances, consulta Autorización
permisos.
Descripción general
La API de la Biblioteca te permite enumerar y acceder a los elementos multimedia que tu aplicación .
Algunas funciones clave de la lista de elementos multimedia son las siguientes:
- Enumera elementos multimedia de álbumes creados en una app específicos o de toda la app creada biblioteca
Aplica filtros (fecha, categoría de contenido, medios). tipo) cuando se publican para limitar la resultados
Recupera objetos
mediaItemcon detalles esenciales, como vínculos directos y metadatos.
Cuando se enumera el contenido de la biblioteca y el álbum, se muestra una lista de elementos multimedia.
Enriquecimientos que son parte de un álbum
no están incluidas. Los elementos multimedia describen una foto, un video o algún otro contenido multimedia. R
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
Acceder a elementos multimedia y
mediaItems
Cómo mostrar una lista de álbumes creados por la app
Puedes ver 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 devuelto tiene un ID que se puede usar para recuperar el contenido de la álbum, como se muestra en el artículo Enumerar el contenido del álbum. También incluye el título y el número de elementos multimedia que contiene.
La productUrl apunta al álbum en Google Fotos que puede ser una
abierto por el usuario.
coverPhotoMediaItemId contiene el elemento multimedia.
ID que representa la portada
foto de este álbum. Para acceder a esta imagen de portada, usa coverPhotoBaseUrl.
No debes usar coverPhotoBaseUrl directamente sin especificarlo.
parámetros adicionales.
La respuesta también contiene una 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.
Cómo enumerar el contenido de la biblioteca creado por la app
Puedes enumerar todos los elementos multimedia de la biblioteca de Google Fotos del usuario que creó tu app. Esto excluye los elementos archivados y borrados. Tú puedes enumerar elementos multimedia según su contenido, fecha y otras propiedades aplicar filtros.
Para mostrar un elemento multimedia, llama
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 del más al menos reciente.
Para obtener más información, consulta mediaItems También
contiene un nextPageToken, que se describe con más detalle en
Paginación.
Mostrar el contenido del álbum
Para enumerar todos los elementos multimedia de un álbum, agrega el campo albumId a tu
para cada solicitud de búsqueda. Para obtener más información sobre albumId, consulta Fichas
álbumes. Si el albumId no es válido, se produce un error Bad Request.
que se devuelven. Si el ID es válido, pero no existe el álbum para la persona autenticada
usuario, se muestra un error Not Found. Para obtener más información sobre el error
consulta las 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 un 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 detalles, consulta
mediaItems y
Paginación. El usuario puede editar el pedido en la
Interfaz de Google Fotos.
Si estableces albumId, no podrás aplicar un filtro cuando enumeres el contenido de un álbum.
Si lo haces, se generará un error Bad Request.
Paginación para REST
Para mejorar el rendimiento, los métodos que devuelven una gran cantidad de resultados (como
list) puede paginar la respuesta. El número máximo de resultados en cada
página se proporciona con el parámetro pageSize.
Para las llamadas a mediaItems.search y mediaItems.list, el tamaño predeterminado de la página es el siguiente:
25 elementos. Recomendamos este tamaño de página porque tiene un equilibrio entre las
el tamaño de la respuesta y la tasa de relleno. El tamaño máximo de la página para un elemento multimedia
de solicitudes de búsqueda y listas
es de 100 elementos.
El tamaño de página predeterminado y recomendado cuando se enumeran álbumes es de 20, con un un máximo de 50 álbumes.
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
que se puedan 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 en conjunto
con otros parámetros necesarios para la operación, ya sea en el cuerpo del
solicitud, o como un parámetro de consulta.
Solicitud n.° 1
{
"pageSize": "5",
"filters": { … }
}
Respuesta no 1
{
"mediaItem": [ … ],
"nextPageToken": "next-page-token"
}
Solicitud 2
{
"pageSize": "5",
"filters": { … },
"pageToken": "page-token"
}
Respuesta n.o 2
{
"mediaItem": [ … ],
"nextPageToken": "next-page-token"
}
Continúa este patrón hasta que no haya 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.