スキル内商品の管理



スキル内商品管理APIを使用して、開発者はAPI経由でスキルのスキル内商品を管理できます。スキル内商品は作成、更新、リスト化できます。スキル内商品とスキルを関連付けし、管理することもできます。

このAPIのエンドポイントは、https://api.amazonalexa.comです。すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値はLogin with Amazonから取得したアクセストークンでなければなりません。認証のしくみは他のスキル管理APIと同じです。

関連トピック：

• スキル内課金の概要
• ASK CLIを使用したスキル内商品の作成と編集
• 開発者コンソールでのスキル内商品の作成と編集
• Alexa Skills Kitコマンドラインインターフェースの概要

• 結果のページ分割とフィルタリング
• スキル内商品の定義を取得する
  • リクエスト
  • 応答
  • エラー
• 新しいスキル内商品を作成する
  • リクエスト
  • 応答
  • エラー
• スキル内商品の概要を取得する
  • リクエスト
  • 応答
  • エラー
• 既存のスキル内商品を更新する
  • リクエスト
  • 応答
  • エラー
• 既存のスキル内商品を削除する
  • リクエスト
  • 応答
  • エラー
• ベンダーのスキル内商品のリストを取得する
  • リクエスト
  • 応答
  • エラー
• 特定のスキルIDおよびステージのスキル内商品のリストを取得する
  • リクエスト
  • 応答
  • エラー
• スキル内商品に関連付けられたスキルのリストを取得する
  • リクエスト
  • 応答
  • エラー
• スキル内商品をスキルに関連付ける
  • リクエスト
  • 応答
  • エラー
• スキル内商品とスキルの関連付けを解除する
  • リクエスト
  • 応答
  • エラー
• 開発者アカウントの買い切り型購入をリセットする
  • リクエスト
  • 応答
  • エラー
• 応答の例外

結果のページ分割とフィルタリング

リストを戻すAPI呼び出しについては、オプションでmaxResultsを指定して1回で表示する結果の数を制御できます。また、nextTokenを指定して、後続のAPI呼び出しで次に表示される結果のセットを取得することもできます。このサンプルリクエストでは読みやすくするために改行を入れていますが、実際には改行を入れずにつなげてください。リストを返す一部のAPI呼び出しでは、フィルタリングを行う他のパラメーターも使用できます。

GET  /v1/skills/AAA-xxxx-yyyy/stages/development/inSkillProducts?
     nextToken=VWB111111111
     &maxResults=5

スキル内商品の定義を取得する

指定された商品IDのスキル内商品の定義を返します。

リクエスト

stageの値にはdevelopmentまたはliveを使用できます。

GET /v1/inSkillProducts/{productId}/stages/{stage}

応答

スキル内商品の定義を、スキル内商品マニフェストの形式で返します。

エラー

新しいスキル内商品を作成する

指定されたベンダーIDで新しいスキル内商品を作成します。

リクエスト

POST /v1/inSkillProducts

リクエスト本文

このサンプルリクエストの本文はスキル内商品マニフェストを表します。

商品を作成するリクエスト本文を表示

{
  "vendorId": "string",
  "inSkillProductDefinition": {
    "version": "string",
    "type": "SUBSCRIPTION",
    "referenceName": "string",
    "purchasableState": "PURCHASABLE",
    "subscriptionInformation": {
      "subscriptionPaymentFrequency": "MONTHLY",
      "subscriptionTrialPeriodDays": 0
    },
    "publishingInformation": {
      "locales": {
        "ja-JP": {
          "name": "string",
          "smallIconUri": "string",
          "largeIconUri": "string",
          "summary": "string",
          "description": "string",
          "examplePhrases": [
            "string"
          ],
          "keywords": [
            "string"
          ],
          "customProductPrompts": {
            "purchasePromptDescription": "{PREMIUM_CONTENT_TITLE}は<emphasis level=\"moderate\"> さまざまな歴史のトピックに関する50個の質問の詰め合わせです。<break time=\"150ms\">",
            "boughtConfirmationPrompt": "新しい{PREMIUM_CONTENT_TITLE}をお楽しみください。 プレイしたくなったらいつでもAlexaにマイパックの究極歴史クイズを開いてと頼んでください。"
          }
        }
      },
      "distributionCountries": [
        "AF"
      ],
      "pricing": {
        "amazon.co.jp": {
          "releaseDate": "2018-09-19T23:06:48.107Z",
          "defaultPriceListing": {
            "price": 0,
            "currency": "JPY"
          }
        }
      },
      "taxInformation": {
        "category": "SOFTWARE"
      }
    },
    "privacyAndCompliance": {
      "locales": {
        "ja-JP": {
          "privacyPolicyUrl": "string"
        }
      }
    },
    "testingInstructions": "string"
  }
}

応答

正常な応答では201と商品名が次のように返されます。

{
  "productId": "string"
}

エラー

スキル内商品の概要を取得する

スキル内商品の概要を返します。

リクエスト

GET /v1/inSkillProducts/{productId}/stages/{stage}/summary

{stage}値ではdevelopmentとliveの両方がサポートされています。

応答

スキル内商品の概要の応答は次の形式を取ります。

{
  "type": "SUBSCRIPTION",
  "productId": "string",
  "referenceName": "string",
  "lastUpdated": "2018-09-20T04:13:02.326Z",
  "nameByLocale": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "status": "INCOMPLETE",
  "stage": "development",
  "editableState": "EDITABLE",
  "purchasableState": "PURCHASABLE",
  "_links": {
    "self": {
      "href": "string"
    }
  },
  "pricing": {
    "amazon.co.jp": {
      "releaseDate": "2018-09-20T04:13:02.326Z",
      "defaultPriceListing": {
        "price": 0,
        "primeMemberPrice": 0,
        "currency": "JPY"
      }
    }
  }
}

エラー

既存のスキル内商品を更新する

特定のproductIdとstageの既存のスキル内商品の定義を更新します。

リクエスト

developmentステージにあるスキルの商品定義のみを更新できます。したがって、{stage}の値はdevelopmentである必要があります。

PUT /v1/inSkillProducts/{productId}/stages/{stage}

リクエスト本文

リクエスト本文はスキル内商品マニフェストの形式です。

応答

スキル内商品の定義を、スキル内商品マニフェストの形式で返します。

エラー

既存のスキル内商品を削除する

指定されたproductIdのスキル内商品を削除します。削除は開発ステージでのみサポートされています。公開中のスキル内商品、またはスキルに関連付けられたスキル内商品は、このAPIでは削除できません。

リクエスト

DELETE /v1/inSkillProducts/{productId}/stages/{stage}

{stage}では、developmentのみがサポートされています。

応答

正常な応答ではコード204が返され、コンテンツはありません。

エラー

ベンダーのスキル内商品のリストを取得する

リクエスト

HTTP/1.1

GET /v1/inSkillProducts

パラメーターを使用してフィルタリングしたリクエスト

リストを戻すAPI呼び出しではどれも、maxResultsを指定して1回で表示する結果の数を制御できます。また、nextTokenを指定して、後続のAPI呼び出しで次に表示される結果のセットを取得することもできます。パラメーターをいくつか使用することがあるこのサンプルリクエストでは読みやすくするために改行を入れていますが、実際には改行を入れずにつなげてください。

GET  /v1/inSkillProducts?
     nextToken=VWB111111111
     &maxResults=5
	 &stage=live
     &type=SUBSCRIPTION	 

応答

正常な200 OK応答では次のような本文が返されます。_linksは、現在の結果を参照するためのURLと、次の結果のセットを参照するためのURLを提供します。

{
  "_links": {
    "self": {
      "href": "string"
    },
    "next": {
      "href": "string"
    }
  },
  "inSkillProducts": [
    {
      "type": "SUBSCRIPTION",
      "productId": "string",
      "referenceName": "string",
      "lastUpdated": "2018-09-19T22:56:57.937Z",
      "nameByLocale": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "status": "INCOMPLETE",
      "stage": "development",
      "editableState": "EDITABLE",
      "purchasableState": "PURCHASABLE",
      "_links": {
        "self": {
          "href": "string"
        }
      },
      "pricing": {
        "amazon.co.jp": {
          "releaseDate": "2018-09-19T22:56:57.937Z",
          "defaultPriceListing": {
            "price": 0,
            "primeMemberPrice": 0,
            "currency": "JPY"
          }
        }
      }
    }
  ],
  "isTruncated": true,
  "nextToken": "string"
}

エラー

特定のスキルIDおよびステージのスキル内商品のリストを取得する

特定のスキルIDおよびステージのスキル内商品のリストを取得します。

リクエスト

GET /v1/skills/{skillId}/stages/{stage}/inSkillProducts

オプションでmaxResultsを指定して1回で表示する結果の数を制御できます。また、nextTokenを指定して、後続のAPI呼び出しで次に表示される結果のセットを取得することもできます。パラメーターをいくつか使用するこのサンプルリクエストでは読みやすくするために改行を入れていますが、実際には改行を入れずにつなげてください。

GET  /v1/skills/AAA-xxxx-yyyy/stages/development/inSkillProducts?
     nextToken=VWB111111111
     &maxResults=5
	 &stage=live

応答

正常な応答では、200と指定されたskillIdおよびstageのスキル内商品のリストが返されます。

_links値は現在のリストのURLと、該当する場合は次の結果セットのURLを返します。

{
  "_links": {
    "self": {
      "href": "string"
    },
    "next": {
      "href": "string"
    }
  },
  "inSkillProducts": [
    {
      "type": "SUBSCRIPTION",
      "productId": "string",
      "referenceName": "string",
      "lastUpdated": "2018-09-11T10:42:07.152Z",
      "nameByLocale": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      },
      "status": "INCOMPLETE",
      "stage": "development",
      "editableState": "EDITABLE",
      "purchasableState": "PURCHASABLE",
      "_links": {
        "self": {
          "href": "string"
        }
      },
      "pricing": {
        "amazon.co.jp": {
          "releaseDate": "2018-09-11T10:42:07.153Z",
          "defaultPriceListing": {
            "price": 0,
            "primeMemberPrice": 0,
            "currency": "JPY"
          }
        }
      }
    }
  ],
  "isTruncated": true,
  "nextToken": "string"
}

エラー

スキル内商品に関連付けられたスキルのリストを取得する

スキル内商品に関連付けられたスキルのリストを返します。

リクエスト

/v1/inSkillProducts/{productId}/stages/{stage}/skills

応答

スキルのリストは、スキルのリストへのURLを提供する_linksオブジェクトで返されます。複数のページが返される場合、次のページへのURLも提供されます。

{
  "associatedSkillIds": [
    "string"
  ],
  "_links": {
    "self": {
      "href": "string"
    },
    "next": {
      "href": "string"
    }
  },
  "isTruncated": true,
  "nextToken": "string"
}

エラー

スキル内商品をスキルに関連付ける

スキル内商品をスキルに関連付けます。

リクエスト

PUT /v1/inSkillProducts/{productId}/skills/{skillId}

応答

204が返されます。コンテンツはありません。

エラー

スキル内商品とスキルの関連付けを解除する

スキル内商品とスキルの関連付けを削除します。商品もスキルも、そのほかの部分に変更はありません。

この関連付け解除は、開発ステージのスキルで行うことができます。公開中のスキルでこの関連付けを削除する場合は、スキルの再認定を申請する必要があります。

リクエスト

productIdとskillIdの両方が呼び出しで指定されます。

DELETE /v1/inSkillProducts/{productId}/skills/{skillId}

応答

正常な応答ではコード204が返され、コンテンツはありません。

エラー

開発者アカウントの買い切り型購入をリセットする

スキル内商品のタイプがENTITLEMENTまたはCONSUMABLEの場合、デフォルトでは、商品を購入したユーザーはその商品を永久に所有します。タイプがSUBSCRIPTIONでありユーザーが商品にアクセスし続けるために繰り返し料金を支払う必要があるインスタンスとは対照的です。スキル開発者が簡単にテストを実施できるよう、このAPIは、開発者アカウントが指定されたproductIDで持っているすべてのアクティブな買い切り型購入をリセットします。このAPIは商品そのものに影響を与えることはなく、スキルの開発者アカウントが持っている開発ステージの買い切り型購入のみをサポートします。

リクエスト

DELETE /v1/inSkillProducts/{productId}/stages/{stage}/entitlement

応答

正常な応答ではコード204が返され、コンテンツはありません。

エラー

応答の例外

リクエストが成功しなかった場合、次のような形式になります。

  {
   "id": string,
   "message": string
  }