その他のプラットフォームおよびデバイス向けのコードベースのリンク

Alexa Voice Service (AVS)にアクセスするには、Alexaが使えるデバイスでLogin with Amazon (LWA)のアクセストークンを取得する必要があります。デバイスは、このアクセストークンをリクエストのたびにAVSに送信します。ここでは、コードベースのリンク(CBL)について説明します。コードベースのリンクとは、テレビやスマートウォッチといった文字入力が制限される、あるいは文字入力の手段を持たない製品に最適な認可方法です。

製品の登録中、ユーザーは英数字の短いコードとURLを受け取ります。ブラウザーにアクセスできる別のデバイスでそのURLにアクセスし、Amazonの認証情報を使ってログインします。受け取ったコードを入力することで、Alexaが使えるデバイスをAmazonアカウントにリンクさせます。リンクが完了すると、製品にスプラッシュ画面が表示され、AVSにアクセスできるようになります。

• 認可のフロー
• ステップ1: CBLを有効化
• ステップ2: デバイス認可をリクエスト
  • リクエスト
  • レスポンス
• ステップ3: ユーザーにログインを指示
• ステップ4: デバイストークンをリクエスト
  • リクエスト
  • レスポンス
• ステップ5: リフレッシュトークンを渡して新しいアクセストークンを取得
• リソース

認可のフロー

以下の図は、AVSで使用するaccess_tokenとrefresh_tokenを取得するためにAlexaが使えるデバイスとLWAとの間で行われるやり取りを示しています。

ステップ1: CBLを有効化

1. Alexaダッシュボードにログインし、「Alexa Voice Service」を選択します。
   • 「管理する」をクリックして既存の製品でCBLを有効にするか、または
   • 「製品を作成する」をクリックして新しい製品を作成します。
2. 「セキュリティプロファイル」タブに移動し、「他のデバイスやプラットフォーム」を選択します。
3. 「クライアントID名」を入力し、「IDを生成」をクリックします。
4. 後で使用するため、クライアントIDは保存しておきます。

ステップ2: デバイス認可をリクエスト

まず、Alexaが使えるデバイスがPOSTリクエストを行い、LWAからユーザーコードとURLを取得する必要があります。有効なレスポンスが返された場合、ユーザーにuser_codeとverification_uriが表示されます。

リクエスト

エンドポイント: https://api.amazon.com/auth/O2/create/codepair

リクエストには以下のパラメーターを含める必要があります。

• response_type: 期待値はdevice_codeです。このパラメーターにより、サービスにCBLリクエストであることを伝えます。
• client_id: ステップ1で作成したクライアントIDです。
• scope: 期待値はalexa:allです。製品に付与するパーミッションを指定します。
• scope_data: productIDやdeviceSerialNumberといった製品固有の情報を含む追加のJSONデータです。以下は、JSONのサンプルです。
  • productID: 製品のデバイスタイプIDです。この情報にアクセスするには、Amazon開発者コンソールに移動します。ログインしたら、「ALEXA」をクリックし、Alexa Voice Serviceの「始める >」をクリックします。登録された製品の横にある「管理する」をクリックする(または、新しい製品を作成する)と、製品のクライアントIDとクライアントシークレットが表示されたページに移動します。
  • productInstanceAttributes: deviceSerialNumberを含むオブジェクトです。
    • deviceSerialNumber: 製品のこのインスタンスを一意に識別するキーです。たとえば、シリアルナンバーやMACアドレスなどです。
    メモ: 以下は、URLエンコードされる前のscopeオブジェクトのサンプルです。

    {
        "alexa:all": {
            "productID": "{{productId}}",
            "productInstanceAttributes": {
                "deviceSerialNumber": "{{deviceSerialNumber}}"
            }
        }
    }

オプション: リクエストにAccept-Languageヘッダーを含めると、ユーザーがログインと登録に使用する言語を選択できます。

• 有効な値: en-US、de-DE、es-ES、en-GB、fr-FR、it-IT、pt-BR、ja-JP、zh-CN

サンプルリクエスト

以下は、curlで記述したリクエストのサンプルです。

curl -k -d 'response_type=device_code&client_id={{client_id}}&scope=alexa%3Aall&scope_data=%7B%22alexa%3Aall%22%3A%7B%22productID%22%3A%22Speaker%22,%22productInstanceAttributes%22%3A%7B%22deviceSerialNumber%22%3A%2212345%22%7D%7D%7D' -H "Content-Type: application/x-www-form-urlencoded" -X POST https://api.amazon.com/auth/O2/create/codepair

レスポンス

レスポンスは、OAuth仕様のセクション3.4に従ってフォーマットされます。入力内容が有効な場合、レスポンスは以下のように構成されます。

サンプルレスポンス

{
    "user_code": "{{STRING}}",
    "device_code": "{{STRING}}",
    "verification_uri": "{{STRING}}",
    "expires_in": {{INTEGER}},
    "interval": {{INTEGER}}
}

エラー

• HTTP 400: MissingValue
• HTTP 500: ServiceError
• HTTP 503: ServiceUnavailable

ステップ3: ユーザーにログインを指示

製品がデバイス認可リクエストへのレスポンスを受け取ったら、ユーザーに対してuser_codeとverification_uriを表示する必要があります。セットアップと認証に記載されているデザインのガイダンスと画面の例を参照してください。

verification_uriに移動すると、ユーザーは、Amazon開発者認証情報でログインして提供されたuser_codeを入力するよう指示されます。コード登録ページは、OAuthの仕様であるユーザーへの指示コンポーネントを実装しています。

user_codeを入力すると、ユーザーは認証の成功または失敗を示すページにリダイレクトされます。認証に失敗した場合、ページにはその理由が表示されます(すでに認可済みのコード、認識できない、コードなど)。

ステップ4: デバイストークンをリクエスト

ユーザーにログインするよう指示したら、製品はaccess_tokenとrefresh_tokenのポーリングを開始します。

リクエスト

エンドポイント: https://api.amazon.com/auth/O2/token

リクエストには以下のヘッダーを含める必要があります。

POST /auth/o2/token
Host: api.amazon.com
Content-Type: application/x-www-form-urlencoded

リクエストには以下のパラメーターを含める必要があります。

• grant_type: 期待値はdevice_codeです。サービスにgrant種別を伝えます。
• device_code: デバイス認可リクエストで返されるコードです。
• user_code: ユーザーに表示されるコードです。ユーザーは登録時にこのコードを入力します。

レスポンス

ユーザーが登録フローを完了したら、以下の構造でレスポンスが返されます。

{
  "access_token": "{{STRING}}",
  "refresh_token": "{{STRING}}",
  "token_type": "bearer",
  "expires_in": {{INTEGER}}
}

• access_token: アクセストークン。
• refresh_token: リフレッシュトークン。
• token_type: ベアラー。
• expires_in: アクセストークンの有効期間(秒)。

ステップ5: リフレッシュトークンを渡して新しいアクセストークンを取得

アクセストークンの有効期限が切れた(または間もなく切れる)ときは、リフレッシュトークンを渡して新しいアクセストークンを取得します。POSTリクエストを行い、https://api.amazon.com/auth/O2/tokenに、これらのパラメーターを組み込んで作成したURLを渡します。

• grant_type: refresh_token。
• refresh_token: リフレッシュトークン。
• client_id: クライアントID。

レスポンスには以下の値が含まれます。

• access_token: アクセストークン。
• refresh_token: リフレッシュトークン。
• token_type: bearer。
• expires_in: アクセストークンの有効期限が切れるまでの残り時間(秒)。

リソース

• コンパニオンサイトからの認可
• コンパニオンアプリからの認可
• AVS製品からの認可