Ambiti di autorizzazione obbligatori
L'API Libreria Google Foto contiene più ambiti utilizzati per accedere a elementi multimediali e album. Gli elementi multimediali restituiti dalle varie chiamate variano in base agli ambiti richiesti dallo sviluppatore.
L'ambito photoslibrary.readonly
consente l'accesso a tutti gli elementi multimediali nella
raccolta dell'utente. L'ambito photoslibrary.readonly.appcreateddata
consente l'accesso
solo agli elementi multimediali creati dall'app. Per ulteriori informazioni, consulta
Ambiti di autorizzazione.
Panoramica
Un uso importante dell'API consiste nell'elenco degli elementi multimediali di cui l'utente ha eseguito il backup su Google Foto. È possibile elencare gli elementi di un determinato album o dell'intera raccolta dell'utente (la visualizzazione predefinita nell'app Google Foto).
Puoi utilizzare i filtri per selezionare le foto che corrispondono a una data, una categoria di contenuti o un tipo di media specificati quando elenchi elementi dalla raccolta dell'utente. Questa funzione non è supportata quando elenchi elementi dagli album.
L'elenco della raccolta e dei contenuti 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 maggiori informazioni, consulta
Accedere agli elementi multimediali e
mediaItems
.
Elenco degli album
Puoi recuperare un elenco degli album dell'utente utilizzando albums.list.
REST
Ecco una richiesta di esempio:
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" }
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 }
Ogni album restituito ha un ID che può essere utilizzato per recuperare i contenuti dell'album come mostrato nella sezione Elenco dei contenuti dell'album. Sono inclusi anche il titolo e il numero di elementi multimediali che contiene.
L'elemento productUrl
rimanda all'album in Google Foto che può essere aperto dall'utente.
coverPhotoMediaItemId
contiene l'ID elemento multimediale che rappresenta la foto di copertina dell'album. Per accedere a questa immagine di copertina, usa
coverPhotoBaseUrl
. Non devi utilizzare direttamente coverPhotoBaseUrl
senza
specificare parametri
aggiuntivi.
Gli album creati nell'account dell'utente o aggiunti all'account
dell'utente e che la tua app ha condiviso includono un'ulteriore proprietà shareInfo
.
Per maggiori dettagli, vedi Condividere contenuti multimediali.
Gli album possono anche avere un flag isWriteable
per indicare se puoi creare elementi multimediali al loro interno. Se non viene restituito, questo flag è impostato in modo predefinito su false
. Dipende dall'accesso concesso all'applicazione, incluso quanto segue:
- Chi ha creato l'album.
- Se viene condiviso o meno.
- Gli ambiti approvati dall'utente.
Il flag può cambiare se viene modificato uno qualsiasi di questi criteri. Per maggiori dettagli, vedi
Creare album. La risposta contiene anche un nextPageToken
. Per ulteriori informazioni, consulta la sezione Impaginazione.
La risposta per gli album vuoti varia perché, mediaItemsCount
e coverPhotoMediaItemId
sono impostati su 0 per impostazione predefinita e vengono omessi dalla risposta REST. Tieni inoltre presente che coverPhotoBaseUrl
rimanda a un'immagine segnaposto predefinita.
Elenco dei contenuti della raccolta
Puoi elencare tutti gli elementi multimediali della raccolta di Google Foto dell'utente. Esclude gli elementi archiviati ed eliminati. Puoi elencare gli elementi multimediali in base a contenuti, data e altre proprietà applicando filtri. Se l'utente non ha aggiunto alla propria raccolta un elemento disponibile nella scheda Condivisione di Google Foto, quell'elemento non sarà incluso in questo elenco.
Per recuperare un elemento multimediale, chiama mediaItems.list.
REST
Ecco una richiesta di esempio:
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" }
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 risposta contiene un elenco di elementi multimediali, ordinati dal più recente al meno recente.
Per maggiori informazioni, consulta
mediaItems
. Contiene inoltre un elemento nextPageToken
, descritto più dettagliatamente nella sezione Impaginazione.
Elenco dei contenuti dell'album
Per elencare tutti gli elementi multimediali di un album, aggiungi il campo albumId
alla richiesta di ricerca. Per ulteriori informazioni su albumId
, vedi Elenco degli album e Elenco degli album condivisi. 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.
REST
Ecco una richiesta di esempio:
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" }
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 risposta contiene un nextPageToken
e l'elenco di elementi multimediali. A differenza di quanto accade per l'elenco dei contenuti della raccolta, gli elementi multimediali vengono restituiti in base al loro ordine nell'album. Per maggiori dettagli, vedi mediaItems
e Impaginazione. L'utente può modificare l'ordine
nell'interfaccia di Google Foto.
Se albumId
è impostato, non puoi applicare un filtro quando elenchi i contenuti dell'album.
Questo comporta un errore di Bad Request
.
Elenco degli album condivisi
Puoi recuperare un elenco di tutti gli album che l'utente ha condiviso o che sono stati condivisi con un utente. È simile alla scheda Condivisione dell'app Google Foto.
Gli album condivisi che l'utente ha aggiunto alla sua raccolta di Google Foto vengono restituiti anche nella chiamata Aggiungere album alla lista. Effettua la seguente chiamata per elencare gli album condivisi tramite l'API Library:
REST
Ecco una richiesta di esempio:
GET https://photoslibrary.googleapis.com/v1/sharedAlbums
La richiesta restituisce il seguente risultato:
{ "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 }
Un elenco di album è incluso in sharedAlbums
. Per ulteriori informazioni, consulta la sezione Elenco di album. La risposta contiene anche un nextPageToken
.
Per ulteriori informazioni, vedi Impaginazione.
Gli album creati e condivisi dall'app includono un'ulteriore proprietà shareInfo
. Per maggiori dettagli, vedi Condividere contenuti multimediali.
Elenco degli album creati dall'app
Puoi elencare gli album creati dalla tua app con
excludeNonAppCreatedData
impostato su true
nelle seguenti chiamate:
REST
Ecco una richiesta GET per elencare tutti gli album della raccolta Google Foto dell'utente creati solo dalla tua app:
GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true Content-type: application/json Authorization: Bearer oauth2-token
Ecco una richiesta GET per elencare tutti gli album condivisi dalla raccolta Google Foto dell'utente creati solo dalla tua 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 }
Impaginazione per REST
Per migliorare le prestazioni, i metodi che restituiscono un numero elevato di risultati (come
i metodi di elenco) possono impaginare la risposta. Il numero massimo di risultati in ogni pagina è dato dal parametro pageSize
.
Per le chiamate a mediaItems:search
e mediaItems:list
, la dimensione predefinita della pagina è
25 elementi. Consigliamo questa dimensione 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 ed elenco di elementi multimediali è di 100 elementi.
Le dimensioni di pagina predefinite e consigliate per un elenco di album sono di 20 album, con un massimo di 50 album.
Quando il numero di risultati disponibili è maggiore delle dimensioni 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 oggetti nextPageToken
.
nextPageToken
è valido solo per la stessa richiesta. Se vengono modificati dei parametri, un elemento nextPageToken
utilizzato in precedenza non deve essere utilizzato nella stessa richiesta.