Ambiti di autorizzazione obbligatori
L'API Raccolta di Google Foto contiene vari ambiti utilizzati per accedere a elementi multimediali e album. Gli elementi multimediali restituiti dalle varie chiamate sono diversi in base agli ambiti che sono state richieste dallo sviluppatore.
L'ambito photoslibrary.readonly
consente di accedere a tutti gli elementi multimediali nel
libreria utente. L'ambito photoslibrary.readonly.appcreateddata
consente l'accesso
solo con gli elementi multimediali creati dall'app. Per ulteriori informazioni, vedi
Ambiti di autorizzazione.
Panoramica
Un uso importante dell'API è l'elenco degli elementi multimediali di cui l'utente ha eseguito il backup su Google Foto. Elementi di un determinato album o dall'intero album 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 funzionalità non è supportata quando elenchi elementi da album.
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 album
Puoi recuperare un elenco degli album dell'utente 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" }
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 del album come mostrato in Elenco dei contenuti dell'album. Inoltre, include il titolo e il numero di elementi multimediali al suo interno.
L'elemento productUrl
rimanda all'album in Google Foto, che può essere un
aperto dall'utente.
coverPhotoMediaItemId
contiene l'elemento multimediale
ID che
rappresenta la foto di copertina dell'album. Per accedere a questa immagine di copertina, utilizza
coverPhotoBaseUrl
. Non devi usare direttamente coverPhotoBaseUrl
senza
specificare ulteriori
parametri.
Album creati nell'account dell'utente o aggiunti alla sua
account e che la tua app ha condiviso includono un'ulteriore proprietà shareInfo
.
Per maggiori dettagli, vedi Condividere contenuti multimediali.
Gli album potrebbero anche avere un flag isWriteable
per indicare se puoi creare contenuti multimediali
elementi dell'album. Per impostazione predefinita, questo flag è false
se non viene restituito. È
dipende dall'accesso concesso alla tua applicazione, tra cui:
- Chi ha creato l'album.
- Se è condivisa o no.
- Quali sono gli ambiti dell'utente è stato approvato.
Il flag può cambiare se uno qualsiasi di questi criteri viene modificato. Per ulteriori dettagli, vedi
Creare album. La
la risposta contiene anche un nextPageToken
. Per ulteriori informazioni, vedi
Impaginazione.
La risposta per gli album vuoti varia in questo senso: mediaItemsCount
e
Per impostazione predefinita, i coverPhotoMediaItemId
sono impostati su 0 e vengono omessi dal REST
la risposta corretta. Tieni inoltre presente che coverPhotoBaseUrl
rimanda a un segnaposto predefinito
dell'immagine.
Elenco dei contenuti della libreria
Puoi elencare tutti gli elementi multimediali dalla raccolta di Google Foto dell'utente. Sono esclusi gli elementi archiviati ed eliminati. Puoi elencare gli elementi multimediali in base ai loro contenuti, date e altre proprietà applicando filtri. Se l'utente non ha aggiunto un elemento disponibile nella scheda Condivisione di Google Foto per libreria, quell'elemento non è incluso in questo elenco.
Per recuperare un elemento multimediale, 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" }
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 ulteriori informazioni, vedi
mediaItems
Inoltre,
contiene un valore nextPageToken
, descritto più dettagliatamente in
Impaginazione.
Elenco dei contenuti dell'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 condivisi e Elenco di 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 visualizzato un errore Not Found
restituito. Per ulteriori dettagli sulla gestione degli errori,consulta Rendimento
suggerimenti e Migliori
pratiche.
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" }
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 nextPageToken
e l'elenco di elementi multimediali. Non mi piace quando
l'elenco dei contenuti della libreria, gli elementi multimediali vengono restituiti in base al loro ordine
dell'album. Per ulteriori dettagli, vedi
mediaItems
e Impaginazione. L'utente può modificare l'ordine nella
Interfaccia di Google Foto.
Se il albumId
è impostato, non puoi applicare un filtro quando elenchi i contenuti degli album.
In questo modo viene visualizzato un errore di tipo 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 nella app Google Foto.
Album condivisi che l'utente ha aggiunto alla propria raccolta di Google Foto vengono restituiti anche nella chiamata album scheda. Fai in modo che seguente chiamata per elencare gli album condivisi tramite l'API Library:
REST
Ecco un esempio di richiesta:
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, vedi
Elenco di album. La risposta contiene anche un nextPageToken
.
Per maggiori informazioni, vedi Impaginazione.
Gli album che l'app ha creato e condiviso includono un ulteriore shareInfo
proprietà. Per ulteriori dettagli, leggi l'articolo Condividere
contenuti multimediali.
Elenco degli album creati dall'app
Puoi elencare gli album creati dalla tua app con
excludeNonAppCreatedData
impostata su true
nelle seguenti chiamate:
REST
Ecco una richiesta GET per elencare tutti gli album dall'account Raccolta di Google Foto creata 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 dall'account Raccolta di Google Foto creata 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
) 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 predefinite della pagina sono
25 elementi. Consigliamo questo formato di pagina perché trova un equilibrio tra
la dimensione della risposta e il tasso di riempimento. Le dimensioni massime della pagina per l'elemento multimediale
richieste di ricerca ed elenco è pari a 100 elementi.
La dimensione di pagina predefinita e consigliata per l'elenco degli album è di 20 album, con un per un massimo di 50 album.
Quando il numero di risultati disponibili supera le dimensioni della pagina, la risposta
include un nextPageToken
, che indica alla tua applicazione che sono presenti
più risultati da recuperare dal server.
Esempio
Devi aggiungere nextPageToken
alle richieste successive nel parametro
pageToken
, come mostrato nell'esempio seguente. Specifica pageToken
insieme
con altri parametri richiesti per l'operazione, nel corpo della
o come parametro di ricerca.
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 esistono parametri
modificata, un valore nextPageToken
utilizzato in precedenza non deve essere utilizzato nello stesso
richiesta.