Elenco contenuti, album ed elementi multimediali della raccolta

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.

Attenzione: non memorizzare nella cache le foto e i video degli utenti. Archivia invece l'elemento multimediale id e richiedi di nuovo i dettagli quando ne avrai bisogno. Le immagini potrebbero cambiare e l'accesso diretto tramite baseUrl scade dopo 60 minuti. Per ulteriori informazioni, consulta Accedere agli elementi multimediali.

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:

• albums.list
• sharedAlbums.list

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.

Nota: il parametro pageSize ha raggiunto il limite massimo: potrebbero essere restituiti meno risultati di quelli richiesti.

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.

Nota: l'esistenza di nextPageToken è l'unico indicatore che indica se sono presenti altri risultati da recuperare dal server. Non contare il numero di risultati per stabilire se usare o meno nextPageToken. Una richiesta potrebbe restituire meno risultati di quelli richiesti nelle dimensioni della pagina. Se è presente un nextPageToken, puoi inviare una richiesta per ricevere più risultati dopo la tua richiesta iniziale.