スキルの検証



スキル検証API

Alexaスキル検証APIは、スキルの開発者がスキル認定を申請する前や開発中の見直しテストとして随時、スキルを検証するために使用できます。正常な応答には、検証の成功と失敗の結果の両方が含まれます。Alexaスキル検証APIは、開発中のスキル編集が公開中スキルへの即時更新の対象かどうかも判断します。

このAPIのエンドポイントは、https://api.amazonalexa.comです。すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値はLogin with Amazonから取得したアクセストークンでなければなりません。

POST

検証のためにスキル検証APIに対してスキルを送信します。

HTTP/1.1

POST /v1/skills/{skillId}/stages/{stage}/validations
フィールド 説明 パラメーターの型 必須
skillId 一意のスキルIDです。 文字列
stage スキルのステージです。「development」、「live」のいずれかです。 文字列

stage値により、検証されるスキルのステージが決まります。

リクエスト

リクエストヘッダー

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

リクエスト本文

  {
    "locales": [Array of strings]
  }
フィールド オプション 説明
locales 検証対象のロケール(複数可)です。すべてのロケールでサポートされています。

応答

応答のヘッダー

  Content-Type: application/json
  Location: /skills/{skillId}/stages/{stage}/validations/{validationId}
  X-Amzn-RequestId: string

応答本文

  {
    "id": string,
    "status": "IN_PROGRESS"
  }

応答の例外(202以外)

  {
   "id": string,
   "message": string
  }

開発スキルを使ったスキルのサンプルリクエスト

POST /v1/skills/1234/stage/development/validations
  Content-Type: application/json
  Accept: application/json
  X-Amzn-RequestId: 11111111-1111-1111-1111-111111111111
  Authorization: MYTOKEN
  {
    "locales": ["ja-JP"]
  }

開発中ステージのスキルへのサンプル応答

HTTP 200 OK(処理中)

  Content-Type: application/json
  Location: /skills/22222222-2222-2222-2222-222222222222/stage/development/validations/33333333-3333-3333-3333-333333333333
  X-Amzn-RequestId: 11111111-1111-1111-1111-111111111111
  {
    "id": "33333333-3333-3333-3333-333333333333",
    "status": "IN_PROGRESS",
    "result": null
  }

HTTP 500 Internal Server Error

  Content-Type: application/json
  X-Amzn-RequestId: 11111111-1111-1111-1111-111111111111
  {
    "message": "An error occurred."
  }

GET

GETにより、スキル検証の結果が取得されます。

HTTP/1.1

GET /v1/skills/{skillId}/stages/{stage}/validations/{validationId}
フィールド 説明 パラメーターの型 必須
skillId 一意のスキルIDです。 パス
stage スキルのステージです。「development」、「live」のいずれかです。 文字列

stage値により、検証されるスキルのステージが決まります。

サンプルリクエストと成功応答の例については、サポートされる検証を参照してください。

リクエスト

リクエストヘッダー

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

リクエスト本文

本文は空です。

応答

応答のヘッダー

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

応答本文

  {
    "id": string,
    "status": string enum["IN_PROGRESS", "SUCCESSFUL", "FAILED"],
    "result": {
      "validations": [
        {
          "title": string,
          "description": string,
          "category": string,
          "locale": string,
          "status": string enum["SUCCESSFUL", "FAILED"],
          "importance": string enum["REQUIRED", "RECOMMENDED"]
        }
      ],
      "error": {
        "message": string
      }
    }
  }
フィールド 説明
id このリクエスト用に生成されたUUIDです。
status この検証の現在のステータスです。「FAILED」は、何らかの検証に「失敗した」場合、またはエラーが発生した場合に返されます。
validations -> title 検証のタイトルです。
validations -> description 検証の簡単な説明を添えた読める形式の説明です。
validations -> category ピリオドで区切られたカテゴリーの文字列です。
validations -> locale 指定の検証を行うロケールです。
validations -> status 指定の検証のステータスを表します。
validations -> importance 指定の検証の重要度です。
error -> code 外部からの参照が可能なエラーコードです。
error -> message ユーザーが読める形式の検証メッセージです。

応答の例外(200以外)

  {
   "id": string,
   "message": string
  }
フィールド 説明
message ユーザーが読める形式のエラー詳細です。

応答コードを参照してください。

HTTP 200 OK(処理中)

このサンプル応答は、最終的な応答が処理中でまだ取得できないことを表しています。

  Content-Type: application/json
  X-Amzn-RequestId: 11111111-1111-1111-1111-111111111111
  {
    "id": "333-3333-3333-3333-333",
    "status": "IN_PROGRESS",
    "results": null
  }

HTTP 404 Not Found

リクエストされたスキルの検証が見つかりませんでした。

  Content-Type: application/json
  X-Amzn-RequestId: 11111111-1111-1111-1111-111111111111
  {
    "message": "No validation found for given id."
  }

HTTP 200 OK(失敗)

検証の実行に失敗しました。

  Content-Type: application/json
  X-Amzn-RequestId: 11111111-1111-1111-1111-111111111111
  {
    "id": "33333333-3333-3333-3333-333333333333",
    "status": "FAILED",
    "result": {
      "error": {
        "message": "Skill Validation Not Allowed"
      }
    }
  }

応答コード

リクエスト 応答
202 スキルの検証が正常に開始されました。
403 APIユーザーに権限がないか、現在このAPIの呼び出しを許可されていません。
404 指定されたスキル、ステージ、検証は存在しません。エラー応答には見つからなかった具体的なリソースの種類を表す詳細が含まれます。
409 このリクエストは現在処理中の別のリクエストと競合しています。
429 APIユーザーが許容されるリクエストレートを超えました。
500 内部サーバーエラーです。

サポートされる検証

このセクションでは、スキル検証APIによって実行される検証について説明します。

以下の表は、スキル検証APIがどのように検証リクエストの全体的な成功または失敗ステータスを判断するかを表しています。

validations->importancevalidations->status全体的なステータス
推奨/必須成功成功
推奨失敗成功
必須失敗失敗

importanceが「RECOMMENDED」のテストのステータスが「FAILED」であっても、importanceが「REQUIRED」でステータスが「FAILED」のテストがなければ、全体的なステータスは「SUCCESSFUL」となります。

サンプルフレーズの検証

スキル検証のサンプルリクエスト

  GET /skills/22-22222/stage/development/validations/333-3333-3333-3333-333

  Content-Type: application/json
  Accept: application/json
  X-Amzn-RequestId: 11111111-1111-1111-1111-111111111111
  Authorization: MYTOKEN

本文は空です。

スキル検証のサンプル応答

HTTP 200 OK(成功)と応答全文

  Content-Type: application/json
  X-Amzn-RequestId: 11111111-1111-1111-1111-111111111111
{
  "id": "11111111-1111-1111-1111-111111111111",
  "status": "SUCCESSFUL",
  "result": {
    "validations": [
      {
        "locale": "ja-JP",
        "title": "Not enough example phrases provided",
        "description": "Required: Provide at least 1 example phrase",
        "status": "SUCCESSFUL",
        "importance": "REQUIRED"
      },
      {
        "locale": "ja-JP",
        "title": "Too many Example Phrases provided",
        "description": "Please limit your entry to a maximum of 3 example phrases.",
        "status": "SUCCESSFUL",
        "importance": "REQUIRED"
      },
      {
        "locale": "ja-JP",
        "title": "Example Phrase has duplicate phrases",
        "description": "Your example phrases must not be duplicates.Please provide unique entries.",
        "status": "SUCCESSFUL",
        "importance": "REQUIRED"
      },
      {
        "locale": "ja-JP",
        "title": "Example Phrase too short",
        "description": "Your example phrase does not meet the minimum character limit of 2 characters.",
        "status": "SUCCESSFUL",
        "importance": "REQUIRED"
      },
      {
        "locale": "ja-JP",
        "title": "Example Phrase exceeds maximum length",
        "description": "Your example phrase has exceeded the maximum character limit of 200 characters.",
        "status": "SUCCESSFUL",
        "importance": "REQUIRED"
      },
      {
        "locale": "ja-JP",
        "title": "Example Phrase contains special characters",
        "description": "Example phrases can only contain apostrophes, quotation marks, question marks, periods, exclamation points, and commas.",
        "status": "SUCCESSFUL",
        "importance": "REQUIRED"
      },
      {
        "locale": "ja-JP",
        "title": "Example Phrase cannot be blank",
        "description": "The example phrase may not be left empty.At least one example phrase must exist.",
        "status": "SUCCESSFUL",
        "importance": "REQUIRED"
      },
      {
        "locale": "ja-JP",
        "title": "Example Phrase must start with Wake Word",
        "description": "The example phrase must start with a valid wake word. (i.e. Alexa).",
        "status": "SUCCESSFUL",
        "importance": "REQUIRED"
      },
      {
        "locale": "ja-JP",
        "title": "Example Phrase must contain invocation name",
        "description": "Your example phrase must contain the invocation name: [reindeer skill].",
        "status": "FAILED",
        "importance": "RECOMMENDED"
      },
      {
        "locale": "ja-JP",
        "title": "Example Phrase must contain invocation name",
        "description": "Your example phrase must contain the invocation name: [reindeer skill].",
        "status": "FAILED",
        "importance": "RECOMMENDED"
      },
      {
        "locale": "ja-JP",
        "title": "Example Phrase too short",
        "description": "Your example phrase does not meet the minimum character limit of 2 characters.",
        "status": "SUCCESSFUL",
        "importance": "REQUIRED"
      },
      {
        "locale": "ja-JP",
        "title": "Example Phrase exceeds maximum length",
        "description": "Your example phrase has exceeded the maximum character limit of 200 characters.",
        "status": "SUCCESSFUL",
        "importance": "REQUIRED"
      },
      {
        "locale": "ja-JP",
        "title": "Example Phrase contains special characters",
        "description": "Your example phrase must not contain special characters.However, '[@, !, #, $, %, &, (, ), *, /, :, {, [, ;, |, \, <, }, ], ^, >, _]' was found.",
        "status": "SUCCESSFUL",
        "importance": "REQUIRED"
      },
      {
        "locale": "ja-JP",
        "title": "Example Phrase must contain invocation name",
        "description": "Your example phrase must contain the invocation name: [reindeer skill].",
        "status": "FAILED",
        "importance": "RECOMMENDED"
      },
      {
        "locale": "ja-JP",
        "title": "Example Phrase too short",
        "description": "Your example phrase does not meet the minimum character limit of 2 characters.",
        "status": "SUCCESSFUL",
        "importance": "REQUIRED"
      },
      {
        "locale": "ja-JP",
        "title": "Example Phrase exceeds maximum length",
        "description": "Your example phrase has exceeded the maximum character limit of 200 characters.",
        "status": "SUCCESSFUL",
        "importance": "REQUIRED"
      },
      {
        "locale": "ja-JP",
        "title": "Example Phrase contains special characters",
        "description": "Your example phrase must not contain special characters.However, '[@, !, #, $, %, &, (, ), *, /, :, {, [, ;, |, \\, <, }, ], ^, >, _]' was found.",
        "status": "SUCCESSFUL",
        "importance": "REQUIRED"
      },
      {
        "locale": "ja-JP",
        "title": "Example Phrase must contain invocation name",
        "description": "Your example phrase must contain the invocation name: [reindeer skill].",
        "status": "FAILED",
        "importance": "RECOMMENDED"
      }
    ]
  }
}

公開中スキルへの即時更新のサンプル応答

このセクションでは、スキル検証APIによって実行される公開中スキルの検証について説明します。このAPIは、スキルが即時更新の対象であるかを判断します。

公開中スキルの成功サンプル応答

以下のサンプルは、スキルが即時更新の対象である場合の応答を示しています。

{
  "title": "Eligibility to update your live skill instantly",
  "description": "Your skill contains changes that make it eligible to update your live skill instantly.For more information see https://www.amazon.com/alexa/updateyourliveskillinstantly",
  "status": "SUCCESSFUL",
  "importance": "RECOMMENDED"
}

公開中スキルの失敗サンプル応答

以下のサンプルは、スキルが即時更新の対象でない場合の応答を示しています。

{
  "title": "Eligibility to update your live skill instantly",
  "description": "Your skill contains changes that make it ineligible to update your live skill instantly.For more information see https://www.amazon.com/alexa/updateyourliveskillinstantly",
  "status": "FAILED",
  "importance": "RECOMMENDED"
}