セッション外からAlexaを呼び出すためのユーザー固有のアクセストークンを取得する

セッション外からAlexaを呼び出すためのユーザー固有のアクセストークンを取得する

カスタムスキルは、特定のAlexaリソースへのアクセスが常に必要な場合あります。たとえば、スキルがユーザーに通知を送信したり、ショッピングリストにアクセスしたり、デバイスの位置情報を読み取ったりする場合があります。これらのアクションは、スキルセッション外で発生する可能性があります。スキルセッション外でAlexa APIを呼び出すには、スキルがユーザー固有のAlexaアクセストークンを非同期で保存および更新する必要があります。

概要

はじめにスキルセッションについて復習し、スキルセッション外でスキルがAlexaリソースにアクセスする必要がある理由を説明します。スキルセッションは、次のように開始および終了します。

  1. スキルセッションは、ユーザーが「アレクサ、タクシー予約を開いて」などの発話でスキルを呼び出したときに開始されます。 これにより、Alexaはスキルにリクエストを送信します。このリクエストは通常起動リクエストですが、ユーザーは特定のインテントでスキルを呼び出すこともできます。リクエストにはsessionオブジェクトが含まれており、これにはスキルセッションを一意に識別するsessionIdが含まれています。
  2. ユーザーがスキルを操作すると、Alexaはスキルリクエストを送信します。これらのリクエストには、前述の一意のsessionIdが含まれます。スキルはリクエストに応答します。
  3. スキルセッションは、ユーザーがAlexaに応答しない場合、またはスキルがshouldEndSessionをtrueに設定してリクエストをAlexaに送信した場合に終了します。スキルセッションが終了すると、Alexaはその特定のsessionIdを持つスキルリクエストを送信しなくなります。ユーザーが新しいスキルセッションを呼び出すとsessionIdも新しいものになり、以前のスキルセッションは存在しません。

Alexaとスキルの間のほとんどのやり取りはスキルセッション内で発生しますが、ユーザーがスキルを明示的に呼び出さない場合でも、スキルがAlexaリソースにアクセスする必要がある場合があります。たとえば、ユーザーのショッピングリストを管理するスキルは、随時リストを更新する必要があります。これらのリクエストは、セッション外リクエストと呼ばれます。

セッション外リクエストの場合、スキルはユーザー固有のアクセストークンが必要となります。スキルはユーザー固有の認可コードを受け取ってから、ユーザー固有のアクセストークンを取得します。次に、スキルは一般的なOAuth 2.0認可コード付与フローで、認可コードとクライアント認証情報をアクセストークンに交換します。

スキルが認可コードをアクセストークンと正しく交換できない場合、ユーザーがスキルを有効にしたり同意を変更したりすると、Alexaはエラーを表示します。このような場合、Alexaはユーザーに認可を再試行するよう求めます。

認可コードを受け取るために使用するエンドポイントは、スキルがアカウントリンクを使用するかどうかによって異なります。

アカウントリンクを使用するスキルの場合

ユーザーがサードバーティサービスからAlexaスキルにアカウントリンクすると、ユーザーはAlexaがサービス内のアカウントリソースにアクセスすることを許可します。次に、Alexaは一般的なOAuth 2.0認可付与フローを通じてアクセストークンを保存および更新します。

しかし多くの場合、ユーザーは別のログインフローを経由することなく、Alexaリソースにアクセスするためのスキルも許可したいと考えています。これを相互認可といいます。

ステップ1： 認可コードを受け取る

Alexaは、以下のパラメーターを使用してエンドポイントに安全なHTTP POST application/x-www-form-urlencodedリクエストを送信することで、認可コードを提供します。

エンドポイント

スキルは、スキルマニフェスト内のアカウントリンクスキーマで指定したreciprocalAccessTokenUrlで認可コードを受け取ります。

リクエストのパラメーター

POSTリクエストには、次のパラメーターを含みます。

フィールド 説明

grant_type

許可タイプ。値はreciprocal_authorization_codeです。

code

ユーザーのAlexa認可コードです。

client_id

スキルのIDです。このclient_idを使って、アカウントリンクを使うよう設定した他のスキルと区別するなど、スキル固有の機能を提供できます。client_idは、スキルのアカウントリンクを設定する際に定義します。

例

認可コードを提供するリクエストの例を次に示します。

POST
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer （3Pアクセストークン）
grant_type=reciprocal_authorization_code&code=EXAMPLEAUTHCODE1234&client_id=someClientId

ステップ2： 認可コードをアクセストークンと交換する

相互アクセストークンエンドポイントが認可トークンを受け取った後、相互アクセストークンエンドポイントは次のことを行う必要があります。

  1. 認可ヘッダー内の提供されたアクセストークンが有効であり、スキルのアカウントリンク設定で登録された認可サーバーのユーザーを表していることを確認します。
  2. 提供されたAlexa認可コードをAlexaアクセストークンと交換します。認可コードとアクセストークンの交換の詳細については、Login with Amazon（LWA）ドキュメントのアクセストークンリクエストを参照してください。
  3. 次のHTTPコードのいずれかを返します。
    • 認可コードをアクセストークンと正常に交換した場合はHTTP 200(OK)を返します。
    • 認可コードをアクセストークンと交換しようとしたときに問題が発生した場合はHTTP 400(BAD_REQUEST)を返します。
    • その他の問題が生じた場合はHTTP 500(INTERNAL_SERVER_ERROR)を返します。

アカウントリンクを使用しないスキルの場合

スキルがアカウントリンクを必要としない場合は、セッション中のリクエストとAlexaイベントのsystemオブジェクトからuserIdを使用してAlexaユーザーを識別できます。systemオブジェクトの詳細については、Systemオブジェクトを参照してください。

ステップ1： 認可コードを受け取る

Alexaは、以下のパラメータを使用してAlexa.Authorization.Grantリクエストをエンドポイントに送信することで、認可コードを提供します。

エンドポイント

スキルは、スキルマニフェストのcustomオブジェクトで指定したエンドポイントで認可コードを受け取ります。

スキル用に異なるリージョンのエンドポイントを設定している場合、Alexaは適切なリージョンのURIを呼び出します。

リクエストのパラメーター

リクエストには次のパラメータが含まれます。

フィールド 説明

type

リクエストタイプ。値はAlexa.Authorization.Grantです。

requestId

リクエストIDです。

timestamp

リクエストのタイムスタンプです。

body.grant.type

認可コードのタイプ。OAuth2.AuthorizationCodeです。

body.grant.code

ユーザーのAlexa認可コードです。

例

認可コードを提供するリクエストの例を次に示します。

{
  "version": "1.0",
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.ask.skill.aaa"
      },
      "user": {
        "userId": "amzn1.ask.account.AAA"
      },
      "apiEndpoint": "https://api.amazonalexa.com"
   },
   "request": {
     "type": "Alexa.Authorization.Grant",
     "requestId": "12345-6789-EXAMPLE",
     "timestamp": "2018-01-01T12:00:00Z",
     "body" : {
        "grant": {
           "type": "OAuth2.AuthorizationCode",
           "code": "EXAMPLEAUTHCODE1234"
         }
       }  
     }
  }
}

ステップ2： 認可コードをアクセストークンと交換する

認可コードを受け取るエンドポイントでは、以下を実行する必要があります。

  1. 提供されたAlexa認可コードをAlexaアクセストークンと交換します。認可コードとアクセストークンの交換の詳細については、Login with Amazon（LWA）ドキュメントのアクセストークンリクエストを参照してください。
  2. 前のステップが成功した場合は、アクセストークンをuserIdに関連付けます。
  3. 次のHTTPコードのいずれかを返します。
    • 認可コードをアクセストークンと正常に交換した場合はHTTP 200(OK)を返します。
    • 認可コードをアクセストークンと交換しようとしたときに問題が発生した場合はHTTP 400(BAD_REQUEST)を返します。
    • その他の問題が生じた場合はHTTP 500(INTERNAL_SERVER_ERROR)を返します。
このページは役に立ちましたか？

最終更新日: 2020 年 09 月 28 日