SMAPI v0からv1への移行
スキル管理APIバージョン1（SMAPI v1）を使うと、スキルとそのサブリソースの詳細情報を取得し、さらに詳細な操作を実行できるようになります。API呼び出しのインターフェースは大幅に変更されましたが、バージョン1とバージョン0には互換性があります。ですが、可能であれば、SMAPI v1に移行されることをおすすめします。コードで使用した各操作については、SMAPI v1のドキュメントを参照し、更新内容をご確認ください。
SMAPI v0とSMAPI v1の変更内容は以下のとおりです。
名前の変更
v0のリクエストおよび応答で使用していたskillManifestキーが、v1ではmanifestという名前に変更されました。
APIに対する変更
スキルの操作
各APIの詳細については、スキルの操作を参照してください。
SMAPI v1では、ステージの入力が必要なすべてのGET操作で使用するstage値で、developmentとlive（大文字小文字の区別あり）が使用できるようになりました。それ以外の操作では、stageにはdevelopment（大文字小文字の区別あり）のみが使用できます。SMAPI v0は暗黙的にdevelopmentステージのみを扱うため、stageパラメーターは使われません。
スキルの作成
-
v0: POST /v0/skills
-
v1: POST /v1/skills
スキルマニフェストの取得
-
v0: GET /v0/skills/{skillId}
-
v1: GET /v1/skills/{skillId}/stages/{stage}/manifest
新しいエラー応答：
HTTP/1.1 303 See Other（このAPIが呼び出された場合、およびスキル作成がまだ完了していない場合。）
スキルの更新
-
v0: PUT /v0/skills/{skillId}
-
v1: PUT /v1/skills/{skillId}/stages/{stage}/manifest
新しいエラー応答：
-
HTTP/1.1 409 Conflict（既に処理中の更新がある場合。） -
HTTP/1.1 403 Forbidden（リクエストを完了できない場合。）
スキルステータスの取得
バージョン1では、interactionModelに加えてmanifestステータスを返します。また、オプションでリソース（interactionModelまたはmanifest）ごとのフィルタリングもサポートします。
-
v0: /v0/skills/{skillId}/status
-
v1: /v1/skills/{skillId}/status?resource=name1&resource=name2
応答のlastModifiedキーの名前がlastUpdateRequestに変更されました。lastUpdateRequestでは‘time’フィールドは返されません。v0でのerrorフィールドは、v1ではerrorsに置き換えられました。これはerrorオブジェクトのリストです。
スキルステータスの取得を参照してください。
スキルの削除
-
v0: DELETE /v0/skills/{skillId}/
-
v1: DELETE /v1/skills/{skillId}/
新しいエラー応答：
v0でのHTTP/1.1 400 Bad Requestに代わり、SMAPI v1では、liveステージのスキルがある場合、スキルが審査中、またはモデルがビルド中の場合にHTTP/1.1 403 Forbiddenが返されます。
スキルリストの表示
バージョン1では、venderIdのスキルをページごとに取得する代わりに、オプションで特定のvenderIdを指定して、スキルリストを取得することができます。
-
v0: GET /v0/skills?vendorId={vendorId}&maxResults={num}&nextToken={token}
-
v1: GET /v1/skills?vendorId={vendorId}&maxResults={num}&nextToken={token}またはGET /v1/skills?vendorId={vendorId}&skillId={skillId1}&skillId={skillId2}
追加のスキル情報フィールド（apisとpublicationStatus）が応答に含まれるようになりました。
アカウントリンク
アカウントリンク操作APIで、stageパラメーターを使用できるようになりました。詳細については、アカウントリンクの管理を参照してください。
accountLinkingRequest構造体でredirectUrlsフィールドを使用できるようになりました。詳細については、アカウントリンクのリクエストを参照してください。
アカウントリンクパートナーの取得
-
v0: GET /v0/skills/{skillId}/accountLinkingClient
-
v1: GET /v1/skills/{skillId}/stages/{stage}/accountLinkingClient
応答のAccountLinkingInformationには、defaultTokenExpirationInSecondsという新しいフィールドが含まれます。このフィールドはaccessTokenの有効期間（秒数）を表します。OAuthクライアントが「expires_in」を返す場合、defaultTokenExpirationInSecondsがこのパラメーターで上書きされます。
アカウントリンクパートナーの設定
-
v0: PUT /v0/skills/{skillId}/accountLinkingClient
-
v1: PUT /v1/skills/{skillId}/stages/{stage}/accountLinkingClient
スキルが審査中の場合、バージョン0はHTTP/1.1 400 Bad Requestをスローしますが、バージョン1はHTTP/1.1 403 Forbiddenをスローします。
アカウントリンクパートナーの削除
v1から新たに追加されました。
- v1: DELETE /v1/skills/{skillId}/stages/{stage}/accountLinkingClient
スキル有効化の操作
これは、開発者コンソールではなく、プログラムからスキル有効化を管理できるAPIで、v1から新たに追加されました。スキル有効化の操作を参照してください。
対話モデルの操作
対話モデル操作APIで、stageをパラメーターとして使用できるようになりました。詳細については、対話モデルの操作を参照してください。
GET対話モデル
-
v0: GET /v0/skills/{skillId}/interactionModel/locales/{locale}
-
v1: GET /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}
HEAD対話モデル
-
v0: HEAD /v0/skills/{skillId}/interactionModel/locales/{locale}
-
v1: HEAD /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}
成功した場合のステータスコードが以下のように変更されました。
-
v0:
HTTP/1.1 200 OK -
v1:
HTTP/1.1 204 No Content
更新のための対話モデル
対話モデル更新に使用するメソッドが変更されました。
-
v0: POST /v0/skills/{skillId}/interactionModel/locales/{locale}
-
v1: PUT /v1/skills/{skillId}/stages/{stage}/interactionModel/locales/{locale}
APIは、リクエストを完了できない場合にHTTP/1.1 403 Forbiddenを返します。
対話モデルの開発ステータス
SMAPI v1では、対話モデルの開発ステータスを取得する専用のAPIはありませんが、‘get skill status’ APIで取得できます。スキルステータスの取得を参照してください
v1のAPIは入力値にlocaleを使用しないため、取得可能なすべてのロケールのステータスを返します。最後の対話モデルのビルドが正常に行われた場合のstatus値が、v0のSUCCESSからv1のSUCCEEDEDに変更されました。
-
v0: GET /v0/skills/{skillId}/interactionModel/locales/{locale}/status
-
v1: GET /v1/skills/{skillId}/status?resource=interactionModel
スキル認定の操作
エラー応答がHTTP/1.1 400 Bad RequestからHTTP/1.1 403 Forbiddenに変更されました。詳細については、スキル認定操作を参照してください。
スキルの認定を申請する
v0: POST /v0/skills/{skillId}/submit
v1: POST /v1/skills/{skillId}/submit
スキルの認定申請を取り消す
v0: POST /v0/skills/{skillId}/withdraw
v1: POST /v1/skills/{skillId}/withdraw
ASK CLIの変更
このページで説明したSMAPI v1の変更はすべて、ASK CLIコマンドリファレンスも対応しています。
