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
REST
Ecco un esempio di richiesta:
GET https://photoslibrary.googleapis.com/v1/albums
La richiesta restituisce il seguente risultato:
{ "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
.
REST
Ecco un esempio di richiesta:
GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
"pageSize": "100",
}
La richiesta GET restituisce la seguente risposta:
{ "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.
REST
Ecco un esempio di richiesta:
POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
"pageSize": "100",
"albumId": "album-id"
}
La richiesta POST restituisce la seguente risposta:
{ "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.