Elenco contenuti, album ed elementi multimediali della raccolta

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

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

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:

• albums.list
• sharedAlbums.list

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.

Nota: il parametro pageSize è un valore massimo. Il numero di risultati potrebbe essere inferiore rispetto a quanto richiesto.

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.

Nota: l'esistenza di nextPageToken è l'unico indicatore che determina se ci sono altri risultati da recuperare dal server. Non contare il numero di per stabilire se devi usare nextPageToken. Una richiesta può restituiscono meno risultati di quelli richiesti nelle dimensioni della pagina. Se nextPageToken è puoi inviare una richiesta per ottenere ulteriori risultati dopo la richiesta iniziale.