Ambient API を使用すると、アプリケーションでアンビエント デバイスをユーザーの Google フォト アカウントに接続し、選択した写真を表示できます。
Ambient API のフロー
アンビエント 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 を返すと、アプリケーションはユーザーが選択したメディア アイテムの取得を開始できます。deviceIdを指定してListMediaItemsメソッドを呼び出します。API は、AmbientMediaItemオブジェクトのリストを含むListMediaItemsResponseを返します。各AmbientMediaItemには、id、createTime、追加のメタデータを含むMediaFileオブジェクトなどの詳細が含まれます。MediaFileにはbaseUrlが含まれており、これを使用してメディア アイテムの実際のバイトを取得できます。その他のbaseUrlパラメータについて詳しくは、メディア アイテムのリストと取得のガイドをご覧ください。メディア アイテムを表示する:
MediaFileのbaseUrlを使用して、メディア コンテンツをダウンロードし、アンビエント デバイスに表示します。
重要な考慮事項
デバイスの制限と管理:
- デバイスの上限: アプリケーションのユーザー 1 人あたり 100 台のデバイスという上限に注意してください。
- デバイスのアクティビティとトークン: デバイスとユーザー認証トークンのライフサイクルを管理する必要があります。デバイスがアクティブな状態を維持する期間と、デバイスが非アクティブになった場合やトークンが期限切れになった場合のトークンの更新や再認証の処理方法を検討します。
詳しくは、デバイスの作成と管理をご覧ください。
メディア アイテムの操作:
- メディア アイテムの使用: 必要な認証やパラメータを含め、
baseUrlを使用してメディア アイテムのコンテンツを適切に取得して処理する方法を理解します。 - エラー処理: デバイスの
NOT_FOUND、メディアソースが設定されていない場合のFAILED_PRECONDITION、デバイスの上限に達した場合のRESOURCE_EXHAUSTEDなどのシナリオを含め、API 呼び出しの堅牢なエラー処理を実装します。
メディア アイテムの取得と一覧表示のガイドには、コンテンツ ポリシーとフィルタリングに関する情報など、詳細が記載されています。
次のステップ
- アプリケーションを構成する: 必要な認証情報があり、TV と入力機能が限られたデバイス用の OAuth 2.0 用にアプリケーションを構成していることを確認します。
- Ambient API リファレンス ドキュメントを確認する: 利用可能なすべてのメソッド、リクエストとレスポンスのパラメータ、エラーコードについて、詳細なリファレンス ドキュメントをご覧ください。