スキルの認定と公開



スキルの認定と公開

 

Alexaスキルの認定および公開を管理するには、スキル管理API(SMAPI)の次のAPI操作を使用します。認定のリクエストと公開のリクエストを分けることも、1つのリクエストで両方を実行することもできます。これらを分ける場合は、Alexaスキルストアへのスキルの公開日を管理できます。

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

スキルを認定および公開のために申請する

スキルを認定に申請し、必要に応じて公開の設定をします。

リクエスト

POST /v1/skills/{skillId}/submit

パラメーター

フィールド 説明 パラメーターの型 必須
skillId 一意のスキルIDです。 パス
versionMessage スキルバージョンを識別するカスタムメッセージ。最大300文字です。 文字列

リクエスト本文

任意です。省略した場合、または publicationMethodAUTO_PUBLISHINGに設定すると、スキルの認定後に自動的に公開されます。 MANUAL_PUBLISHINGに設定した場合は、スキルが認定された後、 publish-skillコマンドを使用してスキルを公開するタイミングを指定できます。

{
  "publicationMethod": "MANUAL_PUBLISHING"
}
フィールド 説明 パラメーターの型 必須
publicationMethod 以下のいずれかになります。 AUTO_PUBLISHING, MANUAL_PUBLISHING 文字列

応答

HTTP/1.1 202 Accepted

ヘッダー

Location: "<申請ステータスを追跡するための相対パス>"

例外

HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable

認定済みスキルの公開

認定されたスキルを公開します。公開日を設定することも、即時に公開することもできます。

レスポンスをローカライズするためには、各APIリクエストのAccept-Languageヘッダーをen-US または ja-JPのいずれかにする必要があります。

リクエスト

POST /v1/skills/{skillId}/publications

パラメーター

フィールド 説明 パラメーターの型 必須
skillId 一意のスキルIDです。 パス

リクエスト本文

任意です。指定しない場合、即時に公開されます。指定する場合、公開日を6か月以内の範囲で設定できます。

{
  "publishesAt": “2019-11-01T00:38:29.708Z”
}
フィールド 説明 パラメーターの型 必須
publishesAt 時刻をUTC形式で指定します。 文字列

応答

HTTP/1.1 202 Accepted

応答本文

レスポンス本文は、公開日と現在のステータスを返します。返されるステータス値は、次のとおりです。 IN_PROGRESS, SUCCEEDED, FAILED, CANCELLED, SCHEDULED.

{
  "publishesAt": “2019-11-01T01:51:23.113Z”,
  "status": "IN_PROGRESS"
}

例外

HTTP/1.1 400 Invalid
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable

認定済みスキルの最新の公開設定を取得する

認定済みスキルの最新の公開設定の詳細(公開日と現在の公開状況など)を取得します。

レスポンスをローカライズするためには、各APIリクエストのAccept-Languageヘッダーをen-US または ja-JPのいずれかにする必要があります。

リクエスト

GET /v1/skills/{skillId}/publications/~latest

パラメーター

フィールド 説明 パラメーターの型 必須
skillId 一意のスキルIDです。 パス

リクエスト本文

なし

応答

HTTP/1.1 202 Accepted

応答本文

レスポンス本文は、公開日と現在のステータスを返します。返されるステータス値は、次のとおりです。 IN_PROGRESS, SUCCEEDED, FAILED, CANCELLED, SCHEDULED.

{
  "publishesAt": “2019-11-01T02:03:07.023Z”,
  "status": "IN_PROGRESS"
}

例外

HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable

スキルの認定審査のリストを取得する

スキルのすべての完了済み、または進行中の認定審査のリストを取得します。

リクエスト

GET /v1/skills/{skillId}/certifications

パラメーター

フィールド 説明 パラメーターの型 必須
skillId 一意のスキルIDです。 パス
nextToken 省略された応答を受け取った後、認定審査の詳細を取得するためにこのパラメーターを使用します。省略された応答に含まれるnextTokenの値を設定します。 クエリ
maxResults 応答で返される項目の最大数です。このパラメーターを含めない場合は、デフォルトの最大値は50です。このパラメーターを含める場合は、指定した値よりも少ない項目が応答に含まれる場合もありますが、これを超える数の項目は含まれません。50を超える値を指定することはできません。 クエリ

応答

HTTP/1.1 200 OK

応答本文の構造(JSON)

{
  "_links": {
    "self": {
      "href": "string"
    },
    "next": {
      "href": "string"
    }
  },
  "isTruncated": false,
  "nextToken": "string",
  "totalCount": 1,
  "items": [
    {
      "id": "string",
      "status": "IN_PROGRESS",
      "skillSubmissionTimestamp": "2019-01-06T05:26:02.430Z",
      "reviewTrackingInfo": {
        "estimatedCompletionTimestamp": "2019-01-06T05:26:02.430Z",
        "actualCompletionTimestamp": "2019-01-06T05:26:02.430Z",
        "lastUpdated": "2019-01-06T05:26:02.430Z"
      }
    }
  ]
}

応答本文の要素

フィールド 説明 パラメーターの型
_links APIナビゲーションのリンクです。このフィールドの構造は、JSON Hypertext Application Languageの仕様(英語)で定義されています。 _links object (spec)
isTruncated 応答で返された項目よりも多くの項目がリストに存在するかどうかを示すフラグです。この値がtrueであれば、この応答のリストは省略されています。さらに多くの項目を取得するには、nextTokenフィールドの値を、次のリクエストのnextTokenパラメーターに渡します。 ブール値
nextToken isTruncatedがtrueの場合、この要素は存在し、次のリクエストのnextTokenパラメーターに使用する値が含まれます。 文字列
totalCount リクエストを満たす項目の総数です。この数字は、この応答で返される項目の数よりも多い場合があります。 整数
itemsオブジェクト
フィールド 説明 パラメーターの型
id 認定審査項目の一意のIDです。 文字列
status 認定審査のステータスです。ステータスは、IN_PROGRESSSUCCEEDEDFAILEDCANCELLEDのいずれかになります。 文字列
skillSubmissionTimestamp スキルが認定に申請された日時です。 日時とタイムスタンプはISO 8601形式です。
reviewTrackingInfoオブジェクト
フィールド 説明 パラメーターの型
estimatedCompletionTimestamp 認定審査が完了する予定の日時です。 日時とタイムスタンプはISO 8601形式です。
actualCompletionTimestamp 認定審査が完了した日時です。 日時とタイムスタンプはISO 8601形式です。
lastUpdated reviewTrackingInfoの値が最後に更新された日時です。 日時とタイムスタンプはISO 8601形式です。

例外

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Server Error

特定の認定審査の詳細を取得する

スキルの特定の認定審査についての詳細を取得します。

進行中の認定審査に対するリクエストは、常に応答を返しますが、以前の認定に対するリクエストの場合はその限りではありません。以前の認定についての詳細が取得できない場合は、ユーザーはHTTP 404 Not Found応答を受け取ります。

リクエスト

GET /v1/skills/{skillId}/certifications/{certificationId}

リクエストヘッダー

ローカライズされた応答を受け取る場合は、オプションでAccept-Languageヘッダーを追加することができます。ヘッダーの値をen-USまたはja-JPに設定できます。

パラメーター

フィールド 説明 パラメーターの型 必須
skillId 一意のスキルIDです。 パス
certificationId 取得する認定審査項目の一意のIDです。最新の認定審査項目を取得するには、~mostRecentの値を使用します。最新でない認定審査項目を取得するには、スキルの認定審査のリストを取得して、取得したい認定審査項目のIDを使用します。 パス

応答

HTTP/1.1 200 OK

応答本文の構造(JSON)

{
  "id": "string",
  "status": "IN_PROGRESS",
  "skillSubmissionTimestamp": "2019-01-06T21:54:09.730Z",
  "reviewTrackingInfo": {
    "estimatedCompletionTimestamp": "2019-01-06T21:54:09.730Z",
    "actualCompletionTimestamp": "2019-01-06T21:54:09.730Z",
    "lastUpdated": "2019-01-06T21:54:09.730Z",
    "estimationUpdates": [
      {
        "originalEstimatedCompletionTimestamp": "2019-01-06T21:54:09.730Z",
        "revisedEstimatedCompletionTimestamp": "2019-01-06T21:54:09.730Z",
        "reason": "string"
      }
    ]
  },
  "result": {
    "distributionInfo": {
      "publishedCountries": [
        "string"
      ],
      "publicationFailures": [
        {
          "reason": "string",
          "countries": [
            "string"
          ]
        }
      ]
    }
  }
}

応答本文の要素

フィールド 説明 パラメーターの型
id 認定審査項目の一意のIDです。 文字列
status 認定審査のステータスです。ステータスは、IN_PROGRESSSUCCEEDEDFAILEDCANCELLEDのいずれかになります。 文字列
skillSubmissionTimestamp スキルが認定に申請された日時です。 日時とタイムスタンプはISO 8601形式です。
reviewTrackingInfoオブジェクト
フィールド 説明 パラメーターの型
estimatedCompletionTimestamp 認定審査が完了する予定の日時です。 日時とタイムスタンプはISO 8601形式です。
actualCompletionTimestamp 認定審査が完了した日時です。 日時とタイムスタンプはISO 8601形式です。
lastUpdated reviewTrackingInfoの値が最後に更新された日時です。 日時とタイムスタンプはISO 8601形式です。
estimationUpdatesオブジェクト
フィールド 説明 パラメーターの型
originalEstimatedCompletionTimestamp 当初の認定審査が完了する見積もり日時です。 日時とタイムスタンプはISO 8601形式です。
revisedEstimatedCompletionTimestamp 更新後の認定審査が完了する予定の日時です。 日時とタイムスタンプはISO 8601形式です。
reason 当初の予定が更新された理由です。 文字列
distributionInfoオブジェクト
フィールド 説明 パラメーターの型
publishedCountries 認定審査が完了すると、スキルが公開された国の一覧が含まれます。ISO 3166-1 alpha-2に従って、各国は2文字の国コードで指定されます。 文字列のリスト
publicationFailures 認定審査が完了すると、スキルが公開さていない国と公開されなかった理由の一覧が含まれます。ISO 3166-1 alpha-2に従って、各国は2文字の国コードで指定されます。 reasoncountriesの値(文字列)の一覧

例外

HTTP/1.1 401 Unauthorized
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Server Error

すべてのスキルバージョンの一覧を取得する

すべてのスキルバージョンのリストを返します。認定済みスキルにのみ適用されます。

リクエスト

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

GET /v1/skills/{skillId}/versions

リクエストのパラメーター

フィールド 説明 パラメーターの型 必須
skillId 一意のスキルIDです。 オブジェクト
MaxResults ページごとに表示するスキルの最大数です。返される結果の最大数は50を超えることはできません。 クエリーパラメーター
nextToken MaxResultsのページ分割を制御する継続トークン。 クエリーパラメーター

応答

以下の例では、応答本文の構造を示します。

応答本文

{
  "_links": {
    "self": {
      "href": "/v1/skills/amzn1.ask.skill.04430552-6fdb-4a59-8588-93171d79fbb0/versions"
    }
  },
  "isTruncated": false,
  "skillVersions": [
    {
      "creationTime": "Wed Jul 01 23:20:11 UTC 2020",
      "message": "Updating the skill icon, and description message.",
      "submissions": [
        {
          "status": "LIVE",
          "submissionTime": "Wed Jul 01 23:20:11 UTC 2020"
        }
      ],
      "version": "2"
    },
    {
      "creationTime": "Wed Jul 01 22:46:16 UTC 2020",
      "message": "Initial submission, excited to try this new feature.",
      "submissions": [
        {
          "status": "CERTIFIED",
          "submissionTime": "Wed Jul 01 22:46:16 UTC 2020"
        }
      ],
      "version": "1"
    }
  ]
}

応答のパラメーター

フィールド 説明 パラメーターの型
skillVersions.version スキルのバージョン番号。 文字列
skillVersions.message スキルのバージョンを追跡するためのカスタムメッセージ。 文字列
skillVersions.creationTime スキルが認定審査に申請され、バージョンが作成された日時。 文字列
skillVersions.submissions ロールバックエラーに関する情報を含むオブジェクト。 文字列
skillVersions.submissions.status 申請のステータス。 文字列
skillVersions.submissions.submissionTime バージョンを申請した日時。 文字列

申請のステータス

フィールド 説明
LIVE スキルバージョンは公開中ステージにあります。
CERTIFIED 認定されたスキルのバージョンです。
IN_REVIEW スキルのバージョンは認定と公開のための審査中です。審査中は、コンフィギュレーションを編集できません。
FAILED CERTIFICATION スキルのバージョンは認定審査に合格しませんでした。新たなバージョンを申請してください。
HIDDEN スキルバージョンを公開しましたが、新しいユーザーは有効にできません。既存のユーザーは、最新バージョンであれば、このスキルを呼び出すことができます。
REMOVED スキルバージョンを公開しましたが、ポリシー違反により削除されました。スキルを更新し、新しいバージョンを公開することで、ポリシー違反に対処できます。
WITHDRAWN_FROM_CERTIFICATION スキルのバージョンは審査から取り下げられました。

スキルの認定申請を取り消す

認定プロセス中のスキルを取り消します。

リクエスト

POST /v1/skills/{skillId}/withdraw

本文

{
  "reason" : "OTHER",
  "message" : "TEST SKILL"
}

パラメーター

フィールド 説明 パラメーターの型 必須
skillId 一意のスキルIDです。 パス
reason 取り消しの理由は次のいずれかの列挙型で示します: TEST_SKILLMORE_FEATURESDISCOVERED_ISSUENOT_RECEIVED_CERTIFICATION_FEEDBACKNOT_INTEND_TO_PUBLISHOTHER リクエスト本文の要素
message reasonにOTHERを指定した場合、スキルを取り消す理由を示す文字列です。 リクエスト本文の要素 OTHERの場合は◯。それ以外は×。

応答

HTTP/1.1 204 No Content

例外

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable

公開中のスキルを非表示、または停止する

公開したスキルを非公開(非表示または停止)にするには、この操作を行います。

スキルを非公開にする場合、スキルを非表示、または停止にするかどうかを選択します。

操作が成功したことを示す応答を受け取った後、実際に非公開になるまで数日かかる場合があります。

スキルが非表示または削除された場合でも、 stage 値は引き続き liveになります。したがって、 live ステージは、現在公開されているスキル、非表示にされたスキルおよび削除されたスキルを指します。

非公開にした後で再公開するには、認定に再申請する必要があります。

リクエスト

POST /v1/skills/{skillId}/unpublish

本文

{
  "type": "string",
  "reason": "string"
}

パラメーター

フィールド 説明 パラメーターの型 必須
skillId 非公開にするスキルのIDです。 パス
type スキルを非表示にするか、停止するかを指定します。有効な値はHIDEおよびREMOVEです。詳細については、スキルを非表示または停止するを参照してください。 リクエスト本文の要素
reason スキルを非公開にする理由です。以下のいずれかの理由を選択します:
  • 呼び出し名の変更
  • 誤ってスキルを公開したため
  • スキルの保守に時間がかかるため
  • インフラストラクチャのコストが高すぎる
  • 技術的な問題
  • その他
リクエスト本文の要素

応答

HTTP/1.1 202 Accepted

本文

{
  "message": "string"
}

パラメーター

フィールド 説明 パラメーターの型
message 応答で返されたメッセージです。 応答本文の要素

例外

HTTP/1.1 400 Bad Request
HTTP/1.1 401 Unauthorized
HTTP/1.1 403 Forbidden
HTTP/1.1 404 Not Found
HTTP/1.1 429 Too Many Requests
HTTP/1.1 500 Internal Server Error
HTTP/1.1 503 Service Unavailable