インテントリクエスト履歴

インテントリクエスト履歴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`	この対話または項目の信頼度レベルです。以下のいずれかになります。 `HIGH` `MEDIUM` `LOW`
`item.dialogAct.name`	この対話で使用される`dialogAct`です。以下のいずれかになります。 `Dialog.ElicitSlot` `Dialog.ConfirmSlot` `Dialog.ConfirmIntent`
`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`	この対話が発生するスキルの状態です。以下のいずれかになります。 `CERTIFICATION` `DEVELOPMENT`
`item.utteranceText`	スキルを使用した実際のユーザーの対話です。
`item.interactionType`	発話が`ONE_SHOT`対話として実行されたのか、`MODAL`対話として実行されたのかを示します。以下のいずれかになります。 `ONE_SHOT`：ユーザーはスキルを呼び出して単一のフレーズでインテントを伝えます。 `MODAL`：ユーザーは最初にスキルを呼び出してからインテントを発話します。

例外

応答の例外のリストは以下のとおりです。

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