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
.
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:
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.
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
.