Cómo mostrar el contenido de la biblioteca, los álbumes y los elementos multimedia

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.