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コマンドリファレンスも対応しています。