あなたのAlexaコンソール
?
サポート

Alexa.Authorizationインターフェース

Alexa.Authorizationインターフェース

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

ディレクティブ

AcceptGrant

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

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

リクエストの例

{
  "directive": {
    "header": {
      "namespace": "Alexa.Authorization",
      "name": "AcceptGrant",
      "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "payloadVersion": "3"
    },
    "payload": {
      "grant": {
        "type": "OAuth2.AuthorizationCode",
        "code": "VGhpcyBpcyBhbiBhdXRob3JpemF0aW9uIGNvZGUuIDotKQ=="
      },
      "grantee": {
        "type": "BearerToken",
        "token": "some-access-token"
      }
    }
  }
}

ペイロードの詳細

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

OAuth2.AuthorizationCode

grantの子要素としてサポートされているのはOAuth2.AuthorizationCode型だけで、これはOAuth2 authorizationコードを指定するcodeプロパティを提供します。認可コードを受信したら、「Amazonでログイン(LWA)」を使用してアクセストークンと更新トークンを受け取ります。詳細については、「Permissionsを設定してAlexaへのユーザー認証を実現する」と LWAのドキュメントを参照してください。

BearerToken

現在のところ、サポートされている子要素はBearerToken型のみです。BearerTokenには単一属性tokenが含まれていて、これはAlexaがアカウントリンクのプロセスで受信したユーザーのアクセストークンを持っており、システムでのユーザーの識別のために使うことができます。

ディレクティブがHTTPプロトコルバインディングを使用して送信された場合、Authorizationヘッダーとして次のような形式で grantee のベアラートークンが提供されます。

Authorization: Bearer some-token-to-identify-customer

プロパティとイベント

このインターフェースでは、次のように応答を行う必要があります。

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

Responseを送信するときには、レポート可能なプロパティがある時、メッセージのcontextにそれらの現在の状態に関する情報を含める必要があります。

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

レポート可能なプロパティ

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

AcceptGrant.Response

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

AcceptGrant.Responseの例

{
  "event": {
    "header": {
      "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
      "namespace": "Alexa.Authorization",
      "name": "AcceptGrant.Response",
      "payloadVersion": "3"
    },
    "payload": {
    }
  }
}

ErrorResponse

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

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

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

ACCEPT_GRANT_FAILED ErrorResponseの例

{
  "event": {
    "header": {
      "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
      "namespace": "Alexa.Authorization",
      "name": "ErrorResponse",
      "payloadVersion": "3"
    },
    "payload": {
      "type": "ACCEPT_GRANT_FAILED",
      "message": "Failed to handle the AcceptGrant directive because ..."
    }
  }
}

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

追加のサンプルコード

リクエストの例と応答メッセージについては、AlexaスマートホームGitHubリポジトリを参照してください。

Authorization