スキルの呼び出し

スキル呼び出しAPI

スキル呼び出しAPIは、指定されたスキルのAWS LambdaまたはサードパーティのHTTPSエンドポイントを呼び出します。正常に完了した応答には、呼び出されたエンドポイントと、エンドポイントとの間で送受信されたペイロードの情報が含まれます。この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である必要があります。スキルエンドポイントへの呼び出しは、10秒後にタイムアウトします。

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

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

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

HTTPメソッドとパス

POST v2/skills/{skillId}/stages/{stage}/invocations

パラメーター

フィールド 説明 パラメーターの型 必須
skillId 一意のスキルIDです。 パス ◯
stage スキルのステージです。有効な値は、developmentとlive（大文字小文字の区別あり）です。 パス ◯

リクエスト

リクエストヘッダー

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

リクエスト本文

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

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

アトリビュート 説明
endpointRegion呼び出されるエンドポイントのリージョンです。「NA」、「EU」、「FE」のいずれかです。「Default」を使用すると、グローバルデフォルトエンドポイントが使用されます。
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エンドポイントが返したペイロードです。
skillExecutionTimeInMilliseconds AWS LambdaまたはHTTPSエンドポイントがリクエストを処理するのにかかった時間（ミリ秒）。

エラー

エラー応答本文

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

応答のエラーコード

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

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

HTTPメソッドとパス

POST /v2/skills/amzn1.ask.skill.a378ab7a-4545-407d-9b68-d0d0c6b75468/stages/development/invocations

リクエストヘッダー

Authorization：文字列（Login with Amazonアクセストークン）
Content-Type: application/json
Accept: application/json

リクエスト本文

{
  "endpointRegion": "JP",
  "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": "ハローワールド"
            },
            "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": "スキルのエンドポイントに対するリクエストがタイムアウトしました。"
    }
  }
}

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

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

応答ヘッダー

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

応答本文

{
  "message": "指定されたリージョンでエンドポイントが見つかりませんでした。"
}
このページは役に立ちましたか？