必要な認可スコープ
Google Photos Library API には、メディア アイテムとアルバムへのアクセスに使用される複数のスコープが含まれています。さまざまな呼び出しから返されるメディア アイテムは、デベロッパーがリクエストしたスコープによって異なります。
photoslibrary.readonly
スコープを使用すると、ユーザーのライブラリ内のすべてのメディア アイテムにアクセスできます。photoslibrary.readonly.appcreateddata
スコープを使用すると、アプリによって作成されたメディア アイテムにのみアクセスできます。詳しくは、承認スコープをご覧ください。
概要
この API の重要な用途は、ユーザーが Google フォトにバックアップしたメディア アイテムを一覧表示することです。特定のアルバム内のアイテムや、ユーザーのライブラリ全体(Google フォト アプリのデフォルト ビュー)のアイテムを表示できます。
ユーザーのライブラリからアイテムを一覧表示するときに、指定した日付、コンテンツ カテゴリ、メディアタイプに一致するフィルタを使用して写真を選択できます。アルバムのアイテムを一覧表示する場合、この機能はサポートされていません。
ライブラリとアルバムのコンテンツを一覧表示すると、メディア アイテムのリストが返されます。アルバムの一部であるエンリッチメントは含まれません。メディア アイテムは、写真や動画などのメディアを記述します。mediaItem
には、アイテムへの直接リンク、Google フォト内のアイテムへのリンク、その他の関連するメタデータが含まれます。詳しくは、メディア アイテムへのアクセスと mediaItems
をご覧ください。
アルバムの一覧表示
albums.list を使用して、ユーザーのアルバムのリストを取得できます。
REST
以下はリクエストのサンプルです。
GET https://photoslibrary.googleapis.com/v1/albums
このリクエストでは次の結果が返されます。
{ "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 }
アルバム コンテンツの一覧表示に示すように、返された各アルバムには、アルバムのコンテンツを取得するために使用できる ID があります。また、タイトルと、含まれるメディア アイテムの数も含まれます。
productUrl
は、ユーザーが開くことができる Google フォトのアルバムを指します。
coverPhotoMediaItemId
には、このアルバムのカバー写真を表すメディア アイテム ID が含まれます。このカバー画像にアクセスするには、coverPhotoBaseUrl
を使用します。追加パラメータを指定せずに coverPhotoBaseUrl
を直接使用しないでください。
ユーザーのアカウントで作成されたアルバムやユーザーのアカウントに追加されたアルバム、アプリが共有しているアルバムには、追加の shareInfo
プロパティが含まれています。詳しくは、メディアを共有するをご覧ください。
アルバム内にメディア アイテムを作成できるかどうかを示す isWriteable
フラグも、アルバムに指定できます。このフラグが返されない場合、デフォルトで false
になります。これは、アプリに付与された次のようなアクセス権によって異なります。
- アルバムの作成者。
- 共有されているかどうか。
- ユーザーが承認したスコープ。
このフラグは、これらの条件のいずれかが変更されると変更される可能性があります。詳しくは、アルバムを作成するをご覧ください。レスポンスには nextPageToken
も含まれています。詳細については、ページネーションをご覧ください。
空のアルバムのレスポンスは、mediaItemsCount
と coverPhotoMediaItemId
がデフォルトで 0 に設定され、REST レスポンスから除外される点で異なります。また、coverPhotoBaseUrl
はデフォルトのプレースホルダ画像を指しています。
ライブラリ コンテンツの一覧表示
ユーザーの Google フォト ライブラリからすべてのメディア アイテムを一覧表示できます。 アーカイブ済みの項目と削除済みの項目は除外されます。フィルタを適用することで、コンテンツ、日付、その他のプロパティに基づいてメディア アイテムを一覧表示できます。ユーザーが Google フォトの [共有] タブにあるアイテムをライブラリに追加していない場合、そのアイテムはこのリストに含まれません。
メディア アイテムを取得するには、mediaItems.list を呼び出します。
REST
以下はリクエストのサンプルです。
GET https://photoslibrary.googleapis.com/v1/mediaItems
Content-type: application/json
Authorization: Bearer oauth2-token
{
"pageSize": "100",
}
GET リクエストは次のレスポンスを返します。
{ "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 }
レスポンスには、新しいものから順に並べられたメディア アイテムのリストが含まれます。詳細については、mediaItems
をご覧ください。また、nextPageToken
も含まれています。詳細については、ページネーションをご覧ください。
アルバムのコンテンツを一覧表示する
アルバム内のすべてのメディア アイテムを一覧表示するには、検索リクエストに albumId
フィールドを追加します。albumId
について詳しくは、アルバムの一覧表示と共有アルバムの一覧表示をご覧ください。albumId
が無効な場合は、Bad Request
エラーが返されます。ID が有効であるにもかかわらず、認証済みユーザーのアルバムが存在しない場合は、Not Found
エラーが返されます。エラー処理の詳細については、パフォーマンスのヒントとベスト プラクティスをご覧ください。
REST
以下はリクエストのサンプルです。
POST https://photoslibrary.googleapis.com/v1/mediaItems:search
Content-type: application/json
Authorization: Bearer oauth2-token
{
"pageSize": "100",
"albumId": "album-id"
}
POST リクエストは次のレスポンスを返します。
{ "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 }
レスポンスには、nextPageToken
とメディア アイテムのリストが含まれます。ライブラリのコンテンツをリストする場合とは異なり、メディア アイテムはアルバム内の順序で返されます。詳細については、mediaItems
とページネーションをご覧ください。ユーザーは Google フォトのインターフェースで注文を編集できます。
albumId
が設定されている場合、アルバムのコンテンツを一覧表示するときにフィルタを適用できません。
そのようにすると、Bad Request
エラーが発生します。
共有アルバムの一覧表示
ユーザーが共有したアルバムや、ユーザーと共有されているすべてのアルバムのリストを取得できます。これは Google フォトアプリの [共有] タブに似ています。
ユーザーが Google フォト ライブラリに追加した共有アルバムも、listingdocs の呼び出しで返されます。Library API を使用して共有アルバムを一覧表示するには、次の呼び出しを行います。
REST
以下はリクエストのサンプルです。
GET https://photoslibrary.googleapis.com/v1/sharedAlbums
このリクエストでは次の結果が返されます。
{ "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 }
アルバムのリストは sharedAlbums
に含まれています。詳しくは、アルバムの一覧表示をご覧ください。レスポンスには nextPageToken
も含まれます。詳細については、ページネーションをご覧ください。
アプリが作成、共有したアルバムには、追加の shareInfo
プロパティが含まれています。詳しくは、メディアを共有するをご覧ください。
アプリで作成されたアルバムの一覧表示
次の呼び出しで excludeNonAppCreatedData
を true
に設定すると、アプリによって作成されたアルバムを一覧表示できます。
REST
次の GET リクエストでは、ユーザーの Google フォト ライブラリに含まれる、アプリが作成したアルバムのみを一覧表示します。
GET https://photoslibrary.googleapis.com/v1/albums?excludeNonAppCreatedData=true Content-type: application/json Authorization: Bearer oauth2-token
次の GET リクエストでは、ユーザーの Google フォト ライブラリから、アプリが作成した共有アルバムのみを一覧表示します。
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 }
REST のページ分け
パフォーマンスを向上させるために、多数の結果を返すメソッド(リストメソッドなど)でレスポンスにページングを設定できます。各ページの結果の最大数は pageSize
パラメータで指定されます。
mediaItems:search
と mediaItems:list
の呼び出しの場合、デフォルトのページサイズは 25 アイテムです。レスポンスのサイズと広告掲載率のバランスが取れているため、このページサイズをおすすめします。メディア アイテムの検索と一覧表示のリクエストの最大ページサイズは 100 アイテムです。
アルバムを一覧表示する際のデフォルトおよび推奨ページサイズは 20 アルバム(最大 50 アルバム)です。
取得可能な結果の数がページサイズより大きい場合、レスポンスには nextPageToken
が含まれます。これは、サーバーから取得すべき結果がまだあることをアプリケーションに伝えます。
例
次の例に示すように、pageToken
パラメータで後続のリクエストに nextPageToken
を追加する必要があります。リクエストの本文で、またはクエリ パラメータとして、pageToken
をオペレーションに必要な他のパラメータと一緒に指定します。
リクエスト 1
{ "pageSize": "5", "filters": { … } }
回答 1
{ "mediaItem": [ … ], "nextPageToken": "next-page-token" }
リクエスト 2
{ "pageSize": "5", "filters": { … }, "pageToken": "page-token" }
回答 2
{ "mediaItem": [ … ], "nextPageToken": "next-page-token" }
nextPageToken
オブジェクトがなくなるまで、このパターンを繰り返します。
nextPageToken
は、同じリクエストに対してのみ有効です。パラメータが変更された場合、以前に使用した nextPageToken
を同じリクエストで使用することはできません。