アンビエント API 用にアプリを構成する

Ambient API の使用を開始するには、Google API Console で API を有効にし、OAuth 2.0 クライアント ID を設定してプロジェクトを設定します。Ambient API は、TV と入力機能が限られたデバイスアプリケーション用の OAuth 2.0 を使用します。

アプリケーションは、Ambient API ユーザーに代わって Ambient API とやり取りします。ユーザーは OAuth 2.0 プロトコルを使用してこれらの API リクエストを承認します。

OAuth 2.0 クライアント ID を使用すると、アプリケーションのユーザーはログインし、Ambient API を認証して使用できるようになります。Ambient API はサービスアカウントをサポートしていません。これらの API を使用するには、ユーザーは有効な Google アカウントにログインしている必要があります。

アプリを構成する

まず API を有効にしてから、OAuth 2.0 クライアント ID をリクエストします。

API を有効にする

Ambient API を使用するには、プロジェクトでこの機能を有効にしておく必要があります。

Google API Console に移動します。
メニューバーで、プロジェクトを選択するか新しいプロジェクトを作成します。
Google フォト API を開くには、ナビゲーションメニューで [API とサービス] > [ライブラリ] を選択します。
「Ambient API」を検索します。Ambient API を選択し、[有効にする] をクリックします。

OAuth 2.0 クライアント ID をリクエストする

次の手順に沿って OAuth クライアント ID をリクエストし、アプリケーション用に構成します。Ambient API は、TV と入力機能が限られたデバイスアプリケーション用の OAuth 2.0 を使用します。

Google API Console に移動し、プロジェクトを選択します。
メニューから [API とサービス] > [認証情報] を選択します。
[認証情報] ページで、[認証情報を作成] > [OAuth クライアント ID] をクリックします。

注: 新しいプロジェクトを設定している場合は、プロジェクトの同意画面を構成するよう求められることがあります。
アプリケーションの種類を選択します。この例では、アプリケーションの種類は [テレビと入力が限られたデバイス] です。
OAuth 2.0 クライアントの名前を入力し、[作成] をクリックします。
表示される OAuth クライアントダイアログから、次の情報をコピーします。
- クライアント ID
- クライアントシークレット

アプリはこれらの値を使用して、有効化された Google API にアクセスできます。

Ambient API にアクセスする公開アプリケーションをリリースするには、Google によるアプリの審査が必要です。アプリケーションが確認されるまで、テストを行う際に「未確認のアプリ」であることを示すメッセージが画面に表示されます。

アプリを構成したら、使用を開始できます。次のリソースを確認するか、Ambient API の簡素化された認証フローについて確認してください。

クライアント ID の変更

Google フォト API を使用して作成されたリソースにアクセスしたり、変更したりできるのは、作成に使用した元のクライアント ID を使用してのみです。たとえば、Picker API で特定のクライアント ID を使用して session を作成し、後でアプリでそのクライアント ID を変更すると、アプリは以前のクライアント ID で作成された API リソースにアクセスできなくなります。

使用している Photos API に適したクライアント ID タイプを慎重に選択してください。アクセスに関する問題を回避するために、クライアント ID は絶対に必要な場合にのみ変更してください。

Ambient API の認証フローを簡素化

標準の Ambient API 認証フローでは、ユーザーが次の 2 つの QR コードをスキャンする必要があります。

Google アカウントに初めてログインします（まだログインしていない場合）。
2 つ目は、Google フォトアカウントで新しく作成したアンビエントデバイスにリンクします。ここで、表示するメディアアイテムを選択できます。

簡素化されたフローでは、最初の認証呼び出しで追加の state パラメータを渡すことで、ユーザーに 1 つの QR コードを提供できます。

制限付き入力デバイスの OAuth の一部としてデバイスコードとユーザーコードをリクエストする場合は、リクエストに state パラメータを追加します。state パラメータに次のコードを追加します。

パラメータ

パラメータ
`requestId`	`string` 必須。このリクエストの一意の識別子（クライアント提供）。これは、ネットワーク障害が発生した場合のリソースの重複を軽減するために使用されます。この ID は UUID（バージョン 4）文字列の形式で、次の要件を満たしている必要があります。ユーザーの機密性の高い個人情報は含めないでください。 32 桁の 16 進数を 5 つのグループに分割し、ハイフンで区切った「xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx」（または 8-4-4-4-12）の形式で指定する必要があります。
`displayName`	`string` 省略可。このデバイスのユーザー定義の表示名。この名前は Google フォトアプリの設定でユーザーに表示されますが、編集できるのは API 経由のみです。有効な表示名は 1 ～ 100 文字（両端を含む）にする必要があります。

requestId

string

必須。このリクエストの一意の識別子（クライアント提供）。これは、ネットワーク障害が発生した場合のリソースの重複を軽減するために使用されます。

この ID は UUID（バージョン 4）文字列の形式で、次の要件を満たしている必要があります。

ユーザーの機密性の高い個人情報は含めないでください。
32 桁の 16 進数を 5 つのグループに分割し、ハイフンで区切った「xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx」（または 8-4-4-4-12）の形式で指定する必要があります。

displayName

string

省略可。このデバイスのユーザー定義の表示名。

この名前は Google フォトアプリの設定でユーザーに表示されますが、編集できるのは API 経由のみです。

有効な表示名は 1 ～ 100 文字（両端を含む）にする必要があります。

たとえば、次のコードブロックをご覧ください。

    const response = await fetch("https://oauth2.googleapis.com/device/code", {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            client_id: config.clientId,
            scope: "profile https://www.googleapis.com/auth/photosambient.mediaitems",
            state: JSON.stringify({
                'requestId': requestId,
                'displayName': "My Device"
            })
        })
    });

成功した場合、レスポンスには user_code と verification_url が含まれます。これは、ユーザーが別のデバイスで移動できるように（ほとんどの場合 QR コードとして）ユーザーに表示します。state パラメータを指定すると、後で Ambient API で createDevice を呼び出すときに、2 つ目の QR コードで settingsUri を提示する必要がなくなります。これは、OAuth フロー内の最後のステップが自動的にこの場所にリダイレクトされるためです。

詳しくは、以下の説明をご覧ください。サンプルアプリのコードを確認することもできます。Ambient API を使用して入力機能が限られたデバイスの OAuth の一部として state パラメータを使用する例をご覧ください。

簡素化された認証フローの詳細

Ambient API の簡素化された OAuth フローを完全に理解するには、TV と入力機能が限られたデバイスアプリケーション用の OAuth 2.0 フローだけでなく、標準の Ambient API フローも理解しておくことが役に立ちます。各フローの手順は次のとおりです。

TV と入力機能が限られたデバイスアプリケーション用の OAuth 2.0:

アプリケーションは、アプリケーションがアクセス権をリクエストするスコープを識別するリクエストを Google の認可サーバーに送信します。
サーバーは、デバイスコードやユーザーコードなど、後続のステップで使用されるいくつかの情報とともにレスポンスを返します。
ユーザーが別のデバイスで入力してアプリを承認できる情報を表示します。
アプリは Google の認可サーバーをポーリングし、ユーザーがアプリを承認したかどうかを判断します。
ユーザーは、入力機能が豊富なデバイスに切り替え、ウェブブラウザを起動して、ステップ 3 に表示された URL に移動し、ステップ 3 に表示されたコードを入力します。ユーザーはアプリへのアクセス権を付与（または拒否）できます。
ポーリングリクエストに対する次のレスポンスには、ユーザーに代わってリクエストを承認するためにアプリが必要とするトークンが含まれています。（ユーザーがアプリへのアクセスを拒否した場合、レスポンスにはトークンが含まれません）。

Ambient API フロー:

既存の OAuth トークンを確認して、トークンを更新するか、新しいトークンをリクエストします。
OAuth トークンを取得したら、新しいデバイスを作成します。
settingsUri をユーザーに表示し、mediaSourcesSet が true を返すまでデバイスのポーリングを開始します。
ユーザーが settingsUri に移動し、アプリと共有する写真を選択します。
mediaSourcesSet が true を返したら、mediaItems のリストを取得します。
これで、スライドショーなどのアンビエントエクスペリエンスを開始できます。

どちらのフローにも、ユーザーに URL を表示し、ユーザーがリッチな入力デバイスでその URL に移動するステップが含まれています。最初の OAuth 呼び出しに state パラメータを含めると、表示する 2 つ目の URL を回避できます。

これは、TV と限定入力デバイスのアプリ向け OAuth 2.0 フローにおける最後のステップで、通常は「デバイスに戻っていただけます」というページにユーザーをリダイレクトするためです。state パラメータを追加すると、フローの最後のステップで settingsUri にリダイレクトされるようになります。アプリは引き続き OAuth トークンを受け取ります。このトークンを使用して、同じ requestId を使用して createDevice を呼び出す必要があります。同じ ID を持つデバイスが作成されると、最初の OAuth フローで、ユーザーは Google フォトアプリ内のリッチデバイスの正しいページにリダイレクトされます。

次の点に注意してください。

認証に問題がある場合に備えて、settingsUri を表示することをおすすめします。
ユーザーが写真の選択を更新する場合など、他のケースでも settingsUri を使用できます。