Elencare album e elementi multimediali creati dall'app

Ambiti di autorizzazione richiesti

Per elencare i contenuti creati dall'app è necessario lo scopo photoslibrary.readonly.appcreateddata. Per ulteriori informazioni sugli ambiti, consulta Ambiti di autorizzazione.

Panoramica

L'API Library ti consente di elencare e accedere agli elementi multimediali creati dalla tua applicazione.

Ecco alcune funzionalità chiave degli elementi multimediali della scheda:

• Elenca gli elementi multimediali di album creati con l'app specifici o dell'intera raccolta creata con l'app

• Applica i filtri (data, categoria di contenuti, tipo di media) quando inserisci una scheda per restringere i risultati.

• Recupera gli oggetti mediaItem con dettagli essenziali come link diretti e metadati.

L'elenco dei contenuti della raccolta e dell'album restituisce un elenco di elementi multimediali. Gli arricchimenti che fanno parte di un album non sono inclusi. Gli elementi multimediali descrivono una foto, un video o altri contenuti multimediali. Un mediaItem include un link diretto all'elemento, un link all'elemento in Google Foto e altri metadati pertinenti. Per ulteriori informazioni, consulta Accedere agli elementi multimediali e mediaItems.

Elenco di album creati dall'app

Puoi elencare gli album creati dalla tua app utilizzando 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"
}

Ogni album restituito ha un ID che può essere utilizzato per recuperare i contenuti dell'album come mostrato in Elenca i contenuti dell'album. Include anche il titolo e il numero di elementi multimediali che contiene.

productUrl rimanda all'album in Google Foto che può essere aperto dall'utente.

coverPhotoMediaItemId contiene l'ID elemento media che rappresenta la foto di copertina di questo album. Per accedere a questa immagine di copertina, usa coverPhotoBaseUrl. Non devi utilizzare coverPhotoBaseUrl direttamente senza specificare parametri aggiuntivi.

La risposta contiene anche un nextPageToken. Per maggiori informazioni, consulta Impaginazione.

La risposta per gli album vuoti varia in quanto mediaItemsCount e coverPhotoMediaItemId sono impostati su 0 per impostazione predefinita e vengono omessi dalla risposta REST. Tieni inoltre presente che coverPhotoBaseUrl fa riferimento a un'immagine segnaposto predefinita.

Elenca i contenuti della raccolta creati dall'app

Puoi elencare tutti gli elementi multimediali della raccolta di Google Foto dell'utente creati dalla tua app. Sono esclusi gli elementi archiviati ed eliminati. Puoi elencare gli elementi multimediali in base ai contenuti, alla data e ad altre proprietà applicando filtri.

Per elencare gli elementi multimediali, chiama 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 risposta contiene un elenco di elementi multimediali, ordinati dal più recente al meno recente. Per maggiori informazioni, vedi mediaItems. Contiene inoltre un nextPageToken, descritto in modo più dettagliato nella sezione Paginazione.

Elenca contenuti album

Per elencare tutti gli elementi multimediali di un album, aggiungi il campo albumId alla richiesta di ricerca. Per maggiori informazioni su albumId, consulta la sezione Elenco di album. Se albumId non è valido, viene restituito un errore Bad Request. Se l'ID è valido, ma l'album non esiste per l'utente autenticato, viene restituito un errore Not Found. Per maggiori dettagli sulla gestione degli errori, consulta Suggerimenti per il rendimento e Best practice.

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 risposta contiene un nextPageToken e l'elenco degli elementi multimediali. A differenza di quanto accade per i contenuti della raccolta, gli elementi multimediali vengono restituiti nell'album in base al relativo ordine. Per maggiori dettagli, consulta mediaItems e Paginazione. L'utente può modificare l'ordine nell'interfaccia di Google Foto.

Se è impostato albumId, non puoi applicare un filtro quando elenchi i contenuti dell'album. In questo modo si verifica un errore Bad Request.

Impaginazione per REST

Per migliorare le prestazioni, i metodi che restituiscono un numero elevato di risultati (ad esempio i metodi di elenco) possono paginare la risposta. Il numero massimo di risultati in ogni pagina è indicato dal parametro pageSize.

Per le chiamate a mediaItems.search e mediaItems.list, la dimensione predefinita della pagina è 25 elementi. Consigliamo questo formato di pagina perché offre un equilibrio tra le dimensioni della risposta e il tasso di riempimento. La dimensione massima della pagina per le richieste di ricerca e elenco di elementi multimediali è di 100 elementi.

La dimensione pagina predefinita e consigliata per la visualizzazione degli album è 20 album, con un massimo di 50 album.

Quando il numero di risultati disponibili è superiore alla dimensione della pagina, la risposta include un nextPageToken, che indica alla tua applicazione che sono disponibili più risultati da recuperare dal server.

Esempio

Devi aggiungere nextPageToken alle richieste successive nel parametro pageToken, come mostrato nell'esempio seguente. Specifica pageToken insieme agli altri parametri richiesti per l'operazione nel corpo della richiesta o come parametro di query.

Richiesta 1

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

Risposta 1

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

Richiesta 2

{
  "pageSize": "5",
  "filters": { … },
  "pageToken": "page-token"
}

Risposta 2

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

Continua questo pattern finché non ci sono altri nextPageToken oggetti.

nextPageToken è valido solo per la stessa richiesta. Se vengono modificati i parametri, nella stessa richiesta non deve essere utilizzato un valore nextPageToken utilizzato in precedenza.