Elencare album e elementi multimediali creati dall'app

Ambiti di autorizzazione obbligatori

Per mostrare i contenuti creati dall'app è necessario photoslibrary.readonly.appcreateddata l'ambito di attività. Per ulteriori informazioni sugli ambiti, consulta Autorizzazione ambiti.

Panoramica

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

Ecco alcune funzionalità chiave dell'elenco degli elementi multimediali:

• Elencare elementi multimediali da album specifici creati dall'app o dall'intera app libreria

• Applica filtri (data, categoria di contenuti, contenuti multimediali tipo) quando utilizzi la scheda per restringere risultati

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

L'elenco della raccolta e dei contenuti dell'album restituisce un elenco di elementi multimediali. Arricchimenti che fanno parte di un album non sono incluse. Gli elementi multimediali descrivono una foto, un video o altri contenuti multimediali. R mediaItem include un link diretto all'elemento, un link all'elemento in Google Foto e altri metadati pertinenti. Per ulteriori informazioni, vedi 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 del album come mostrato in Elenca i contenuti dell'album. Inoltre, include il titolo e il numero di elementi multimediali al suo interno.

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

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

La risposta contiene anche un nextPageToken. Per ulteriori informazioni, vedi Impaginazione.

La risposta per gli album vuoti varia in questo senso: mediaItemsCount e I coverPhotoMediaItemId sono impostati su 0 per impostazione predefinita e vengono omessi dal REST risposta. Tieni inoltre presente che coverPhotoBaseUrl rimanda a un segnaposto predefinito dell'immagine.

Elencare i contenuti della raccolta creata dall'app

Puoi elencare tutti gli elementi multimediali dalla 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 i 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 ulteriori 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 a richiesta di ricerca. Per ulteriori informazioni su albumId, consulta la sezione Scheda album. Se albumId non è valido, viene restituito un errore Bad Request. Se l'ID è valido, ma l'album non esiste per l'utente autenticato utente, viene restituito un errore Not Found. Per ulteriori dettagli sull'errore e la gestione dei contenuti,vedi 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 nextPageToken e l'elenco di elementi multimediali. A differenza di quanto avviene quando si elencano i contenuti della raccolta, gli elementi multimediali vengono restituiti in base all'ordine nell'album. Per ulteriori dettagli, vedi mediaItems e Impaginazione. L'utente può modificare l'ordine nell'interfaccia di Google Foto.

Se il albumId è impostato, non puoi applicare un filtro quando elenchi i contenuti dell'album. In questo modo viene visualizzato un errore di tipo Bad Request.

Impaginazione per REST

Per migliorare le prestazioni, i metodi che restituiscono un numero elevato di risultati (come ) possono impaginare la risposta. Il numero massimo di risultati in ogni pagina viene fornita dal parametro pageSize.

Per le chiamate a mediaItems.search e mediaItems.list, le dimensioni di pagina predefinite sono di 25 elementi. Consigliamo questo formato di pagina perché trova un equilibrio tra la dimensione 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.

Il numero predefinito e consigliato di album da elencare è 20, con un massimo di 50 album.

Quando il numero di risultati disponibili è superiore alle dimensioni della pagina, la risposta include un nextPageToken, che indica all'applicazione che ci sono altri 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 schema finché non ci sono più oggetti nextPageToken.

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