Alexa.Authorizationインターフェース



Alexa.Authorizationインターフェース

AlexaスキルにAlexa.Authorizationインターフェースを実装すると、非同期応答や、変更レポートなどのプロアクティブメッセージをAlexaイベントゲートウェイに送信できます。

概要

Alexa.Authorization.AcceptGrantディレクティブの目的は、ユーザーを識別してAlexaへの認証を行うための認証情報を提供することです。

Alexaは、ユーザーがスマートホームスキルを有効にしてアカウントリンクプロセスを完了した後、または開発者が既存のスキルを更新してプロアクティブな変更レポートイベントをサポートしたときに、AcceptGrantディレクティブを送信します。

AcceptGrantディレクティブには、主に次の2つの情報が含まれています。

  • Alexaから認可コードが送信されます。Login with Amazon(LWA)を使用して、この認可コードをアクセストークンや更新トークンと交換します。詳細については、LWAのドキュメントを参照してください。

  • Alexaから、アカウントリンクプロセスの間にAlexaに渡されたユーザーのアクセストークンが送信されます。このトークンを保存して、システムでユーザーを識別するために使用します。

ディレクティブ

AcceptGrantディレクティブ

Alexaでユーザーを識別するための認証情報を取得して保存できるようにするには、AcceptGrantディレクティブをサポートします。

AcceptGrantディレクティブの例

次の例は、Alexaがスキルに送信するAcceptGrantディレクティブを示しています。このインターフェースは同期的応答のみであるため、メッセージに相関トークンは含まれません。

{
  "directive": {
    "header": {
      "namespace": "Alexa.Authorization",
      "name": "AcceptGrant",
      "messageId": "<メッセージID>",
      "payloadVersion": "3"
    },
    "payload": {
      "grant": {
        "type": "OAuth2.AuthorizationCode",
        "code": "VGhpcyBpcyBhbiBhdXRob3JpemF0aW9uIGNvZGUuIDotKQ=="
      },
      "grantee": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      }
    }
  }
}

AcceptGrantディレクティブペイロードの詳細

フィールド 説明
grant Amazon Alexaシステムでユーザーを識別する情報です。 オブジェクト
grant.type グラントの種類です。現在有効な値は、OAuth2.AuthorizationCodeのみです。 文字列
grant.code ユーザーの認可コードです。 文字列
grantee リンクされたアカウントサービスまたはシステムでユーザーを識別する情報です。 オブジェクト
grantee.type granteeの種類です。現在有効な値は、BearerTokenのみです。 文字列
grantee.token アカウントリンクプロセスでAlexaが受け取ったユーザーアクセストークンです。 文字列

AcceptGrant応答イベント

AcceptGrantディレクティブを正しく処理したら、AcceptGrant.Responseイベントを使用して応答します。このインターフェースは同期的応答のみであるため、メッセージに相関トークンは含まれません。

AcceptGrant応答イベントの例

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "namespace": "Alexa.Authorization",
      "name": "AcceptGrant.Response",
      "messageId": "<メッセージID>",
      "payloadVersion": "3"
    },
    "payload": {}
  }
}

AcceptGrantのエラー処理

次のいずれかの理由でAcceptGrantディレクティブを正しく処理できなかった場合は、Alexa.Authorization.ErrorResponseイベントを使用して応答します。

  • Login with Amazonを呼び出して認可コードをアクセストークンや更新トークンと交換することができなかった。
  • ユーザーのアクセストークンや更新トークンを保存できなかった。
  • アクセストークンや更新トークンを取得して保存しようとしたときに、その他のエラーが発生した。

より一般的なエラーについては、Alexa.ErrorResponseイベントで応答します。

AcceptGrantエラー応答イベントの例

クリップボードにコピーされました。

{
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "namespace": "Alexa.Authorization",
      "name": "ErrorResponse",
      "payloadVersion": "3"
    },
    "payload": {
      "type": "ACCEPT_GRANT_FAILED",
      "message": "AcceptGrantディレクティブの処理に失敗しました。<理由>"
    }
  }
}