Wyświetlanie listy zawartości biblioteki, albumów i elementów multimedialnych

Wymagane zakresy autoryzacji

Interfejs Google Photos Library API obejmuje wiele zakresów używanych do uzyskiwania dostępu do elementów multimedialnych i albumów. Elementy multimedialne zwracane w ramach różnych wywołań różnią się w zależności od zakresów zażądanych przez programistę.

Zakres photoslibrary.readonly umożliwia dostęp do wszystkich elementów multimedialnych w bibliotece użytkownika. Zakres photoslibrary.readonly.appcreateddata umożliwia dostęp tylko do elementów multimedialnych utworzonych przez aplikację. Więcej informacji znajdziesz w artykule o zakresach autoryzacji.

Przegląd

Interfejs API odgrywa ważną rolę przy wyświetlaniu listy elementów multimedialnych, których kopia zapasowa została utworzona przez użytkownika w Zdjęciach Google. Na liście mogą być elementy z danego albumu lub z całej biblioteki użytkownika (domyślny widok w aplikacji Zdjęcia Google).

Przy wyświetlaniu elementów w bibliotece użytkownika możesz użyć filtrów, aby wybrać zdjęcia, które pasują do określonej daty, kategorii treści lub typu multimediów. Ta funkcja nie jest obsługiwana w przypadku list elementów z albumów.

Wyświetlenie zawartości biblioteki i albumu zwraca listę elementów multimedialnych. Wzbogacenia, które są częścią albumu, nie są uwzględniane. Elementy multimedialne opisują zdjęcia, filmy lub inne multimedia. mediaItem zawiera bezpośredni link do elementu, link do niego w Zdjęciach Google i inne istotne metadane. Więcej informacji znajdziesz w artykułach na temat dostępu do elementów multimedialnych i mediaItems.

Uwaga: nie zapisuj zdjęć i filmów użytkowników w pamięci podręcznej. Zamiast tego zapisz element multimedialny id i w razie potrzeby ponownie poproś o jego szczegóły. Obrazy mogą się zmienić, a bezpośredni dostęp przez baseUrl wygasa po 60 minutach. Więcej informacji znajdziesz w artykule o dostępie do elementów multimedialnych.

Informacje o albumach

Listę albumów użytkownika możesz pobrać za pomocą pliku albums.list.

REST

Oto przykładowe żądanie:

GET https://photoslibrary.googleapis.com/v1/albums

Żądanie zwraca taki wynik:

{
  "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
}

Każdy zwrócony album ma identyfikator, który umożliwia pobranie jego zawartości, tak jak w sekcji Lista zawartości albumu. Obejmuje to też tytuł i liczbę elementów multimedialnych w reklamie.

productUrl wskazuje album w Zdjęciach Google, który użytkownik może otworzyć.

Pole coverPhotoMediaItemId zawiera identyfikator elementu multimedialnego, który reprezentuje zdjęcie na okładkę tego albumu. Aby uzyskać dostęp do zdjęcia okładki, użyj adresu coverPhotoBaseUrl. Nie używaj bezpośrednio parametru coverPhotoBaseUrl bez określenia dodatkowych parametrów.

Albumy utworzone na koncie użytkownika lub dodane do tego konta, które zostały udostępnione przez aplikację, zawierają dodatkową usługę shareInfo. Więcej informacji znajdziesz w artykule Udostępnianie multimediów.

Albumy mogą też zawierać flagę isWriteable, która wskazuje, czy możesz w nim tworzyć elementy multimedialne. Jeśli ta flaga nie zostanie zwrócona, przyjmuje domyślnie wartość false. Zależy to od przyznanych aplikacji dostępu, w tym:

• kto utworzył album,
• czy je udostępniasz.
• Zakresy zatwierdzone przez użytkownika.

Flaga może się zmienić, jeśli któreś z tych kryteriów ulegnie zmianie. Więcej informacji znajdziesz w artykule Tworzenie albumów. Odpowiedź zawiera też nextPageToken. Więcej informacji znajdziesz w sekcji Podział na strony.

Odpowiedź dotycząca pustych albumów różni się tym, że wartości mediaItemsCount i coverPhotoMediaItemId mają domyślnie wartość 0 i są pomijane w odpowiedzi REST. Pamiętaj też, że coverPhotoBaseUrl wskazuje domyślny obraz zastępczy.

Zawartość biblioteki z informacjami o aplikacji

Możesz wyświetlić wszystkie elementy multimedialne z biblioteki Zdjęć Google użytkownika. Nie uwzględnia elementów zarchiwizowanych i usuniętych. Możesz zastosować filtry, by wyświetlić listę elementów multimedialnych na podstawie ich treści, daty i innych właściwości. Jeśli użytkownik nie dodał do biblioteki elementu dostępnego na karcie Udostępnianie w Zdjęciach Google, ten element nie jest widoczny na tej liście.

Aby pobrać element multimedialny, wywołaj metodę mediaItems.list.

REST

Oto przykładowe żądanie:

GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
}

Żądanie GET zwraca następującą odpowiedź:

{
  "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
}

Odpowiedź zawiera listę elementów multimedialnych uporządkowanych od najnowszych do najstarszych. Więcej informacji: mediaItems. Zawiera też element nextPageToken, który został szczegółowo opisany w sekcji Podział.

Wyświetlenie zawartości albumu

Aby wyświetlić wszystkie elementy multimedialne w albumie, dodaj do żądania wyszukiwania pole albumId. Więcej informacji o albumId znajdziesz w sekcjach Lista albumów i Lista albumów udostępnionych. Jeśli albumId jest nieprawidłowy, zwracany jest błąd Bad Request. Jeśli identyfikator jest prawidłowy, ale album nie istnieje w przypadku uwierzytelnionego użytkownika, zostanie zwrócony błąd Not Found. Więcej informacji o obsłudze błędów znajdziesz we wskazówkach dotyczących skuteczności i sprawdzonych metodach.

REST

Oto przykładowe żądanie:

POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
  "pageSize": "100",
  "albumId": "album-id"
}

Żądanie POST zwraca następującą odpowiedź:

{
  "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
}

Odpowiedź zawiera element nextPageToken i listę elementów multimedialnych. W przeciwieństwie do informacji o zawartości biblioteki elementy multimedialne są zwracane według kolejności w albumie. Więcej informacji znajdziesz w sekcjach mediaItems i Podział. Użytkownik może edytować kolejność w interfejsie Zdjęć Google.

Jeśli ustawiona jest wartość albumId, nie można zastosować filtra przy wyświetlaniu zawartości albumu. Spowoduje to wystąpienie błędu Bad Request.

Lista albumów udostępnionych

Możesz pobrać listę wszystkich albumów, które ten użytkownik udostępnił lub które został mu udostępniony. Przypomina to kartę Udostępnianie w aplikacji Zdjęcia Google.

Albumy udostępnione, które użytkownik dodał do biblioteki Zdjęć Google, są też zwracane w wywołaniu albumów. Wykonaj to wywołanie, aby wyświetlić listę albumów udostępnionych za pomocą interfejsu Library API:

REST

Oto przykładowe żądanie:

GET https://photoslibrary.googleapis.com/v1/sharedAlbums

Żądanie zwraca taki wynik:

{
  "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
}

Lista albumów znajduje się w sharedAlbums. Więcej informacji znajdziesz w artykule Lista albumów. Odpowiedź zawiera też nextPageToken. Więcej informacji znajdziesz w sekcji Podział na strony.

Albumy utworzone i udostępnione przez aplikację zawierają dodatkową właściwość shareInfo. Więcej informacji znajdziesz w artykule Udostępnianie multimediów.

Wyświetlanie listy albumów utworzonych przez aplikację

Albumy utworzone przez Twoją aplikację możesz wyświetlić z ustawieniem excludeNonAppCreatedData na true w tych wywołaniach:

• albums.list
• sharedAlbums.list

REST

Oto żądanie GET umożliwiające wyświetlenie listy wszystkich albumów z biblioteki Zdjęć Google użytkownika, które zostały utworzone tylko przez Twoją aplikację:

GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true
Content-type: application/json
Authorization: Bearer oauth2-token

Oto żądanie GET, które tworzy listę wszystkich albumów udostępnionych z biblioteki Zdjęć Google użytkownika, które zostały utworzone tylko przez Twoją aplikację:

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
}

Podział na strony w architekturze REST

Aby zwiększyć wydajność, metody zwracające dużą liczbę wyników (np. metody listy) mogą dzielić odpowiedź na strony. Maksymalna liczba wyników na każdej stronie jest określana przez parametr pageSize.

W przypadku wywołań funkcji mediaItems:search i mediaItems:list domyślny rozmiar strony to 25 elementów. Zalecamy ten rozmiar strony, ponieważ zapewnia on równowagę między rozmiarem odpowiedzi a współczynnikiem wypełnienia. Maksymalny rozmiar strony w przypadku żądań wyszukiwań i list elementów multimedialnych to 100.

Domyślny i zalecany rozmiar strony w przypadku listy albumów to 20 – maksymalnie 50.

Jeśli liczba dostępnych wyników jest większa niż rozmiar strony, w odpowiedzi znajduje się element nextPageToken, który informuje aplikację, że z serwera można pobrać więcej wyników.

Uwaga: parametr pageSize jest wartością maksymalną – może zostać zwróconych mniej wyników, niż jest żądanych.

Przykład

Do kolejnych żądań w parametrze pageToken musisz dołączać nextPageToken, jak pokazano w tym przykładzie. Określ pageToken razem z innymi parametrami wymaganymi do wykonania tej operacji – w treści żądania lub jako parametr zapytania.

Wniosek 1

{
  "pageSize": "5",
  "filters": { … }
}

Odpowiedź 1

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

Wniosek 2

{
  "pageSize": "5",
  "filters": { … },
  "pageToken": "page-token"
}

Odpowiedź 2

{
  "mediaItem": [ … ],
  "nextPageToken": "next-page-token"
}

Kontynuuj ten wzorzec, aż nie będzie więcej obiektów nextPageToken.

Pole nextPageToken jest ważne tylko w przypadku tego samego żądania. Jeśli ulegną zmianie jakieś parametry, nie należy używać w tym samym żądaniu już użytego nextPageToken.

Uwaga: istnienie nextPageToken to jedyny wskaźnik tego, czy serwer ma więcej wyników do pobrania. Nie licz wyników, aby określić, czy należy użyć komponentu nextPageToken. Żądanie może zwrócić mniej wyników niż te określone w rozmiarze strony. Jeśli występuje nextPageToken, po pierwszej prośbie możesz wysłać prośbę o więcej wyników.