Permisos de autorización obligatorios
La API de la Biblioteca de Google Fotos contiene varios permisos que se usan para acceder a elementos multimedia y álbumes. Los elementos multimedia que se muestran de varias llamadas difieren según los alcances que el desarrollador haya solicitado.
El permiso photoslibrary.readonly
permite acceder a todos los elementos multimedia del
biblioteca del usuario. El permiso photoslibrary.readonly.appcreateddata
permite el acceso
solo a elementos multimedia creados por la app. Para obtener más información, consulta
Permisos de autorización.
Descripción general
Un uso importante de la API es enumerar los elementos multimedia de los que el usuario creó una copia de seguridad. a Google Fotos. Los elementos de un álbum en particular o de todo el contenido del biblioteca (la vista predeterminada en la app de Google Fotos).
Puedes usar filtros para seleccionar fotos. que coincidan con una fecha, categoría de contenido o tipo de medio específicos cuando enumeras elementos de la biblioteca del usuario. No se admite esta función cuando enumeras elementos de álbumes.
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
Lista de álbumes
Puedes recuperar una lista de los álbumes del usuario mediante 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" }
Java
try { // Make a request to list all albums in the user's library // Iterate over all the albums in this list // Pagination is handled automatically ListAlbumsPagedResponse response = photosLibraryClient.listAlbums(); for (Album album : response.iterateAll()) { // Get some properties of an album String id = album.getId(); String title = album.getTitle(); String productUrl = album.getProductUrl(); String coverPhotoBaseUrl = album.getCoverPhotoBaseUrl(); // The cover photo media item id field may be empty String coverPhotoMediaItemId = album.getCoverPhotoMediaItemId(); boolean isWritable = album.getIsWriteable(); long mediaItemsCount = album.getMediaItemsCount(); } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all albums in the user's library // Iterate over all the albums in this list // Pagination is handled automatically $response = $photosLibraryClient->listAlbums(); foreach ($response->iterateAllElements() as $album) { // Get some properties of an album $albumId = $album->getId(); $title = $album->getTitle(); $productUrl = $album->getProductUrl(); $coverPhotoBaseUrl = $album->getCoverPhotoBaseUrl(); // The cover photo media item id field may be empty $coverPhotoMediaItemId = $album->getCoverPhotoMediaItemId(); $isWriteable = $album->getIsWriteable(); $totalMediaItems = $album->getTotalMediaItems(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Cada álbum devuelto tiene un ID que se puede usar para recuperar el contenido de la álbum, como se muestra en Cómo enumerar el contenido de los álbumes. 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 foto de portada de este álbum. Para acceder a esta imagen de portada, usa
coverPhotoBaseUrl
No debes usar coverPhotoBaseUrl
directamente sin
especificar la función
parámetros.
Álbumes que se crearon en la cuenta del usuario o que se agregaron a la cuenta del usuario
y que tu app compartió incluyen una propiedad shareInfo
adicional.
Para obtener más detalles, consulta Cómo compartir contenido multimedia.
Los álbumes también pueden tener una marca isWriteable
para indicar si puedes crear contenido multimedia.
elementos del álbum. El valor predeterminado de esta marca es false
si no se muestra. Sí
que dependen del acceso otorgado a tu aplicación, incluidos los siguientes:
- Quién creó el álbum
- Si se comparten o no.
- Qué alcances al usuario ha aprobado.
Esta marca puede cambiar si cambia alguno de estos criterios. Para obtener más detalles, consulta
Crear álbumes El
también contiene un nextPageToken
. Para obtener más información, consulta
Paginación.
La respuesta para los álbumes vacíos varía en función de eso, mediaItemsCount
y
Las coverPhotoMediaItemId
se configuran en 0 de forma predeterminada y se omiten de REST.
respuesta. Además, ten en cuenta que coverPhotoBaseUrl
apunta a un marcador de posición predeterminado.
imagen.
Cómo enumerar el contenido de la biblioteca
Puedes enumerar todos los elementos multimedia desde la biblioteca de Google Fotos del usuario. Excluye los elementos archivados y borrados. Puedes enumerar elementos multimedia según su contenido, fecha y otras propiedades al aplicar filtros. Si el usuario no ha agregado un elemento disponible en la pestaña Uso compartido de su cuenta de Google Fotos en su biblioteca, ese elemento no está incluido en esta lista.
Para recuperar un elemento 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" }
Java
try { // Make a request to list all media items in the user's library // Iterate over all the retrieved media items // Pagination is handled automatically ListMediaItemsPagedResponse response = photosLibraryClient.listMediaItems(); for (MediaItem item : response.iterateAll()) { // Get some properties of a media item String id = item.getId(); String description = item.getDescription(); String mimeType = item.getMimeType(); String productUrl = item.getProductUrl(); String filename = item.getFilename(); } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all media items in the user's library // Iterate over all the retrieved media items // Pagination is handled automatically $response = $photosLibraryClient->listMediaItems(); foreach ($response->iterateAllElements() as $item) { // Get some properties of a media item /* @var $item \Google\Photos\Library\V1\MediaItem */ $id = $item->getId(); $description = $item->getDescription(); $mimeType = $item->getMimeType(); $productUrl = $item->getProductUrl(); $filename = $item->getFilename(); } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
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.
Enumera 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 y Cómo mostrar una lista de álbumes compartidos. Si
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 mostrará un error Not Found
que se devuelven. Para obtener más detalles sobre el manejo de errores,consulta Rendimiento
sugerencias y Las
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" }
Java
try { // Make a request to list all media items in an album // Provide the ID of the album as a parameter in the searchMediaItems call // Iterate over all the retrieved media items SearchMediaItemsPagedResponse response = photosLibraryClient.searchMediaItems(albumId); for (MediaItem item : response.iterateAll()) { // ... } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all media items in an album // Provide the ID of the album as a parameter in the searchMediaItems call // Iterate over all the retrieved media items $response = $photosLibraryClient->searchMediaItems(['albumId' => $albumId]); foreach ($response->iterateAllElements() as $item) { // ... } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
La respuesta contiene una nextPageToken
y la lista de elementos multimedia. A diferencia de cuando
con una lista de contenidos de la biblioteca, los elementos multimedia se devuelven 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
.
Cómo ver una lista de los álbumes compartidos
Puedes recuperar una lista de todos los álbumes que compartió el usuario o que se compartidas con un usuario. Esto es similar a la pestaña Compartir en el App de Google Fotos
Álbumes compartidos que el usuario agregó a su biblioteca de Google Fotos también se devuelven en la llamada listing album. Haz que el siguiente llamada para crear una lista de los álbumes compartidos a través de la API de la Biblioteca:
REST
A continuación, se muestra una solicitud de ejemplo:
GET https://photoslibrary.googleapis.com/v1/sharedAlbums
La solicitud muestra el siguiente resultado:
{ "sharedAlbums": [...] "nextPageToken": "token-for-pagination" }
Java
try { // Make a request to list all albums that have been shared by the user // Iterate over all the albums in this list // Pagination is handled automatically ListSharedAlbumsPagedResponse response = photosLibraryClient.listSharedAlbums(); for (Album album : response.iterateAll()) { // .. } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all albums that have been shared by the user // Iterate over all the albums in this list // Pagination is handled automatically $response = $photosLibraryClient->listSharedAlbums(); foreach ($response->iterateAllElements() as $album) { // ... } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
sharedAlbums
incluye una lista de álbumes. Para obtener más información, consulta
Lista de álbumes: La respuesta también contiene una nextPageToken
.
Para obtener más información, consulta Paginación.
Los álbumes que creó y compartió tu app incluyen un shareInfo
adicional
propiedad. Para obtener más información, consulta Cómo compartir
contenido multimedia.
Cómo mostrar una lista de los álbumes creados por la app
Puedes ver una lista de los álbumes que creó tu app con
excludeNonAppCreatedData
se configuró como true
en las siguientes llamadas:
REST
Esta es una solicitud GET para enumerar todos los álbumes del álbum Biblioteca de Google Fotos creada solo por tu app:
GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true Content-type: application/json Authorization: Bearer oauth2-token
Esta es una solicitud GET para enumerar todos los álbumes compartidos del álbum Biblioteca de Google Fotos creada solo por tu app:
GET https://photoslibrary.googleapis.com/v1/sharedAlbums?excludeNonAppCreatedData=true Content-type: application/json Authorization: Bearer oauth2-token
Java
try { // Make a request to list all albums that have been created by your app boolean excludeNonAppCreatedData = true; // Iterate over all the albums in this list // Pagination is handled automatically ListAlbumsPagedResponse response = photosLibraryClient.listAlbums(excludeNonAppCreatedData); for (Album album : response.iterateAll()) { // .. } } catch (ApiException e) { // Handle error } try { // Make a request to list all shared albums that have been created by your app boolean excludeNonAppCreatedData = true; // Iterate over all the albums in this list // Pagination is handled automatically ListSharedAlbumsPagedResponse response = photosLibraryClient.listSharedAlbums(excludeNonAppCreatedData); for (Album album : response.iterateAll()) { // .. } } catch (ApiException e) { // Handle error }
PHP
try { // Make a request to list all albums that have been created by your app $response = $photosLibraryClient->listAlbums(['excludeNonAppCreatedData' => true]); // Iterate over all the albums in this list // Pagination is handled automatically foreach ($response->iterateAllElements() as $album) { // ... } } catch (\Google\ApiCore\ApiException $e) { // Handle error } try { // Make a request to list all shared albums that have been created by your app $response = $photosLibraryClient->listSharedAlbums(['excludeNonAppCreatedData' => true]); // Iterate over all the albums in this list // Pagination is handled automatically foreach ($response->iterateAllElements() as $album) { // ... } } catch (\Google\ApiCore\ApiException $e) { // Handle error }
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
solicitudes de búsqueda y lista 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 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 queden más objetos nextPageToken
.
El nextPageToken
solo es válido para la misma solicitud. Si algún parámetro se
cambia, no debes usar nextPageToken
ya usado en el mismo
para cada solicitud.