アプリによって作成されたメディア アイテムとアルバムを一覧表示する

必要な認可スコープ

アプリ作成コンテンツをリストするには、photoslibrary.readonly.appcreateddata スコープが必要です。スコープの詳細については、認可スコープをご覧ください。

概要

Library API を使用すると、アプリが作成したメディア アイテムを一覧表示してアクセスできます。

リスティング メディア アイテムの主な機能は次のとおりです。

  • アプリが作成した特定のアルバムまたはアプリが作成したライブラリ全体のメディア アイテムをリストする

  • リストに表示するときにフィルタ（日付、コンテンツ カテゴリ、メディア タイプ）を適用して結果を絞り込む

  • 直接リンクやメタデータなどの重要な詳細情報を含む mediaItem オブジェクトを取得します。

ライブラリとアルバムのコンテンツをリストすると、メディア アイテムのリストが返されます。アルバムの一部であるエンリッチメントは含まれません。メディア アイテムは、写真や動画などのメディアを表します。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"
}

アルバムのコンテンツをリストするで説明するように、返された各アルバムには、アルバムのコンテンツを取得するために使用できる ID が含まれます。また、タイトルと、アルバム内のメディア アイテムの数も含まれます。

productUrl は、ユーザーが開くことができる Google フォト内のアルバムを参照します。

coverPhotoMediaItemId には、このアルバムのカバー写真を表すメディア アイテム ID が格納されています。このカバー写真にアクセスするには、coverPhotoBaseUrl を使用します。coverPhotoBaseUrl はそのまま使用せず、必ず追加のパラメータを指定してください。

レスポンスには nextPageToken も含まれます。詳しくは、ページ分けをご覧ください。

空のアルバムに対するレスポンスはさまざまで、mediaItemsCount と coverPhotoMediaItemId はデフォルトで 0 に設定され、REST レスポンスでは省略されます。また、coverPhotoBaseUrl はデフォルトのプレースホルダ画像を参照している点に注意してください。

アプリによって作成されたライブラリ コンテンツを一覧表示する

ユーザーの 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"
}

レスポンスには、新しい順に並べられたメディア アイテムのリストが含まれます。詳細については、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"
}

レスポンスには nextPageToken とメディア アイテムのリストが含まれます。ライブラリのコンテンツをリストする場合と異なり、アルバム内の順番でメディア アイテムが返されます。詳しくは、mediaItems と ページ分けをご覧ください。ユーザーは、Google フォトのインターフェースで並び順を編集できます。

albumId が設定されている場合、アルバムのコンテンツをリストするときにフィルタを適用することはできません。このようにすると、Bad Request エラーが発生します。

REST のページ分け

list メソッドなど多数の結果を返すメソッドでは、パフォーマンスを向上させるために、レスポンスをページ分けする場合があります。各ページの結果の最大数は 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 を同じリクエストで使用しないでください。