Amazon Alexa Skill Kit のリクエストを紐解く

はじめに

Alexa Skillの開発をする際には、送信されたJSONを使って各種処理を行います。
今回は送信されたJSONを1つずつ紐解いてみたいと思います
ただ・・・調べている途中にAmazonの公式のドキュメントに詳細にかかれていることに気が付きました。。。
書きかけだったのと、公式ドキュメントより具体的に書いている部分もあるので自分のメモも兼ねて公開しておきます。

カスタムスキルのJSONインターフェースのリファレンス | Custom Skills

Alexa Request JSON

Alexaから送信されるJSONは下記です。

{
  "session": {
    "new": true,
    "sessionId": "SessionId.xxx",
    "application": {
      "applicationId": "amzn1.ask.skill.xxx"
    },
    "attributes": {},
    "user": {
      "userId": "amzn1.ask.account.xxx",
      "accessToken": "xxx",
      "permissions": {
        "consentToken": "xxx"
      }
    }
  },
  "request": {
    "type": "IntentRequest",
    "requestId": "EdwRequestId.xxx",
    "intent": {
      "name": "HelloWorldIntent",
      "slots": {}
      }
    },
    "locale": "ja-JP",
    "timestamp": "2018-03-15T23:30:55Z"
  },
  "context": {
    "AudioPlayer": {
      "playerActivity": "IDLE"
    },
    "System": {
      "application": {
        "applicationId": "amzn1.ask.skill.xxx"
      },
      "user": {
        "userId": "amzn1.ask.account.xxx"
      },
      "device": {
        "supportedInterfaces": {}
      }
    }
  },
  "version": "1.0"
}

項目ごとに詳細に説明します。

session.new

このセッションが新しいセッションかどうかの値を返します。値はtrue　or　falseです。
例えばAlexaに、続きの発話を要求したい場合にはセッションが継続する旨のレスポンスを返します。
その場合にはAlexaデバイスは発話待ちの状態になります。
発話待ちの状態から新しい発話を受け取るとfalseとしてリクエストが飛んできます。

例えば下記のような発話例の場合には「1」のリクエストはtrueで、「3」のリクエスではfalseとなります。

# 発話例
1. 自分：　Alexa、プロフィールを起動して　【true】
2. Alexa：　あなたの名前を教えてください
3. 自分：　とちひら です　【false】
4. Alexa：　あなたの年齢を教えてください
5. 自分：　39歳 です　【false】
6. Alxa： とちひら さんの年齢は 39歳 ですね

session.sessionId

セッションごとのユニークなIDです。
公式ドキュメントにも書かれていますが、続き（session.new 発話例の様に続いている）の場合にはセッションIDは同一となります。

session.application.applicationId

Alexa SkillごとのユニークなIDです。
applicationIdは正しいAlexa Skillからのリクエストなのかを検証する際に利用します。

サービスに対するリクエストの妥当性を検証する | Custom Skills

session.attributes

Alexaで継続して発話を受け付けている場合に、以前の発話の値を次の発話まで保持したい場合があります。
その際にキーと値のペアでattributesにセットしてあげることで、次の発話で値を取り出すことが可能になります。

# 発話例
1. 自分：　Alexa、プロフィールを起動して
2. Alexa：　あなたの名前を教えてください
3. 自分：　とちひら です　【「とちひら」をセット】
4. Alexa：　あなたの年齢を教えてください
5. 自分：　39歳 です
6. Alxa： とちひらさんの年齢は39歳ですね　【「とちひら」を取り出し】

session.user.userId

ユーザーごとのユニークなIDです。
userIdはスキルを有効にするとAmazonアカウントごとに割り振られます。
例えば複数のAlexaデバイスで、同じAmazonアカウントでスキルを利用している場合にはuserIdは同じになります。
スキルを有効=>無効=>有効とした場合には新しいuserIdが付与されます。

例えば初回利用時にニックネームを登録してもらいます。
2回目からはニックネームで呼びかけるような場合にuserIdをキーとしてニックネームを保持することも可能です。

session.user.accessToken

AlexaがOAuthで外部サービスとアカウント連携した場合に必要となるaccessTokenです。

Alexaユーザーとシステムユーザーを関連付ける | Custom Skills

session.user.permissions.consentToken

Alexaには、住所やTODOリストを登録する仕組みがあります。
これらの個人情報にスキルからアクセスする事が可能です。
アクセスする際にconsentTokenを利用して個人情報を取得します。

所在地情報を使用してスキルを拡張する | Custom Skills

Alexaの買い物リストとTo Doリストにアクセスする | Custom Skills

request.type

リクエストの種類です。
インテントの指定が無い場合にはLaunchRequestが、インテントの指定がある場合にはIntentRequestが入ります。
IntentRequestはスキルを作っていれば自然と実装しますが、LaunchRequestは忘れがちです。ただ、LaunchRequestを実装していない場合には審査に通りません。（僕も審査に提出した際に指摘されました。）

標準のリクエストタイプのリファレンス | Custom Skills

request.requestId

requestIdは1リクエストごとに異なります。
連続した発話であっても、各リクエストごとに異なるrequestIdが入ります。

request.intent.name

スキルを作成する場合には、該当の発話がされると該当のインテントが呼ばれるように設定します。
その該当のインテント名が入ります。
例えば、「こんにちは」と発話された場合にHelloIntentを設定している場合にはrequest.intent.nameにはHelloIntentが入ります。

request.intent.slots

発話の中の単語を取得した場合があります。
例えば「私の名前はとちひらです」と発話された場合に名前の部分を取り出して利用したいときがあります。
この時に利用できるのがslotsです。スロットはキーと値のペアでデータが入っています。
キーをfirstName、値をとちひらとした場合のスロットは下記の様になります。
"slots"=>{"firstName"=>{"name"=>"firstName", "value"=>"とちひら"}}