スキルのシミュレーション
スキルシミュレーションAPIでは、スキルの開発者がスキルをシミュレートできます。スキルをテストして、シミュレートされたデバイスが返すインテントを対話モデルから確認できます。APIでは、インテントのデバッグはJSON応答で返されたconsideredIntentsを返し、候補に挙がったが破棄されたインテントを表示します。この情報を使用して、意図したインテントとスロットに発話を解決するようにモデルをトレーニングするために、追加のサンプルをどのように使用するか決めることができます。特定の発話をテストして、その応答を対話モデルの改善に役立てるには、発話プロファイラーAPIを使用することもできます。
成功した場合の応答のヘッダーには、シミュレーションリソースの場所が含まれます。このAPIへのリクエストがエラーになった場合、応答に問題の詳細が記述されています。
このAPIのエンドポイントは、https://api.amazonalexa.comです。すべてのAPIリクエストにはAuthorization
ヘッダーが必要であり、その値はLogin with Amazonから取得したアクセストークンでなければなりません。
SMAPI v2 APIはすべて、該当する場合に次のエラー応答をスローします。 HTTP/1.1 429 TooManyRequestsException(リクエストが制限される場合)、HTTP/1.1 503(サービスが利用できない場合)。
このAPIは、ユーザー自身が開発したスキルのシミュレートに使用できます。シミュレートするスキルが、開発者のアカウントから有効にされたものであり、かつstageがdevelopment
またはlive
である必要があります。このAPIでは、1ユーザーからの同時に複数のリクエストは許可されていません。
スキルシミュレーションAPIは、スキルのテストにのみ使用します。
関連トピック: Alexa Skills KitコマンドラインインターフェースとAlexaスキル管理APIの概要とスキル呼び出しAPI
- スキルシミュレーションAPIリクエスト
- スキルシミュレーションAPI応答
スキルシミュレーションAPIリクエスト
HTTPメソッドとパス
POST /v2/skills/amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123/stages/live/simulations
パラメーター
フィールド | 説明 | パラメーターの型 | 必須 |
---|---|---|---|
skillId | 一意のスキルIDです。 | パス | ◯ |
stage | スキルのステージです。有効な値は、development とlive (大文字小文字の区別あり)です。 |
パス | ◯ |
リクエスト
リクエストヘッダー
Authorization:文字列(Login with Amazonアクセストークン)
Content-Type: application/json
Accept: application/json
リクエスト本文
{
"session": {
"mode": string enum ["DEFAULT", "FORCE_NEW_SESSION"]
},
"input": {
"content": string
},
"device": {
"locale": string
}
}
リクエストアトリビュートの定義
アトリビュート | 説明 |
---|---|
session.mode
|
任意です。シミュレートされたダイアログのセッション動作に影響を与える値です。セッションモードは、必ずシミュレーションを実行する前に新しいダイアログセッションが開始されるようにするFORCE_NEW_SESSION か、シミュレートされたダイアログのデフォルトのセッション動作を維持するDEFAULT のいずれかです。
|
input.content
|
ユーザーがAlexaに対して話しかける発話テキストを表す文字列です |
device.locale
| シミュレーションで使用する仮想デバイスのロケールです。有効なロケールは以下のいずれかです。en-US 、en-GB 、en-CA 、en-AU 、de-DE 、fr-FR 、en-IN 、ja-JP
|
スキルシミュレーションAPI応答
応答ヘッダー
Content-Type: application/json
Location: /skills/{skillId}/simulations/{simulationId}
X-Amzn-RequestId: string
応答本文
200 OK
{
"id": string,
"status": "IN_PROGRESS",
"result": null
}
エラー
エラー応答本文
{
"message": string
}
アトリビュート | 説明 |
---|---|
message | 読める形式でのエラー詳細です。 |
応答のエラーコード
応答 | 説明 |
---|---|
400 Bad Request | データが無効か、存在しません。 |
401 Not Authorized | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
403 Forbidden | APIユーザーにこのAPIを呼び出す権限がないか、現在このスキルのシミュレーションを許可されていません。 |
404 Not Found | 指定したスキルが存在しません。 |
409 Conflict | この開発者の別のリクエストを現在処理中です。開発者が、複数のスキルのシミュレーションリクエストを同時に実行しようとしました。 |
429 Throttling | APIユーザーが許容されるリクエストレートを超えました。 |
503 Service Unavailable | サービスを利用できません。 |
スキルシミュレーションリクエストのサンプル(POST)
HTTPメソッドとパス
POST /v2/skills/34b178945-6ec3-1749-a123-3cbd123456ab/stages/live/simulations
リクエストヘッダー
Authorization:文字列(Login with Amazonアクセストークン)
Content-Type: application/json
Accept: application/json
リクエスト本文
{
"session": {
"mode": "FORCE_NEW_SESSION"
},
"input": {
"content": "ごあいさつして"
},
"device": {
"locale": "en-US"
}
}
スキルシミュレーション応答のサンプル(200 OK) - 成功
インテントリクエストに対する正常な応答です。
応答ヘッダー
HTTP 200 OK
Location: /skills/amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123/simulations/34b178945-6ec3-1749-a123-3cbd123456ab
X-Amzn-RequestId: c03faf54-684d-11e7-6249-6bbd1825c634
応答本文
{
"id": "34b178945-6ec3-1749-a123-3cbd123456ab",
"status": "IN_PROGRESS",
"result": null
}
スキルシミュレーションリクエスト(GET)
HTTPメソッドとパス
GET /v2/skills/amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123/stages/live/simulations/34b178945-6ec3-1749-a123-3cbd123456ab
フィールド | 説明 | パラメーターの型 | 必須 |
---|---|---|---|
skillId | 一意のスキルIDです。 | パス | ◯ |
stage | スキルのステージです。有効な値は、development とlive (大文字小文字の区別あり)です。 |
パス | ◯ |
simulationId | シミュレーションの識別子 | ◯ |
リクエストヘッダー
Authorization:文字列(Login with Amazonアクセストークン)
Content-Type: application/json
Accept: application/json
リクエスト本文
GETリクエストのリクエスト本文がありません。
GETリクエストに対するスキルシミュレーション応答(200 OK)
応答ヘッダー
Content-Type: application/json
X-Amzn-RequestId: string
応答本文
{
"id": string,
"status": string enum["IN_PROGRESS", "SUCCESSFUL", "FAILED"],
"result": {
"skillExecutionInfo": {
"invocations": [{
"invocationRequest": {
"endpoint": string,
"body": object
},
"invocationResponse": {
"body": object
},
"metrics": {
"skillExecutionTimeInMilliseconds": integer
}
}]
},
"alexaExecutionInfo": {
"alexaResponses": [{
"type": "Speech",
"content": {
"caption": string
}
}],
"consideredIntents": [{
"name": string,
"confirmationStatus": string enum["NONE", "CONFIRMED", "DENIED"],
"slots": {
"SlotName": {
"name": string,
"value": string,
"confirmationStatus": string,
"resolutions": {
"resolutionsPerAuthority": [{
"authority": string,
"status": {
"code": string enum["ER_SUCCESS_MATCH", "ER_SUCCESS_NO_MATCH", "ER_ERROR_TIMEOUT", "ER_ERROR_EXCEPTION"]
},
"values": [{
"value": {
"name": string,
"id": string
}
}]
}]
}
}
}
}]
},
"error": {
"message": string
}
}
}
アトリビュート | 説明 |
---|---|
id | シミュレーションIDです。 |
status | シミュレーションの現在のステータスです。以下のいずれかになります。 IN_PROGRESS 、SUCCESSFUL 、またはFAILED です。
|
result
| シミュレーション結果に関する情報を含むオブジェクトです。 |
result.skillExecutionInfo
| スキルの実行結果を含むオブジェクトです。 |
result.skillExecutionInfo.invocations.invocationRequest
| 呼び出しリクエスト情報を含むオブジェクトです。 |
result.skillExecutionInfo.invocations.invocationRequest.endpoint | スキルのAWS LambdaまたはHTTPSエンドポイントです |
result.skillExecutionInfo.invocations.invocationRequest.body | スキルのAWS LambdaまたはHTTPSエンドポイントに送信されたJSONペイロードです |
result.skillExecutionInfo.invocations.invocationResponse
| 呼び出し応答情報を含むオブジェクトです。 |
result.skillExecutionInfo.invocations.invocationResponse.body | スキルのAWS LambdaまたはHTTPSエンドポイントが返したペイロードです。 |
result.skillExecutionInfo.invocations.metrics | スキルの実行時間に関する情報を含むオブジェクトです。 |
result.skillExecutionInfo.invocations.metrics.skillExecutionTimeInMilliseconds | AWS LambdaまたはHTTPSエンドポイントがリクエストを処理するのにかかった時間(ミリ秒)。 |
result.alexaExecutionInfo
| Alexaの実行結果を含むオブジェクトです。 |
result.alexaExecutionInfo.alexaResponses.type
| Alexaからの応答のタイプです。現時点でサポートされているのはSpeech 応答タイプのみです。
|
result.alexaExecutionInfo.alexaResponses.content
|
Alexaの応答の内容を含むオブジェクトです。 |
result.alexaExecutionInfo.alexaResponses.content.caption
|
Alexaの音声応答のテキストによる表現です。 |
result.alexaExecutionInfo.consideredIntents
| 配列には、自然言語理解(NLU)によって返された、候補に上がった最高5個のインテントが含まれます。 |
スキルシミュレーションリクエストのサンプル(POST)
HTTPメソッドとパス
POST /v2/skills/amzn1.ask.skill.1234../stages/live/simulations
リクエストヘッダー
Authorization:文字列(Login with Amazonアクセストークン)
Content-Type: application/json
Accept: application/json
リクエスト本文
{
"session": {
"mode": "DEFAULT"
},
"input": {
"content": "ごあいさつして"
},
"device": {
"locale": "en-US"
}
}
スキルシミュレーション応答のサンプル(200 OK) - 成功
インテントリクエストに対する正常な応答です。
応答ヘッダー
HTTP 200 OK
Content-Type: application/json
X-Amzn-RequestId: string
応答本文
スキルシミュレーション応答のサンプル(200 OK) - 処理中
応答ヘッダー
HTTP 200 OK
Content-Type: application/json
X-Amzn-RequestId: string
応答本文
{
"id": 34b178945-6ec3-1749-a123-3cbd123456ab,
"status": "IN_PROGRESS",
"result": null
}
スキルシミュレーション応答のサンプル(200 OK) - 失敗
この応答は、スキルシミュレーションが許可されていない場合に発生します。
応答ヘッダー
HTTP 200 OK
Content-Type: application/json
X-Amzn-RequestId: string
応答本文
{
"id": "34b178945-6ec3-1749-a123-3cbd123456ab",
"status": "FAILED",
"result": {
"alexaExecutionInfo": null,
"skillExecutionInfo": null,
"error": {
"message": "スキルは現在開発中ステージで無効です。このAPIを呼び出すにはスキルを有効にしてください。"
}
}
}