デバイスの作成と管理

このガイドでは、デバイスの作成、管理、削除の方法について説明します。デバイスを適切に管理することで、スムーズなユーザー エクスペリエンスを実現し、Ambient API を効率的に使用できます。

デバイスの作成

ユーザーが TV と入力機能が限られたデバイス アプリケーション用の OAuth 2.0 フローを使用して認証に成功したら、そのユーザーの Google フォト アカウントにデバイスを作成します。

アプリが devices.create メソッドを使用してデバイスを正常に作成すると、Ambient API は Google が生成した id を含む AmbientDevice オブジェクトを返します。この id を安全に保存し、ユーザーに関連付けます。

OAuth によるデバイス作成の合理化

Ambient API は、合理化された OAuth フローを提供します。最初の OAuth リクエストで追加の state パラメータを渡し、一致する requestId を使用して devices.create を呼び出すことで、デバイス作成プロセスをユーザーのログインフローに直接リンクできます。これにより、ユーザーがスキャンする必要がある QR コードの数を減らし、ユーザー エクスペリエンスを簡素化できます。

詳細と例については、Ambient API の効率化された認証フローのガイドをご覧ください。

デバイス数の上限

アプリケーションは、ユーザーごとに最大 100 台のデバイスを作成できます。この上限を超えると、API から RESOURCE_EXHAUSTED エラーが返されます。

デバイスの管理

デバイスを作成してユーザーの Google フォト アカウントにリンクしたら、そのライフサイクルを管理する必要が生じることがあります。

デバイスを取得する

特定のデバイスに関する情報を取得するには、一意の id を指定して devices.get メソッドを使用します。これは、mediaSourcesSet が true かどうかなど、デバイスのステータスを確認するのに役立ちます。

デバイスの更新

devices.patch メソッドを使用すると、既存のデバイスの特定のプロパティ（表示名など）を更新できます。これにより、ユーザーはデバイスをパーソナライズし、Google フォト内で簡単に識別できるようになります。

デバイスの削除

適切なクリーンアップとユーザー制御のために、デバイスを削除する戦略を実装します。devices.delete メソッドを使用してデバイスを削除できます。

デバイスを削除する際は、次のシナリオを考慮してください。

  • ユーザーの接続解除: ユーザーが Google フォト アカウントからアプリの接続を解除した場合は、対応するデバイスを削除する必要があります。
  • 孤立したデバイス: id を追跡できなくなったが、作成時に使用された requestId がまだある場合は、devices.delete で requestId を使用して、孤立したデバイスを削除できます。これにより、誤って重複が作成されるのを防ぎ、ユーザーのアカウントを整理された状態に保つことができます。

重要な考慮事項とベスト プラクティス

  • デバイスのライフサイクルとユーザー認証: デバイスのライフサイクルとユーザー認証トークンを管理する必要があります。デバイスがアクティブな状態を維持する期間と、デバイスが非アクティブになった場合やトークンの有効期限が切れた場合のトークンの更新や再認証の処理方法を検討します。
  • エラー処理: デバイス関連のすべての API 呼び出しに対して堅牢なエラー処理を実装します。次のようなシナリオに備えてください。
    • NOT_FOUND: デバイスが存在しないか、ユーザーが所有していない場合。
    • RESOURCE_EXHAUSTED: デバイスの上限を超えた場合。
    • ALREADY_EXISTS: requestId がすでに存在するデバイスを作成しようとした場合。

次のステップ