Enumera elementos multimedia y álbumes creados por la app

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 mediaItem con 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.

GET https://photoslibrary.googleapis.com/v1/albums

{
  "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.

GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
}

{
  "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.

POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
  "albumId": "album-id"
}

{
  "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.