メディア アイテムの一覧表示と取得

ユーザーがアンビエント デバイスを設定して Google フォトでメディア ソースを選択すると、アプリはこれらのメディア アイテムを一覧表示して取得し、表示できます。

始める前に

  • デバイスの設定を確認する: ユーザーのデバイスを作成して設定したことを確認します。
  • Ambient API フローを理解する: Ambient API フローを確認して、全体的なプロセス（特に mediaSourcesSet のポーリングを含むステップ）を理解します。

mediaSourcesSet のアンケート

デバイスのメディア アイテムを一覧表示するには、ユーザーが Google フォト アプリ内でアプリと共有する写真を選択する必要があります。アプリは、この選択がいつ行われたかを判断するためにデバイスをポーリングする必要があります。

特定の deviceId の devices.get メソッドを定期的に呼び出します。AmbientDevice レスポンスの mediaSourcesSet フィールドをモニタリングします。最初は false になります。ユーザーがメディアソースを選択すると、このフィールドは true に変わります。

AmbientDevice レスポンスには、ポーリング頻度のガイドラインとして使用すべき pollInterval を含む pollingConfig が含まれます。

List Media Items

デバイスの mediaSourcesSet が true になったら、ユーザーが選択したメディア アイテムの取得を開始できます。

  1. mediaItems.list エンドポイントを使用する: パスに deviceId を指定して、https://photosambient.googleapis.com/v1/mediaItems に GET リクエストを送信します。

  2. ページネーションを処理する（必要に応じて）: レスポンスはページネーションされる場合があります。pageSize パラメータを使用して返されるアイテムの最大数を指定し、前のレスポンスの pageToken を使用して、結果の次のページを取得します。

  3. メディア アイテムを処理する: レスポンスには、選択したメディア アイテムを表す AmbientMediaItem オブジェクトの配列が含まれます。これらのオブジェクトには、次のような重要な詳細情報が含まれます。

    • id: メディア アイテムの一意の識別子。
    • creationTime: メディア アイテムが作成されたときのタイムスタンプ。
    • mediaFile: 実際のコンテンツにアクセスするための詳細を含むオブジェクト。

mediaFile フィールドには baseUrl が含まれています。この baseUrl を使用して、さまざまな解像度や形式でメディア アイテムのコンテンツにアクセスするための URL を作成します。

ベース URL

Google Photos API のベース URL を使用すると、メディア アイテムの未加工バイトにアクセスできるため、アプリでメディア アイテムをダウンロードまたは表示できます。これらの URL は、アルバムのリストを取得する（Library API）場合や、メディア アイテムにアクセスする（Library API と Picker API の両方）場合のレスポンスに含まれます。ベース URL を正しく機能させるには、追加のパラメータが必要です。

Picker API の場合:

すべての PickedMediaItem.mediaFile オブジェクトには baseUrl が含まれています。

ベース URL は 60 分間有効ですが、ユーザーが Google アカウントの設定でアプリの権限を取り消した場合は、それより早く期限切れになることがあります。

Library API の場合:

ベース URL は 60 分間アクティブのままです。

ベース URL には次のものがあります。

  • baseUrl: 写真、動画のサムネイルに直接アクセスしたり、動画のバイト列をダウンロードしたりできます。
  • coverPhotoBaseUrl: アルバムのカバー写真に直接アクセスできます。
  • profilePictureBaseUrl: mediaItem のオーナーのプロフィール写真に直接アクセスできます。

画像のベース URL

以下に示すのは、画像のベース URL で使用できるオプションのリストです。

パラメータ
w、h

説明

幅 w パラメータと高さ h パラメータ。

画像のメディア アイテム（写真、動画のサムネイルなど）にアクセスするには、アプリケーションで表示する予定のサイズを指定する必要があります（これにより、アスペクト比を維持しながら画像をこのサイズに拡大または縮小できます）。これを行うには、例に示すように、必要なサイズをベース URL に連結します。

例:

base-url=wmax-width-hmax-height

以下の例は、幅が最大 2,048 ピクセル、高さが最大 1,024 ピクセルのメディア アイテムを示しています。

https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024
c

説明

切り抜き、c パラメータ。

指定した幅と高さで正確なサイズに画像を切り抜くには、オプションの -c パラメータと必須の w パラメータおよび h パラメータをベース URL に連結します。

サイズ（ピクセル単位）は 1 ～ 16, 383 の範囲内である必要があります。画像の幅または高さがリクエストしたサイズを超える場合、画像は縮小され、切り取られます（縦横比は維持されます）。

例:

base-url=wmax-width-hmax-height-c

この例では、アプリケーションは正確に幅 256 ピクセル、高さ 256 ピクセルのメディア アイテム（サムネイルなど）を表示します。

https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c
d

説明

ダウンロード、d パラメータ。

位置情報のメタデータを除くすべての Exif メタデータを保持する画像をダウンロードする場合は、ベース URL に d パラメータを連結します。

例:

base-url=d

この例では、アプリケーションは位置情報のメタデータを除くすべてのメタデータを含む画像をダウンロードします。

https://lh3.googleusercontent.com/p/Az....XabC=d

動画のベース URL

以下に示すのは、動画のベース URL で使用できるオプションのリストです。

パラメータ
dv

説明

動画 mediaItem のバイトにアクセスするには、baseUrl に動画のダウンロードを表す dv パラメータを連結します。

dv パラメータは、元の動画の高品質なトランスコード バージョンをリクエストします。このパラメータは、w パラメータと h パラメータと互換性がありません。

動画ダウンロードのベース URL からバイトを返すまでに数秒かかることがあります。

このパラメータを使用する前に、メディア アイテムの mediaMetadata.status フィールドが READY であることを確認してください。メディア アイテムの処理が完了していない場合は、エラーが発生することがあります。

例:

base-url=dv

次の例は、動画のバイトをダウンロードする方法を示しています。

https://lh3.googleusercontent.com/p/AF....BsdZ=dv
w、h、c、d

説明

動画のサムネイルにアクセスするには、画像のベース URL のパラメータのいずれかを使用します。

デフォルトでは、すべての動画のサムネイルに再生ボタンのオーバーレイが含まれています。このオーバーレイを削除するには、-no パラメータをご覧ください。

例:

例については、画像ベース URL の表をご覧ください。
no

説明

サムネイル オーバーレイを削除する no パラメータ。

再生ボタンのオーバーレイなしで動画のサムネイルを取得するには、ベース URL に no パラメータを連結します。

no パラメータは、画像のベース URL パラメータの少なくとも 1 つで使用する必要があります。

例:

base-url=wmax-width-hmax-height-no

次の例では、幅 1,280 ピクセル、高さ 720 ピクセルの動画サムネイルを表示し、再生ボタンのオーバーレイは含めていません。

https://lh3.googleusercontent.com/p/AF....VnnY=w1280-h720-no

モーション フォトのベース URL

モーション フォトには、写真と動画の両方の要素が含まれています。モーション フォトの baseUrl リクエストには、画像のベース URL または動画のベース URL のパラメータを使用できます。

パラメータ
dv

説明

モーション フォトのメディア アイテムの動画要素を取得するには、動画のベース URL からダウンロードする場合と同様に、dv パラメータを使用します。
w、h、c、d

説明

モーション フォト メディア アイテムの写真要素を取得するには、画像のベース URL の形式を使用します。

次のステップ

  • サンプル アプリケーション: サンプル アプリケーションには、メディア アイテムのリストと取得の例が含まれています。詳細については、checkMediaSourcesSet 関数と fetch_media_item_list 関数をご覧ください。
  • リファレンス ドキュメント: 使用可能なすべてのメソッド、リクエストとレスポンスのパラメータ、エラーコードについて詳しくは、メディア アイテムのリファレンス ドキュメントをご覧ください。