インテントリクエスト履歴
インテントリクエスト履歴APIは、ユーザーの音声データや、スキルに関するインテントリクエストの詳細を集めて匿名化したコピーデータを、スキルごとにスキル開発者に提供します。当該ロケールのある1日分のデータを使用できるようにするには、ロケールごとに1日最低10人のユニークユーザーが必要です。いくつかのロケールでしきい値に達し、他のロケールでは達しなかったという場合、しきい値に達したロケールのデータのみが返されます。
このAPIは以下の機能をサポートしています:
- 結果をテキストで検索および並び替える
- 結果を複数ページに分けて表示する
- データを直近の30日間以上のユーザーの対話に応じて毎日更新
提供されたデータは、スキルに送信された発話のサブセットで、よく使用される発話のみを含めるよう、フィルタリングされています。つまり、ユーザーの日次のしきい値を満たしていたとしても、返される発話がない場合もあるということです。
このAPIのエンドポイントは、https://api.fe.amazonalexa.comです。すべてのAPIリクエストにはAuthorization
ヘッダーが必要であり、その値はLogin with Amazonから取得したアクセストークンでなければなりません。
SMAPI v1 APIはすべて、該当する場合に次のエラー応答をスローします。 HTTP/1.1 429 TooManyRequestsException(リクエストが制限される場合)、HTTP/1.1 503(サービスが利用できない場合)。
このコマンドのコマンドラインインターフェースのバージョンについては、Alexa Skills Kitコマンドラインインターフェース(ASK CLI)リファレンスを参照してください。
開発者コンソールでインテント履歴を確認することもできます。カスタムスキルのインテント履歴を確認するを参照してください。
リクエスト
GET /v1/skills/{skillId}/history/intentRequests
パラメーター
プロパティ | 必須 | パラメータータイプ | 説明 |
---|---|---|---|
skillId |
◯ | パス | 発話データが返される先のskillId です。有効値: 有効なスキルID |
nextToken |
✕ | クエリーパラメーター | nextToken は、結果の項目に通しでページ番号をふるために使用されます。nextToken はmaxResults パラメーターとともに使用し、ページに読み込む結果の数を指定します。最初のページを読み込むには、このプロパティをnull に設定します。有効期間は60分です。このトークンは、このトークンを取得するために使用したフィルターとスキルIDのセットに結びついているため、他のパラメーターが使用された場合は無視されます。その場合は、新しい検索パラメーターによって得た結果の最初のページが返されます。デフォルト値: null
|
sortField |
✕ | クエリーパラメーター | 結果の項目は、この属性で指定したフィールドの値に従って並び替えられます。ソートの順序は、別のsortDirection アトリビュートで定義します。このフィールドは大文字と小文字を区別しません。有効値: dialogAct.name 、locale 、intent.confidence.bin 、stage 、publicationStatus 、intent.name 、interactionType 、またはutteranceText
|
sortDirection |
✕ | クエリーパラメーター | 適用される並び替えの順序です。デフォルトでは、順序は降順です。このフィールドは大文字と小文字を区別しません。 デフォルト値: desc 、有効値:asc (昇順)またはdesc (降順)
|
maxResults |
✕ | クエリーパラメーター | 応答で返される結果の項目の最大数(最低ではありません)。デフォルトでは、この数は10に設定されています。maxResults の上限は250です。デフォルト値: 10 有効値: 1から250までの正の整数(1と250も含む) |
dialogAct.name |
✕ | クエリーパラメーター | dialogAct.name フィルターは、dialogAct.name の値がこのフィルターの値のいずれかに一致する場合、その結果を表示します。このフィルターは複数の値を持つことができ、大文字と小文字を区別しません。これらの値は、マルチターンの会話のコンテキストで発生します。Dialogディレクティブとマルチターンの会話の詳細については、Dialogインターフェースのリファレンスを参照してください。デフォルト値: null 有効値: Dialog.ElicitSlot 、Dialog.ConfirmSlot 、またはDialog.ConfirmIntent |
locale | ✕ | クエリーパラメーター | locale フィルターは、locale の値がこのフィルターの値のいずれかに一致する場合、その結果を表示します。このフィルターは複数の値を持つことができ、大文字と小文字を区別しません。デフォルト値: null 有効値: 現在サポートされているすべてのロケールになります。例: en-US
|
intent.confidence.bin |
✕ | クエリーパラメーター | intent.confidence.bin フィルターは、intent.confidence.bin の値がこのフィルターの値のいずれかに一致する場合、その結果を表示します。このフィルターを実行すると、スキルは信頼度が低のインテントを受け取らないことに注意してください。このフィルターは複数の値を持つことができ、大文字と小文字を区別しません。すべてのインテントリクエストは、IDの信頼度に応じて自動的に高 、中 、低 のいずれかに振り分けられます。デフォルト値: null 有効値: HIGH 、MEDIUM 、またはLOW
|
stage |
✕ | クエリーパラメーター | stage フィルターは、stage の値がこのフィルターの値のいずれかに一致する場合、その結果を表示します。このフィルターは複数の値を持つことができ、大文字と小文字を区別しません。このアトリビュートは、スキルの公開中のバージョンに対するインテントリクエストを、スキルの開発中のバージョンと区別するために使用します。デフォルト値: null 有効値: live またはdevelopment
|
publicationStatus | ✕ | クエリーパラメーター | publicationStatus フィルターは、publicationStatus の値がこのフィルターの値のいずれかに一致する場合、その結果を表示します。このフィルターは複数の値を持つことができ、大文字と小文字を区別しません。デフォルト値: null 有効値: CERTIFICATION またはDEVELOPMENT
|
utteranceText | ✕ | クエリーパラメーター | utteranceText フィルターは、utteranceText の値を使用した全文検索の結果を表示します。このフィルターは複数の値を持つことができ、大文字と小文字を区別しません。デフォルト値: null 有効値: 任意の文字列 |
intent.name | ✕ | クエリーパラメーター | intent.name フィルターは、intent.name の値がこのフィルターの値のいずれかに一致する場合、その結果を表示します。このフィルターは複数の値を持つことができ、大文字と小文字を区別しません。デフォルト値: null 有効値: スペースを使用していない任意の文字列 |
intent.slot.name | ✕ | クエリーパラメーター | このフィルターは、intent.slots.slot.name の値がこのフィルター値のうち1つ以上に一致する場合、その結果を表示します。このフィルターは複数の値を持つことができ、大文字と小文字を区別しません。デフォルト値: null 有効値: スペースを使用していない任意の文字列 |
interactionType | ✕ | クエリーパラメーター | このフィルターは、interactionType の値がこのフィルターの値に一致する場合、その結果を表示します。発話がONE_SHOT 対話として実行されたのか、MODAL 対話として実行されたのかを示します。ONE_SHOT : ユーザーはスキルを呼び出して単一のフレーズでインテントを伝えます。MODAL : ユーザーは最初にスキルを呼び出してからインテントを発話します。このフィルターは複数の値を持つことができます。 デフォルト値: null 有効値: ONE_SHOT またはMODAL
|
サンプルリクエスト
インテントリクエストの履歴を取得するこのサンプルリクエストでは、インテントリクエスト履歴APIに対するリクエストをさまざまな属性の組み合わせによってフィルタリングする方法を示します。
この場合、結果は降順で表示され、intent.confidence.bin
フィールドをキーに並び替えられており、結果のロケールがen-US
またはja-JP
、intent.confidence.bin
の値がHIGH
またはMEDIUM
、development
のstage
およびCERTIFICATION
のpublicationStatus
になります。ダイアログ、スロット名、発話のテキストなどによって結果を絞り込むために、追加でフィルターをかけています。
このサンプルリクエストでは読みやすくするために改行を入れていますが、改行を入れずにつなげる方がいいでしょう。
GET /v1/skills/{skillId}/history/intentRequests?
nextToken=VWB111111111
&maxResults=5
&sortField=intent.confidence.bin
&sortDirection=desc
&locale=en-US&locale=ja-JP
&intent.confidence.bin=HIGH&intent.confidence.bin=MEDIUM
&stage=development
&publicationStatus=CERTIFICATION
&dialogAct.name=Dialog.ElicitSlot&dialogAct.name=Dialog.ConfirmSlot
&intent.slots.name=answer
&utteranceText=answer%20is
&intent.name=AnswerIntent
&interactionType=MODAL
stage
とpublicationStatus
に他の値を使用すると、異なる結果を取得できます。たとえば、stageをlive
に設定すると、live
バージョンのスキルに対するインテントリクエストの履歴を取得できます。
応答
以下に応答のサンプルを示します。
HTTP/1.1 200 OK
Content-Type: application/json+hal
{
"body": {
"_links": {
"self": {
"href": "v1/skills/{skillId}/history/intentRequests?nextToken=VWB111111111&maxResults=5&sortDirection=desc&sortField=intent.confidence.bin&locale=en-US&locale=en-GB&locale=de-DE&intent.confidence.bin=HIGH&intent.confidence.bin=MEDIUM&stage=development&publicationStatus=CERTIFICATION&dialogAct.name=Dialog.ElicitSlot&dialogAct.name=Dialog.ConfirmSlot&intent.slots.name=answer&utteranceText=answer&intent.name=AnswerIntent&interactionType=MODAL"
},
"next": {
"href": "v1/skills/{skillId}/history/intentRequests?nextToken=VXjbbbbbbbbb&maxResults=5&sortDirection=desc&sortField=intent.confidence.bin&locale=en-US&locale=en-GB&locale=de-DE&intent.confidence.bin=HIGH&intent.confidence.bin=MEDIUM&stage=development&publicationStatus=CERTIFICATION&dialogAct.name=Dialog.ElicitSlot&dialogAct.name=Dialog.ConfirmSlot&intent.slots.name=answer&utteranceText=answer&intent.name=AnswerIntent&interactionType=MODAL"
}
},
"nextToken": "VXjbbbbbbbbb",
"totalCount": 15,
"skillId": "amzn1.ask.skill.12345678-1234-1234-123456789123",
"startIndex": 0,
"isTruncated": true,
"items": [
{
"dialogAct": {
"name": "Dialog.ConfirmSlot"
},
"intent": {
"name": "AnswerIntent",
"confidence": {
"bin": "HIGH"
},
"slots": {
"answer": {
"name": "answer"
}
}
},
"locale": "ja-JP",
"interactionType": "MODAL",
"stage": "development",
"publicationStatus": "CERTIFICATION",
"utteranceText": "答えはkです"
},
{
"dialogAct": {
"name": "Dialog.ConfirmSlot"
},
"intent": {
"name": "AnswerIntent",
"confidence": {
"bin": "HIGH"
},
"slots": {
"answer": {
"name": "answer"
}
}
},
"locale": "ja-JP",
"interactionType": "MODAL",
"stage": "development",
"publicationStatus": "CERTIFICATION",
"utteranceText": "ゲームトリビアに答えは象だと言って"
},
{
"dialogAct": {
"name": "Dialog.ElicitSlot"
},
"intent": {
"name": "AnswerIntent",
"confidence": {
"bin": "HIGH"
},
"slots": {
"answer": {
"name": "answer"
}
}
},
"locale": "ja-JP",
"interactionType": "MODAL",
"stage": "development",
"publicationStatus": "CERTIFICATION",
"utteranceText": "答えはアポロです"
},
{
"dialogAct": {
"name": "Dialog.ConfirmSlot"
},
"intent": {
"name": "AnswerIntent",
"confidence": {
"bin": "MEDIUM"
},
"slots": {
"answer": {
"name": "answer"
}
}
},
"locale": "ja-JP",
"interactionType": "MODAL",
"stage": "development",
"publicationStatus": "CERTIFICATION",
"utteranceText": "答えはテトリスです"
},
{
"dialogAct": {
"name": "Dialog.ConfirmSlot"
},
"intent": {
"name": "AnswerIntent",
"confidence": {
"bin": "MEDIUM"
},
"slots": {
"answer": {
"name": "answer"
}
}
},
"locale": "ja-JP",
"interactionType": "MODAL",
"stage": "development",
"publicationStatus": "CERTIFICATION",
"utteranceText": "答えはワシントンd cです"
}
]
}
}
応答のアトリビュート
フィールド | 説明 |
---|---|
nextToken | nextToken を使用して、結果の次のセットを読み込みます。 |
totalCount | クエリーに一致した結果の総数です。totalCount ≥ 0 |
skillId | インテントリクエストの履歴データが返される先のスキルです。 |
startIndex | 現在の結果セットにおけるトークンの位置です。 |
isTruncated | 検索リクエストに一致する結果の一部が返されなかった場合に、このプロパティはtrue になります。すべてが返された場合はfalse になります。 |
items | 発話データのコレクションです |
item.intent.confidence.bin |
この対話または項目の信頼度レベルです。以下のいずれかになります。
|
item.dialogAct.name |
この対話で使用される
|
item.intent.name | この対話で使用されるインテントです。 |
item.locale | この対話が発生するロケールです。以下のいずれかになります。en-US 、en-GB 、en-IN 、en-CA 、en-AU 、de-DE 、fr-FR 、またはja-JP 。 |
item.intent.slots.name | スキルに返されるスロットです。 |
item.stage | この対話が発生するスキルのステージです。有効値:live またはdevelopment |
item.publicationStatus |
この対話が発生するスキルの状態です。以下のいずれかになります。
|
item.utteranceText | スキルを使用した実際のユーザーの対話です。 |
item.interactionType |
発話が
|
例外
応答の例外のリストは以下のとおりです。
HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable