スキルのシミュレーション

スキルシミュレーションAPI

スキルシミュレーションAPIでは、スキルの開発者がスキルをシミュレートできます。スキルをテストして、シミュレートされたデバイスが返すインテントを対話モデルから確認できます。APIでは、インテントのデバッグはJSON応答で返されたconsideredIntentsを返し、候補に挙がったが破棄されたインテントを表示します。この情報を使用して、意図したインテントとスロットに発話を解決するようにモデルをトレーニングするために、追加のサンプルをどのように使用するか決めることができます。特定の発話をテストして、その応答を対話モデルの改善に役立てるには、発話プロファイラーAPIを使用することもできます。

成功した場合の応答のヘッダーには、シミュレーションリソースの場所が含まれます。この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は、スキルのテストにのみ使用します。

スキルシミュレーションAPIリクエスト
- HTTPメソッドとパス
- リクエスト
スキルシミュレーション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

応答本文

{
    "id": "34b178945-6...3456ab",
    "status": "SUCCESSFUL",
    "result": {
        "skillExecutionInfo": {
            "invocations": [{
                "invocationRequest": {
                    "endpoint": "arn:aws:lambda:us-east-1:032174894474:function:TRIPSCHEDULER",
                    "body": {
                        "version": "1.0",
                        "session": {
                            "new": false,
                            "sessionId": "amzn1.echo-api.session.bff866a1-ddeb-4e08-94c1-33dfe06fc090",
                            "application": {
                                "applicationId": "amzn1.ask.skill.ceed0aea-6715-4188-9bcd-018fbc2cbb33"
                            },
                            "user": {
                                "userId": "amzn..DKTRAPY"
                            }
                        },
                        "context": {
                            "AudioPlayer": {
                                playerActivity": "IDLE"
                            },
                            "Display": {
                                "token": ""
                            },
                            "System": {
                                "application": {
                                    "applicationId": "amzn1.ask.skill.ceed0aea-6715-4188-9bcd-018fbc2cbb33"
                                },
                                "user": {
                                    "userId": "amzn1.ask.accoun.."
                                },
                                "device": {
                                    "deviceId": "amzn1.ask.device...",
                                    "supportedInterfaces": {
                                        "AudioPlayer": {},
                                        "Display": {
                                            "templateVersion": "1.0",
                                            "markupVersion": "1.0"
                                        }
                                    }
                                },
                                "apiEndpoint": "https://api.amazonalexa.com",
                                "apiAccessToken": ""
                            }
                        },
                        "request": {
                            "type": "IntentRequest",
                            "requestId": "amzn1.echo-api.request.a2d2714b-e92f-4bdb-a722-9a5cd37fcfa8",
                            "timestamp": "2018-05-08T19:13:59Z",
                            "locale": "ja-JP"
                            "intent": {
                                "name": "BookFlightIntent",
                                "confirmationStatus": "CONFIRMED",
                                "slots": {
                                    "fromCity": {
                                        "name": "fromCity",
                                        "confirmationStatus": "CONFIRMED"
                                    },
                                    "toCity": {
                                        "name": "toCity",
                                        "confirmationStatus": "CONFIRMED"
                                    },
                                    "travelDate": {
                                        "name": "travelDate",
                                        "confirmationStatus": "NONE"
                                    },
                                    "airline": {
                                        "name": "airline",
                                        "confirmationStatus": "NONE"
                                    }
                                }
                            },
                            "dialogState": "STARTED"
                        }
                    }
                },
                "invocationResponse": {
                    "body": {
                        "version": "1.0",
                        "response": {
                            "directives": [{
                                "type": "Dialog.Delegate"
                            }],
                            "shouldEndSession": false
                        },
                        "sessionAttributes": {}
                    }
                },
                "metrics": {
                    "skillExecutionTimeInMilliseconds": 32
                }
            }]
        },
        "alexaExecutionInfo": {
            "alexaResponses": [{
                    "type": "Speech",
                    "content": {
                        "caption": "You flight has been booked."
                    }
                }],
            "consideredIntents": [{
                "name": "BookFlightIntent",
                "confirmationStatus": "CONFIRMED",
                "slots": {
                    "fromCity": {
                        "name": "fromCity",
                        "value": "神戸",
                        "confirmationStatus": "CONFIRMED",
                        "resolutions": {
                            "resolutionsPerAuthority": [{
                                "authority": "skillId + AMAZON.City",
                                "status": {
                                    "code": ER_SUCCESS_MATCH
                                },
                                "values": [{
                                    "value": {
                                        "name": "神戸",
                                        "id": "UID"
                                    }
                                }]
                            }]
                        }
                    },
                    "toCity": {
                        "name": "toCity",
                        "value": "福 岡",
                        "confirmationStatus": "CONFIRMED",
                        "resolutions": {
                            "resolutionsPerAuthority": [{
                                "authority": "skillId + AMAZON.City",
                                "status": {
                                    "code": ER_SUCCESS_MATCH
                                },
                                "values": [{
                                    "value": {
                                        "name": "福 岡",
                                        "id": "UID"
                                    }
                                }]
                            }]
                        }
                    },
                    "travelDate": {
                        "name": "travelDate",
                        "value": "2月 9日",
                        "confirmationStatus": "NONE",
                        "resolutions": {
                            "resolutionsPerAuthority": [{
                                "authority": "skillId + AMAZON_DATE",
                                "status": {
                                    "code": ER_SUCCESS_MATCH
                                },
                                "values": [{
                                    "value": {
                                        "name": "2月 9日",
                                        "id": "UID"
                                    }
                                }]
                            }]
                        }
                    },
                    "airline": {
                        "name": "airline",
                        "value": "MyOwn",
                        "confirmationStatus": "NONE",
                        "resolutions": {
                            "resolutionsPerAuthority": [{
                                "authority": "skillId + myAirlines",
                                "status": {
                                    "code": ER_SUCCESS_MATCH
                                },
                                "values": [{
                                    "value": {
                                        "name": "MyOwn",
                                        "id": "UID"
                                    }
                                }]
                            }]
                        }
                    }
                }
            }]
        },
        "error": null
    }
}

スキルシミュレーション応答のサンプル（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を呼び出すにはスキルを有効にしてください。"
    }
  }
}