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

Permisos de autorización necesarios

La API de la Biblioteca de Google Fotos contiene varios alcances que se usan para acceder a elementos multimedia y álbumes. Los elementos multimedia que muestran varias llamadas son diferentes según los alcances que haya solicitado el desarrollador.

El permiso photoslibrary.readonly permite el acceso a todos los elementos multimedia de la biblioteca del usuario. El permiso photoslibrary.readonly.appcreateddata permite acceder solo a los elementos multimedia que creó 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 que el usuario creó en una copia de seguridad en Google Fotos. Se pueden mostrar los elementos de un álbum en particular o de toda la biblioteca del usuario (la vista predeterminada en la app de Google Fotos).

Puedes usar filtros para seleccionar fotos que coincidan con una fecha, una categoría de contenido o un tipo de medio especificados cuando enumeras elementos de la biblioteca del usuario. Esta función no es compatible cuando enumeras elementos de álbumes.

Cuando se muestra el contenido del álbum y la biblioteca, se muestra una lista de elementos multimedia. No se incluyen los enriquecimientos que son parte de un álbum. Los elementos multimedia describen una foto, un video u 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 los elementos multimedia y mediaItems.

Precaución: No almacenes en caché las fotos y los videos de los usuarios. En su lugar, almacena el elemento multimedia id y vuelve a solicitar su información cuando lo necesites. Las imágenes pueden cambiar y el acceso directo a través de baseUrl vence después de 60 minutos. Para obtener más información, consulta Cómo acceder a elementos multimedia.

Enumera á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 mostrado tiene un ID que se puede usar para recuperar el contenido del álbum como se muestra en Enumera el contenido del álbum. También incluye el título y la cantidad de elementos multimedia que contiene.

La productUrl apunta al álbum en Google Fotos que el usuario puede abrir.

coverPhotoMediaItemId contiene el ID de elemento multimedia que representa la foto de portada de este álbum. Para acceder a esta imagen de portada, usa coverPhotoBaseUrl. No debes usar el coverPhotoBaseUrl directamente sin especificar parámetros adicionales.

Los álbumes que se crearon en la cuenta del usuario o que se agregaron a la cuenta del usuario y que la app compartió incluyen una propiedad shareInfo adicional. Para obtener más detalles, consulta Compartir contenido multimedia.

Los álbumes también pueden tener una marca isWriteable para indicar si puedes crear elementos multimedia en el álbum. Esta marca predeterminada es false si no se muestra. Depende del acceso otorgado a tu aplicación, incluidos los siguientes:

• Quién creó el álbum
• Si se comparte o no.
• Los alcances que aprobó el usuario.

Esta marca puede cambiar si cambia alguno de estos criterios. Para obtener más información, consulta Crea álbumes. La respuesta también contiene un nextPageToken. Para obtener más información, consulta Paginación.

La respuesta para los álbumes vacíos varía en que mediaItemsCount y coverPhotoMediaItemId se establecen en 0 de forma predeterminada y se omiten en la respuesta de REST. Además, ten en cuenta que coverPhotoBaseUrl apunta a una imagen de marcador de posición predeterminada.

Enumera el contenido de la biblioteca

Puedes enumerar todos los elementos multimedia de la biblioteca de Google Fotos del usuario. Excluye los elementos archivados y borrados. Puedes enumerar los elementos multimedia según su contenido, fecha y otras propiedades si aplicas filtros. Si el usuario no agregó a la biblioteca un elemento disponible en la pestaña Compartir de Google Fotos, ese elemento no se incluye en la 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, ordenadas de mayor a menor. 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 solicitud de búsqueda. Para obtener más información sobre albumId, consulta Enumera álbumes y Enumera á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 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"
}

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 un nextPageToken y la lista de elementos multimedia. A diferencia de lo que ocurre cuando se enumera el contenido de la biblioteca, los elementos multimedia se muestran por 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 los contenidos del álbum. Si lo haces, se producirá un error Bad Request.

Enumera los álbumes compartidos

Puedes recuperar una lista de todos los álbumes que el usuario compartió o que se compartieron con él. Esto es similar a la pestaña Compartir en la app de Google Fotos.

Los álbumes compartidos que el usuario haya agregado a su biblioteca de Google Fotos también se mostrarán en la llamada de álbumes en la lista. Realiza la siguiente llamada para enumerar 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
}

Se incluye una lista de álbumes en sharedAlbums. Para obtener más información, consulta Enumera álbumes. La respuesta también contiene un nextPageToken. Para obtener más información, consulta Paginación.

Los álbumes que tu app creó y compartió incluyen una propiedad shareInfo adicional. Para obtener más detalles, consulta Compartir contenido multimedia.

Enumera los álbumes que se crearon en la app

Puedes enumerar los álbumes que haya creado tu app con excludeNonAppCreatedData configurado como true en las siguientes llamadas:

• albums.list
• sharedAlbums.list

REST

Esta es una solicitud GET para mostrar todos los álbumes de la biblioteca de Google Fotos del usuario creados solo por tu app:

GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

A continuación, se muestra una solicitud GET para mostrar todos los álbumes compartidos de la biblioteca de Google Fotos del usuario 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 de 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. La cantidad máxima de resultados en cada página se proporciona mediante el parámetro pageSize.

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 de página máximo para las solicitudes de lista y búsqueda de elementos multimedia es de 100 elementos.

El tamaño de página predeterminado y recomendado para la enumeración de álbumes es de 20 álbumes, con 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 indica a la aplicación que hay más resultados para recuperar del servidor.

Nota: El parámetro pageSize es un máximo; se pueden mostrar menos resultados de los que se solicitan.

Ejemplo

Debes agregar nextPageToken a las solicitudes posteriores en el parámetro pageToken, como se muestra en el siguiente ejemplo. Especifica el pageToken junto con otros parámetros necesarios para la operación, ya sea en el cuerpo de la solicitud o como un parámetro de consulta.

Solicitud n.o 1

{
  "pageSize": "5",
  "filters": { … }
}

Respuesta n.o 1

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

Solicitud n.o 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.

nextPageToken solo es válido para la misma solicitud. Si se cambia algún parámetro, no se debería usar un nextPageToken que se haya usado antes en la misma solicitud.

Nota: La existencia de nextPageToken es el único indicador de si hay más resultados para recuperar del servidor. No cuentes el número de resultados para determinar si debes usar tu nextPageToken. Una solicitud puede mostrar menos resultados de los solicitados en el tamaño de la página. Si hay un nextPageToken presente, puedes enviar una solicitud para obtener más resultados después de la solicitud inicial.