SMAPI v0からv1への移行

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