デバイスの作成と管理

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

デバイスの作成

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

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

OAuth によるデバイス作成の効率化

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

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

デバイス数の上限

アプリで作成できるデバイスは、ユーザーあたり 100 台までです。この上限を超えると、API は RESOURCE_EXHAUSTED エラーを返します。

デバイスの管理

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

デバイスを取得する

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

デバイスの更新

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

デバイスの削除

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

デバイスの削除に関する次のシナリオについて考えてみましょう。

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

重要な考慮事項とおすすめの方法

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

次のステップ