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 コードとして提示します）。ユーザーはモバイル デバイスを使用してこの QR コードをスキャンできます。この URI は、ユーザーを Google フォト アプリに誘導します。ユーザーは、アンビエント デバイスに表示するメディアソース（アルバムなど）を構成できます。mediaSourcesSetをポーリングする: アプリケーションは、deviceIdを指定してGetDeviceメソッドを定期的に呼び出し、周囲のデバイスのステータスを確認する必要があります。AmbientDeviceレスポンスのmediaSourcesSetフィールドをモニタリングします。最初は false になります。ユーザーが Google フォト アプリでメディアソースを正常に選択すると、このフィールドは true に変わります。
AmbientDeviceレスポンスには、ポーリング頻度のガイドラインとして使用する必要があるpollIntervalを含むpollingConfigが含まれています。メディア アイテムを取得する:
mediaSourcesSetが true を返すと、アプリケーションはユーザーが選択したメディア アイテムの取得を開始できます。ListMediaItemsメソッドを呼び出し、deviceIdを指定します。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 リファレンス ドキュメントを確認する: 利用可能なすべてのメソッド、リクエスト パラメータとレスポンス パラメータ、エラーコードについて、詳細なリファレンス ドキュメントをご覧ください。