Alexa.Authorizationインターフェース



Alexa.Authorizationインターフェース

Alexa.Authorizationインターフェースには、特定のユーザーに向けての非同期応答と変更レポートイベントの通知が認可されるために必要なメッセージが含まれています。詳細については、アクセス権限を使用してAlexaのユーザー認証を実現するを参照してください。

ディレクティブ

AcceptGrant

AcceptGrantの目的は、Alexaに通知リクエストが来た時に、Alexaが宛先となる特定のユーザーを識別でき、許可をすることができるようにするための認証情報を提供することです。イベントをAlexaのイベントゲートウェイに送信するためには、このディレクティブを実装する必要があります。AcceptGrantディレクティブは、ユーザーがスマートホームスキルを有効にしてアカウントリンクのプロセスを完了するか、非同期応答イベントやプロアクティブイベントをサポートするように既存のスキルがアップグレードされた時に、Alexaから送信されます。

AcceptGrantディレクティブは与える許可に関する情報を持つgrantと、許可が与えられるユーザーを特定するための情報を持つgranteeを含んでいます。

リクエストの例

{
  "directive": {
    "header": {
      "namespace": "Alexa.Authorization",
      "name": "AcceptGrant",
      "messageId": "abc-123-def-456",
      "payloadVersion": "3"
    },
    "payload": {
      "grant": {
        "type": "OAuth2.AuthorizationCode",
        "code": "VGhpcyBpcyBhbiBhdXRob3JpemF0aW9uIGNvZGUuIDotKQ=="
      },
      "grantee": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      }
    }
  }
}

ペイロードの詳細

フィールド 説明 必須
grant イベントゲートウェイが、ユーザーを識別できるようにするために必要な情報を提供するポリモーフィックな型です。 ポリモーフィックなオブジェクトです。現在は次の子要素1つがサポートされています。 OAuth2.AuthorizationCode
grant.type 指定されたgrantの型を提供し、このオブジェクトの他のフィールドを決定します。 OAuth2.AuthorizationCodeを指定する文字列
grant.code ユーザーの認可コードです。 文字列
grantee スキルに関連付けられたアカウントサービスまたはシステムのユーザーを識別する情報を提供するポリモーフィックな型です。 ポリモーフィックなオブジェクトです。現在は次の子要素1つがサポートされています。BearerToken
grantee.type 指定されたgranteeの型を提供し、このオブジェクトの他のフィールドを決定します。 BearerTokenを指定する文字列です。
grantee.token アカウントリンクプロセスからAlexaが受け取るユーザーアクセストークンを提供します。 文字列

OAuth2.AuthorizationCode型

grantの子要素としてサポートされているのはOAuth2.AuthorizationCode型だけです。OAuth2.AuthorizationCodeを受け取る場合、grantにはOAuth2認可コードを含むcodeアトリビュートが含まれています。「Login With Amazon(LWA)」を使用してアクセストークンと更新トークンの認可コードと交換します。詳細については、「アクセス権限を設定してAlexaへのユーザー認証を実現する」と LWAのドキュメントを参照してください。

BearerToken型

現在のところ、guranteeでサポートされている子要素はBearerToken型のみです。BearerToken型を受け取る場合、granteeにはtokenアトリビュートが含まれており、ここにアカウントリンクプロセスからAlexaが受け取るユーザーアクセストークンが含まれています。トークンを使用してシステムでユーザーを識別します。

プロパティとイベント

この機能では、以下のように応答する必要があります。

  • 同期的に応答します。つまり、AlexaからLambda関数に応答を送信します。

応答を送信する場合、メッセージのcontextにインターフェースのプロパティの状態を含める必要があります。

このインターフェースは同期的応答のみであるため、メッセージには相関トークンは含まれないことに注意してください。

プロパティ

現在、このインターフェースに定義されているレポート可能なプロパティはありません。

AcceptGrant.Response

AcceptGrantディレクティブの処理が成功した場合、AcceptGrant.Responseイベントにより同期的に応答する必要があります。

Example AcceptGrant.Response

{
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "namespace": "Alexa.Authorization",
      "name": "AcceptGrant.Response",
      "payloadVersion": "3"
    },
    "payload": {
    }
  }
}

ErrorResponse

AcceptGrantディレクティブの処理でエラーが発生した場合、ErrorResponseイベントを使用して同期的に応答する必要があります。

次のいずれかの理由でエラーが生じる場合、ACCEPT_GRANT_FAILEDエラー型を、エラーの詳細を説明するメッセージとともに返す必要があります。

  • アクセストークンおよび更新トークンの認可コード交換をするためのLogin with Amazonの呼び出しに失敗した
  • ユーザーのアクセストークンおよび更新トークンを保存しようとしたが、何らかの理由で操作を完了できなかった
  • アクセストークンおよび更新トークンを取得しようとした際に生じた、その他のエラー

ACCEPT_GRANT_FAILED ErrorResponseの例

{
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "namespace": "Alexa.Authorization",
      "name": "ErrorResponse",
      "payloadVersion": "3"
    },
    "payload": {
      "type": "ACCEPT_GRANT_FAILED",
      "message": "AcceptGrantディレクティブの処理が失敗した理由は次のとおりです。"
    }
  }
}

他のエラーに関しては、Alexa.ErrorResponseを参照してください。

その他のサンプルコード

リクエストと応答のサンプルについては、AlexaスマートホームのGitHubリポジトリで以下を参照してください。

Authorization