リソーススキーマの情報と検証

Alexa Skills Kitコマンドラインインターフェース（ASK CLI）またはAlexaスキル管理API（SMAPI）を使用してAlexaスキルを管理できます。Alexaスキルは、スキーマに準拠したスキルマニフェストで表されます。スキーマが正しくないと、スキルマニフェストを引数として必要とするCLIまたはSMAPIコマンドを呼び出すときにエラーが発生することがあります。

ASK SDKとツールキットを使用してスキルを管理することもできます。ローカルでスキルを操作する場合は、ディレクトリ構造に準拠したスキルパッケージとして表されます。ディレクトリ構造が正しくないと、スキルパッケージを操作しようとしたときにエラーが発生することがあります。

スキーマ情報はスキルに固有の情報です。たとえば、ベータプログラムに参加している場合、自分のスキルのマニフェストには、そのベータプログラムに固有のデータが必要になることがありますが、他の類似スキルのマニフェストには必要ありません。CLIまたはSMAPIコマンドを呼び出す前、あるいはスキルパッケージをローカルで操作する前に、スキルが必要とするスキーマまたはディレクトリ構造に関する情報を取得できます。この情報を使用して、エラーが発生する前にスキーマまたはディレクトリ構造を検証できます。

このドキュメントでは、resourceSchema APIについて説明します。また、get-resource-schema CLIコマンドを使用すると、スキーマとスキルパッケージの情報を取得できます。

リソーススキーマを取得する

リソーススキーマ取得リクエスト

スキルリソースのスキーマ情報をリクエストするには、api.amazonalexa.com/v1/skills/resourceSchema/にGETリクエストを送信します。ヘッダーにはアクセストークンが含まれている必要があります。詳細については、SMAPIで使用するアクセストークンの取得方法を参照してください。

リソーススキーマ取得リクエストの例

GET / HTTP/1.1
Host: api.amazonalexa.com/v1/skills/resourceSchema/<リソース>?operation=<オペレーション名>&vendorId=<ベンダーID>
Content-type: application/json
Accept: application/json
Authorization: <アクセストークン>
{
}

リソーススキーマ取得リクエストのパラメーター

パラメーター	説明	型	必須
`resource`	情報を要求するリソースです。`manifest`、`skillPackageStructure`のいずれかです。	文字列	◯
`operation`	マニフェストスキーマを必要とするオペレーションです。マニフェストスキーマは、オペレーションによって異なります。たとえば、スキルを認定のために提出する場合、スキルの初回作成時よりも多くのスキーマ検証が必要となります。次のいずれかです：`CREATE_SKILL`, `UPDATE_SKILL`, `ENABLE_SKILL`, `SUBMIT_SKILL`	文字列	◯（`resource`に`manifest`を指定した場合）。
`vendorId`	アクセスできるベータ機能に固有のスキーマを含めるには、ベンダーIDを指定します。	文字列	◯

リソーススキーマ取得の応答

リソーススキーマ取得の応答の例

HTTP/1.1 200 OK
Content-Type: application/json
Location: v1/skills/resourceSchema/manifest
{
  "expiryTime": "2020-10-29T06:38:35.549Z", 
  "schemaLocationUrl": "<url>"
}

リソーススキーマ取得の応答のフィールド

フィールド	説明	型
`schemaLocationUrl`	スキーマ情報は、署名付きURLで提供されます。情報が含まれているURLは60分間有効です。	文字列
`expiryTime`	URLの有効期限です。UTCで指定されます。	文字列はISO 8601形式で、YYYY-MM-DDThh:mm:ssZとなります。

エラー

次の表は、受け取ることができるエラーステータスコードの一覧です。

HTTP応答のステータスコード	説明
`400 Bad Request`	メッセージが無効です。原因としては、フィールドがない、値が正しくない、正しいJSON形式ではないことが考えられます。
`401 Unauthorized`	有効期限が切れているか、形式が正しくないため、アクセストークンが無効です。トークンを更新して、リクエストを再試行してください。
`403 Forbidden`	指定した`vendorId`にアクセスする権限がありません。
`429 Too Many Requests`	リクエスト数が多すぎます。リクエストを最大3回再送します。再送の間隔は、1秒以上空けます。
`500 Internal Server Error`	Alexaでエラーが発生したため、メッセージを処理できませんでした。メッセージを最大3回再送します。再送の間隔は、1秒以上空けます。