ユーザーがアンビエント デバイスを設定し、Google フォトでメディアソースを選択すると、アプリはそれらのメディア アイテムを一覧表示して取得し、表示できるようになります。
始める前に
- デバイスのセットアップを確認する: ユーザーのデバイスを作成して構成していることを確認します。
- Ambient API フローを理解する: Ambient API フローを確認して、プロセス全体、特に
mediaSourcesSetのポーリングを含むステップを理解します。
mediaSourcesSet のアンケート
デバイスのメディア アイテムを一覧表示するには、ユーザーが Google フォトアプリ内で、アプリと共有する写真を選択している必要があります。アプリは、この選択が行われたタイミングを判断するために、デバイスをポーリングする必要があります。
特定の deviceId の devices.get メソッドを定期的に呼び出します。AmbientDevice レスポンスの mediaSourcesSet フィールドをモニタリングします。最初は false になります。ユーザーがメディアソースを正常に選択すると、このフィールドは true に変わります。
AmbientDevice レスポンスには、ポーリング頻度のガイドラインとして使用する pollInterval を含む pollingConfig が含まれています。
メディア アイテムの一覧表示
デバイスの mediaSourcesSet が true になったら、ユーザーが選択したメディア アイテムの取得を開始できます。
mediaItems.listエンドポイントを使用する:https://photosambient.googleapis.com/v1/mediaItemsに GET リクエストを送信し、パスにdeviceIdを指定します。ページネーションを処理する（必要な場合）: レスポンスがページネーションされている場合があります。
pageSizeパラメータを使用して、返すアイテムの最大数を指定し、前のレスポンスのpageTokenを使用して、結果の次のページを取得します。メディア アイテムを処理する: レスポンスには、選択された各メディア アイテムを表す
AmbientMediaItemオブジェクトの配列が含まれます。これらのオブジェクトには、次のような重要な詳細情報が含まれます。id: メディア アイテムの固有識別子。creationTime: メディア アイテムが作成されたときのタイムスタンプ。mediaFile: 実際のコンテンツにアクセスするための詳細を含むオブジェクト。
mediaFile フィールドには baseUrl が含まれています。この baseUrl は、さまざまな解像度や形式でメディア アイテムのコンテンツにアクセスするための URL を作成するために使用します。
ベース URL
Google フォト 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 |
説明
画像のメディア アイテム（写真、動画のサムネイルなど）にアクセスするには、アプリケーションで表示する予定のサイズを指定する必要があります（これにより、アスペクト比を維持しながら画像をこのサイズに拡大または縮小できます）。これを行うには、例に示すように、必要なサイズをベース URL に連結します。 例: base-url=wmax-width-hmax-height 以下の例は、幅が最大 2,048 ピクセル、高さが最大 1,024 ピクセルのメディア アイテムを示しています。 https://lh3.googleusercontent.com/p/AF....VnnY=w2048-h1024 |
c |
説明
指定した幅と高さで正確なサイズに画像を切り抜くには、オプションの サイズ（ピクセル単位）は 1 ～ 16, 383 の範囲内である必要があります。画像の幅または高さがリクエストしたサイズを超える場合、画像は縮小され、切り取られます（縦横比は維持されます）。 例: base-url=wmax-width-hmax-height-c この例では、アプリケーションは正確に幅 256 ピクセル、高さ 256 ピクセルのメディア アイテム（サムネイルなど）を表示します。 https://lh3.googleusercontent.com/p/AF....VnnY=w256-h256-c |
d |
説明
位置情報のメタデータを除くすべての Exif メタデータを保持する画像をダウンロードする場合は、ベース URL に 例: base-url=d この例では、アプリケーションは位置情報のメタデータを除くすべてのメタデータを含む画像をダウンロードします。 https://lh3.googleusercontent.com/p/Az....XabC=d |
動画のベース URL
以下に示すのは、動画のベース URL で使用できるオプションのリストです。
| パラメータ | |
|---|---|
dv |
説明 動画 dv パラメータは、元の動画の高品質なトランスコード バージョンをリクエストします。このパラメータは、w パラメータおよび h パラメータと互換性がありません。 動画ダウンロードのベース URL がバイトを返すまでに数秒かかることがあります。 このパラメータを使用する前に、メディア アイテムの 例: base-url=dv 次の例は、動画のバイトをダウンロードする方法を示しています。 https://lh3.googleusercontent.com/p/AF....BsdZ=dv |
w、h、c、d |
説明 動画のサムネイルにアクセスするには、画像のベース URL のパラメータのいずれかを使用します。 デフォルトでは、すべての動画のサムネイルに再生ボタンのオーバーレイが含まれます。このオーバーレイを削除するには、-no パラメータをご覧ください。 例: 例については、イメージ ベース URL の表をご覧ください。 |
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 からダウンロードする場合と同様に |
w、h、c、d |
説明 モーション フォト メディア アイテムの写真要素を取得するには、画像のベース URL の形式を使用します。 |
コンテンツ ポリシーとフィルタリング
Google フォトでは、テレビやデジタル ディスプレイなどの共有デバイスに表示される画像や動画に対して、デフォルトで標準のコンテンツ フィルタリングが適用されます。このフィルタは、次のようなコンテンツを除外して視聴体験を最適化するように設計されています。
- 機能的な画像（スクリーンショット、ドキュメント、領収書など）。
- 大画面で適切にレンダリングされない可能性がある画像（解像度が非常に低い、ぼやけている、粒子が粗すぎるなど）。
- 非常に個人的または機密性の高いコンテンツとして識別されたコンテンツ。共有設定で一般に表示することを意図していない可能性があります。
コンテンツのフィルタリングはすべて自動で行われます。表示されるコンテンツをユーザーがより細かく制御できるように、アンビエント ディスプレイで使用するメディアソースを手動で選択して更新できるようにします。
次のステップ
- サンプル アプリケーション: サンプル アプリケーションには、メディア アイテムのリスト表示と取得の例が含まれています。詳しくは、
checkMediaSourcesSet関数とfetch_media_item_list関数をご覧ください。 - リファレンス ドキュメント: 利用可能なすべてのメソッド、リクエストとレスポンスのパラメータ、エラーコードの詳細については、メディア アイテムに関する包括的なリファレンス ドキュメントをご覧ください。