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



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

スキルシミュレーション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リクエスト

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.skillExecutionTimeInMillisecondsAWS 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を呼び出すにはスキルを有効にしてください。"
    }
  }
}
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment