Ambient API を使用すると、アンビエント デバイスをユーザーの Google フォト アカウントに接続し、選択した写真を表示できます。
Ambient API のフロー
以下は、Ambient API がデバイスを接続し、メディア アイテムを取得して表示する仕組みの詳細です。
既存のデバイスを確認する（推奨）: 新しいデバイスを作成する前に、現在のユーザーのデバイスがすでに存在するかどうかを確認することをおすすめします。アプリは、内部ユーザーと、ユーザーがアプリで作成したデバイスの Google 提供の
deviceIdとのマッピングを維持する必要があります。ユーザーのdeviceIdが見つかった場合は、（必要に応じて）認可トークンの更新に進みます。OAuth 2.0 認可を開始する（必要に応じてデバイスを作成する）: 認可コードをリクエストして、TV と入力機能が限られたデバイス用の OAuth 2.0 フローを開始します。
新しいデバイスを作成する: アプリは、
CreateDeviceを呼び出して有効な v4 UUID を指定し、ユーザーの Google フォト アカウントにデバイスを作成します。デバイスの作成に成功すると、API は Google が割り当てた
deviceIdを含むAmbientDeviceオブジェクトを返します。アプリでこのdeviceIdを保存し、ユーザーに関連付けることが重要です。settingsUriを表示する:AmbientDeviceオブジェクトにはsettingsUriが含まれています。この URI をユーザーに提示します（通常は QR コードとして提示します）。ユーザーはモバイル デバイスでこの URI をスキャンできます。この URI により、ユーザーは Google フォト アプリにリダイレクトされます。ここで、アンビエント デバイスに表示するメディアソース（アルバムなど）を設定できます。mediaSourcesSetをポーリングする: アプリは、deviceIdを指定してGetDeviceメソッドを定期的に呼び出し、アンビエント デバイスのステータスを確認する必要があります。AmbientDeviceレスポンスのmediaSourcesSetフィールドをモニタリングします。最初は false になります。ユーザーが Google フォト アプリでメディアソースを選択すると、このフィールドは true に変わります。
AmbientDeviceレスポンスには、ポーリング頻度のガイドラインとして使用すべきpollIntervalを含むpollingConfigが含まれています。メディア アイテムを取得する:
mediaSourcesSetが true を返すと、アプリはユーザーが選択したメディア アイテムの取得を開始できます。deviceIdを指定してListMediaItemsメソッドを呼び出します。API は、AmbientMediaItemオブジェクトのリストを含むListMediaItemsResponseを返します。各AmbientMediaItemには、id、createTime、追加のメタデータを含むMediaFileオブジェクトなどの詳細が含まれます。MediaFileにはbaseUrlが含まれており、これを使用してメディア アイテムの実際のバイト数を取得できます。その他のbaseUrlパラメータの詳細については、メディア アイテムの一覧表示と取得のガイドをご覧ください。メディア アイテムを表示する:
MediaFileのbaseUrlを使用して、アンビエント デバイスにメディア コンテンツをダウンロードして表示します。
重要な考慮事項
デバイス数の上限と管理:
- デバイスの上限: アプリのユーザーあたり 100 台のデバイスという上限に注意してください。
- デバイスのアクティビティとトークン: デバイスとユーザー認可トークンのライフサイクルを管理する必要があります。デバイスがアクティブな状態を維持する期間と、デバイスが非アクティブになった場合やトークンが期限切れになった場合にトークンの更新や再承認をどのように処理するかを検討します。
詳しくは、デバイスの作成と管理のガイドをご覧ください。
メディア アイテムの操作:
- メディア アイテムの使用: 必要な認証やパラメータなど、
baseUrlを使用してメディア アイテム コンテンツを適切に取得して処理する方法について説明します。 - エラー処理: デバイスの
NOT_FOUND、メディアソースが設定されていない場合のFAILED_PRECONDITION、デバイスの上限に達した場合のRESOURCE_EXHAUSTEDなどのシナリオを含む、API 呼び出しに対する堅牢なエラー処理を実装します。
詳しくは、メディア アイテムの一覧表示と取得のガイドをご覧ください。
次のステップ
- アプリを構成する: 必要な認証情報が揃っていること、および TV と入力機能が限られたデバイス向けの OAuth 2.0 用にアプリが構成されていることを確認します。
- Ambient API リファレンス ドキュメントを確認する: 利用可能なすべてのメソッド、リクエストとレスポンスのパラメータ、エラーコードについては、詳細なリファレンス ドキュメントをご覧ください。