スキル呼び出しAPI

スキル呼び出しAPI

スキル呼び出しAPIは、指定されたスキルのAWS LambdaまたはサードパーティのHTTPSエンドポイントを呼び出します。正常に完了した応答には、呼び出されたエンドポイントと、エンドポイントとの間で送受信されたペイロードの情報が含まれます。このAPIへのリクエストがエラーになった場合、応答に問題の詳細が記述されています。具体的なエラー内容がスキルエンドポイントの呼び出しの失敗である場合、応答にはエラーの発生とともにエンドポイントに何が送信されたかの詳細を示すステータスアトリビュートが含まれます。

SMAPI v1 APIはすべて、該当する場合に次のエラー応答をスローします。HTTP/1.1 429 TooManyRequestsException(リクエストが制限される場合)、HTTP/1.1 503(サービスが利用できない場合)。

この機能は、以下のロケールを使用するスキルではサポートされません。

  • en-AU
  • en-CA
  • en-IN
  • ja-JP

このAPIは、ユーザー自身が開発したスキルの呼び出しに使用できます。呼び出されるスキルが、開発者のアカウントで有効にされたもので、かつdevelopmentステージである必要があります。スキルエンドポイントへの呼び出しは、10秒後にタイムアウトします。

スキル呼び出しAPIは、スキルのテスト目的でのみ使用します。

関連トピック:Alexa Skills KitコマンドラインインターフェースとAlexaスキル管理APIの概要スキルシミュレーションAPI

スキル呼び出しAPIリクエスト

HTTPメソッドとパス

POST /v0/skills/{skillId}/invocations HTTP/1.1

リクエスト

リクエストヘッダー

Content-Type: application/json
Accept: application/json
X-Amzn-RequestId: string

リクエスト本文

{
  "endpointRegion": string enum["NA", "EU", etc],
  "skillRequest": {
    "body": object
  }
}

リクエストアトリビュートの定義

アトリビュート 説明
endpointRegion呼び出されるエンドポイントのリージョンです。「NA」、「EU」、「FE」のいずれかです。
skillRequest.bodyリクエスト本文の構文で定義されたASKリクエスト本文です

スキル呼び出しAPI応答

応答ヘッダー

Content-Type: application/json
X-Amzn-RequestId: string

応答本文

200 OK

 {
   "status": string enum["SUCCESSFUL", "FAILED"],
   "result": {
     "skillExecutionInfo": {
       "invocationRequest": {
         "endpoint": string,
         "body": object
       },
       "invocationResponse": {
         "body": object
       },
       "metrics": {
         "skillExecutionTimeInMilliseconds": integer
       }
     },
     "error": {
       "message": string
     }
   }
 }
アトリビュート 説明
statusスキル呼び出しのステータスを示す文字列です。SUCCESSFULまたはFAILEDになります。
invocationRequest.endpointスキルのAWS LambdaまたはHTTPSエンドポイントです
invocationRequest.bodyスキルのAWS LambdaまたはHTTPSエンドポイントに送信されたJSONペイロードです
invocationResponse.bodyスキルのAWS LambdaまたはHTTPSエンドポイントが返したペイロード
skillExecutionTimeInMillisecondsAWS LambdaまたはHTTPSエンドポイントがリクエストを処理するのにかかった時間(ミリ秒)

エラー

エラー応答本文

{
  "message": string
}
アトリビュート 説明
codeエラーメッセージにマッピングされるエラーコードです。各ロケールの開発者がこのコードに基づいて、エラー詳細を調べることができるようにしておく必要があります。
message読める形式でのエラー詳細です。

応答のエラーコード

応答 説明
400 Bad Request データが無効か、存在しません。
403 Forbidden APIユーザーにこのAPIを呼び出す権限がないか、現在このスキルの呼び出しを許可されていません。
404 Not Found 指定されたスキルが見つかりませんでした。

スキル呼び出しリクエストのサンプル

HTTPメソッドとパス

POST /v0/skills/amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123/invocations

リクエストヘッダー

Authorization: string (Login with Amazon access token)
Content-Type: application/json
Accept: application/json

リクエスト本文

{
  "endpointRegion": "NA",
  "skillRequest": {
    "body": {
      "version": "1.0",
      "session": {
        "new": true,
        "sessionId": "aaf7b112-434c-11e7-2563-6bbd1672c748",
        "application": {
          "applicationId": "amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123"
        },
        "attributes": {},
        "user": {
          "userId": "amzn1.ask.account.12345ABCDEFGH"
        }
      },
      "context": {
        "System": {
          "application": {
            "applicationId": "amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123"
          },
          "user": {
            "userId": "amzn1.ask.account.12345ABCDEFGH"
          }
        }
      },
      "request": {
        "type": "IntentRequest",
        "requestId": "c03faf54-684d-11e7-6249-6bbd1825c634",
        "timestamp": "2017-08-14T04:20:20Z",
        "locale": "en-US",
        "intent": {
          "name": "SayHello"
        }
      }
    }
  }
}

スキル呼び出し応答のサンプル(200 OK) - 成功

インテントリクエストに対する正常な応答です。

応答ヘッダー

HTTP 200 OK
Content-Type: application/json
X-Amzn-RequestId: <value>

応答本文

{
  "status": "SUCCESSFUL",
  "result": {
    "skillExecutionInfo": {
      "invocationRequest": {
        "endpoint": "arn:aws:lambda:us-east-1:123456789:function:HelloWorld",
        "body": {
          "version": "1.0",
          "session": {
            "new": true,
            "sessionId": "aaf7b112-434c-11e7-2563-6bbd1672c748",
            "application": {
              "applicationId": "amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123"
            },
            "attributes": {},
            "user": {
              "userId": "amzn1.ask.account.12345ABCDEFGH"
            }
          },
          "context": {
            "System": {
              "application": {
                "applicationId": "amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123"
              },
              "user": {
                "userId": "amzn1.ask.account.12345ABCDEFGH"
              }
            }
          },
          "request": {
            "type": "IntentRequest",
            "requestId": "c03faf54-684d-11e7-6249-6bbd1825c634",
            "timestamp": "2017-08-14T04:20:20Z",
            "locale": "en-US",
            "intent": {
              "name": "SayHello"
            }
          }
        }
      },
      "invocationResponse": {
        "body": {
          "version": "1.0",
          "sessionAttributes": {},
          "response": {
            "outputSpeech": {
              "type": "PlainText",
              "text": "hello, world"
            },
            "shouldEndSession": true
          }
        }
      },
      "metrics": {
        "skillExecutionTimeInMilliseconds": 100
      }
    },
    "error": null
  }
}

スキル呼び出し応答のサンプル(200 OK) - 失敗

HTTPコードは200 OKであるにもかかわらず内容がエラーである場合の応答です。スキルエンドポイントが制限時間である10秒を超えてタイムアウトしたことが原因です。

HTTP 200 OK
Content-Type: application/json
X-Amzn-RequestId: <value>
{
  "status": "FAILED",
  "result": {
    "skillExecutionInfo": {
      "invocationRequest": {
        "endpoint": "arn:aws:lambda:us-east-1:123456789:function:HelloWorld",
        "body": {
          "version": "1.0",
          "session": {
            "new": true,
            "sessionId": "aaf7b112-434c-11e7-2563-6bbd1672c748",
            "application": {
              "applicationId": "amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123"
            },
            "attributes": {},
            "user": {
              "userId": "amzn1.ask.account.12345ABCDEFGH"
            }
          },
          "context": {
            "System": {
              "application": {
                "applicationId": "amzn1.ask.skill.12345678-12d1-5b2b-a012-1d1f33311123"
              },
              "user": {
                "userId": "amzn1.ask.account.12345ABCDEFGH"
              }
            }
          },
          "request": {
            "type": "IntentRequest",
            "requestId": "c03faf54-684d-11e7-6249-6bbd1825c634",
            "timestamp": "2017-08-14T04:20:20Z",
            "locale": "en-US",
            "intent": {
              "name": "SayHello"
            }
          }
        }
      },
      "invocationResponse": null,
      "metrics": null
    },
    "error":  {
      "message": "Request to skill endpoint timed out."
    }
  }
}

スキル呼び出し応答のサンプル(400 不正なリクエスト)

この応答は、指定されたリージョンのエンドポイントが見つからなかった場合に返されます。

応答ヘッダー

HTTP 400 Bad Request
Content-Type: application/json
X-Amzn-RequestId: <value>

応答本文

{
  "message": "No endpoint was found for the specified region."
}