Alexa.Authorizationインターフェース3

Alexa.Authorizationインターフェース3

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

メッセージプロパティの定義については、Alexaインターフェースのメッセージとプロパティを参照してください。

イベントゲートウェイの認可

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

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

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

  • Alexaから認可コードが送信されます。Login with Amazon（LWA）を使用して、この認可コードをアクセストークンや更新トークンと交換します。詳細については、Get access token with authorization code操作およびLWA Authorization Code Grantを参照してください。

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

ディレクティブ

Alexa.Authorizationインターフェースは次のディレクティブを定義します。

AcceptGrantディレクティブ

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

AcceptGrantディレクティブの例

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

{
  "directive": {
    "header": {
      "namespace": "Alexa.Authorization",
      "name": "AcceptGrant",
      "messageId": "一意のバージョン4 UUID",
      "payloadVersion": "3"
    },
    "payload": {
      "grant": {
        "type": "OAuth2.AuthorizationCode",
        "code": "someAuthCode"
      },
      "grantee": {
        "type": "BearerToken",
        "token": "someAccessToken"
      }
    }
  }
}

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

次の表は、AcceptGrantディレクティブのペイロードの詳細を示しています。

プロパティ 説明 型 必須

grant

Amazon Alexaシステムでユーザーを識別する情報です。

オブジェクト

◯

grant.type

Grantの種類です。
有効な値は OAuth2.AuthorizationCodeです。

文字列

◯

grant.code

ユーザーの認可コードです。
Login with Amazon（LWA）OAuth 2.0サーバーを使用して、この認可コードをアクセストークンや更新トークンと交換します。

文字列

◯

grantee

リンクされたアカウントのサービスまたはシステムでユーザーを識別する情報です。

オブジェクト

◯

grantee.type

grantee（被付与者）の種類です。
有効な値は BearerTokenです。

文字列

◯

grantee.token

アカウントリンクプロセスでAlexaが受け取ったユーザーアクセストークンです。

文字列

◯

AcceptGrant応答

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

以下は、AcceptGrant.Responseの例です。応答にペイロードは必要ありません。

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

{
  "event": {
    "header": {
      "namespace": "Alexa.Authorization",
      "name": "AcceptGrant.Response",
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
      "payloadVersion": "3"
    },
    "payload": {}
  }
}

AcceptGrantのエラー処理

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

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

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

以下は、Alexa.Authorization.ErrorResponseの例です。

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

{
  "event": {
    "header": {
      "messageId": "一意の識別子、バージョン4 UUIDが望ましい",
      "namespace": "Alexa.Authorization",
      "name": "ErrorResponse",
      "payloadVersion": "3"
    },
    "payload": {
      "type": "ACCEPT_GRANT_FAILED",
      "message": "＜理由＞のため、AcceptGrantディレクティブを処理できませんでした"
    }
  }
}

このページは役に立ちましたか？

最終更新日: 2024 年 11 月 08 日