スキル内商品の管理
スキル内商品管理APIを使用して、開発者はAPI経由でスキルのスキル内商品を管理できます。スキル内商品は作成、更新、リスト化できます。スキル内商品とスキルを関連付けし、管理することもできます。
このAPIのエンドポイントは、https://api.amazonalexa.comです。すべてのAPIリクエストにはAuthorizationヘッダーが必要であり、その値はLogin with Amazonから取得したアクセストークンでなければなりません。認証のしくみは他のスキル管理APIと同じです。
関連トピック：
- 結果のページ分割とフィルタリング
- スキル内商品の定義を取得する
- 新しいスキル内商品を作成する
- スキル内商品の概要を取得する
- 既存のスキル内商品を更新する
- 既存のスキル内商品を削除する
- ベンダーのスキル内商品のリストを取得する
- 特定のスキルIDおよびステージのスキル内商品のリストを取得する
- スキル内商品に関連付けられたスキルのリストを取得する
- スキル内商品をスキルに関連付ける
- スキル内商品とスキルの関連付けを解除する
- 開発者アカウントの買い切り型購入をリセットする
- 応答の例外
結果のページ分割とフィルタリング
リストを戻すAPI呼び出しについては、オプションでmaxResultsを指定して1回で表示する結果の数を制御できます。また、nextTokenを指定して、後続のAPI呼び出しで次に表示される結果のセットを取得することもできます。このサンプルリクエストでは読みやすくするために改行を入れていますが、実際には改行を入れずにつなげてください。リストを返す一部のAPI呼び出しでは、フィルタリングを行う他のパラメーターも使用できます。
GET /v1/skills/AAA-xxxx-yyyy/stages/development/inSkillProducts?
nextToken=VWB111111111
&maxResults=5
| パラメーター | 説明 |
|---|---|
| nextToken | 文字列です。後続のAPI呼び出しでnextToken値を使い、maxResults件の結果が表示された後の次の値を取得できます。このトークンの有効期限は24時間です。 |
| maxResults | 整数です。1回のAPI呼び出しで表示する結果の最大数です。デフォルトは100です。nextToken値を使って、後続のAPI呼び出しで残りの結果を取得できます。 |
スキル内商品の定義を取得する
指定された商品IDのスキル内商品の定義を返します。
リクエスト
stageの値にはdevelopmentまたはliveを使用できます。
GET /v1/inSkillProducts/{productId}/stages/{stage}
応答
スキル内商品の定義を、スキル内商品マニフェストの形式で返します。
エラー
| コード | 説明 |
| 400 | 不正なリクエストです。必須パラメーターが存在しないか、形式が正しくない場合に返されます。 |
| 401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
| 404 | リクエストされたリソースが見つかりません。 |
| 429 | 受信リクエストが多すぎます。 |
| 500 | 内部サーバーエラーです |
新しいスキル内商品を作成する
指定されたベンダーIDで新しいスキル内商品を作成します。
リクエスト
POST /v1/inSkillProducts
リクエスト本文
このサンプルリクエストの本文はスキル内商品マニフェストを表します。
応答
正常な応答では201と商品名が次のように返されます。
{
"productId": "string"
}
エラー
| コード | 説明 |
| 400 | 不正なリクエストです。必須パラメーターが存在しないか、形式が正しくない場合に返されます。 |
| 401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
| 429 | 受信リクエストが多すぎます。 |
| 500 | 内部サーバーエラーです |
スキル内商品の概要を取得する
スキル内商品の概要を返します。
リクエスト
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"
}
}
}
}
エラー
| コード | 説明 |
| 401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
| 404 | リクエストされたリソースが見つかりません。 |
| 429 | 受信リクエストが多すぎます。 |
| 500 | 内部サーバーエラーです |
既存のスキル内商品を更新する
特定のproductIdとstageの既存のスキル内商品の定義を更新します。
リクエスト
developmentステージにあるスキルの商品定義のみを更新できます。したがって、{stage}の値はdevelopmentである必要があります。
PUT /v1/inSkillProducts/{productId}/stages/{stage}
リクエスト本文
リクエスト本文はスキル内商品マニフェストの形式です。
応答
スキル内商品の定義を、スキル内商品マニフェストの形式で返します。
エラー
| コード | 説明 |
| 400 | 不正なリクエストです。必須パラメーターが存在しないか、形式が正しくない場合に返されます。 |
| 401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
| 403 | リクエストは許可されていません。 |
| 404 | リクエストされたリソースが見つかりません。 |
| 412 | 前提条件が失敗しました。 |
| 429 | 受信リクエストが多すぎます。 |
| 500 | 内部サーバーエラーです |
既存のスキル内商品を削除する
指定されたproductIdのスキル内商品を削除します。削除は開発ステージでのみサポートされています。公開中のスキル内商品、またはスキルに関連付けられたスキル内商品は、このAPIでは削除できません。
リクエスト
DELETE /v1/inSkillProducts/{productId}/stages/{stage}
{stage}では、developmentのみがサポートされています。
応答
正常な応答ではコード204が返され、コンテンツはありません。
エラー
| コード | 説明 |
| 400 | 不正なリクエストです。必須パラメーターが存在しないか、形式が正しくない場合に返されます。 |
| 401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
| 403 | リクエストは許可されていません。 |
| 404 | リクエストされたリソースが見つかりません。 |
| 412 | 前提条件が失敗しました。 |
| 429 | 受信リクエストが多すぎます。 |
| 500 | 内部サーバーエラーです |
ベンダーのスキル内商品のリストを取得する
リクエスト
HTTP/1.1
GET /v1/inSkillProducts
パラメーターを使用してフィルタリングしたリクエスト
リストを戻すAPI呼び出しではどれも、maxResultsを指定して1回で表示する結果の数を制御できます。また、nextTokenを指定して、後続のAPI呼び出しで次に表示される結果のセットを取得することもできます。パラメーターをいくつか使用することがあるこのサンプルリクエストでは読みやすくするために改行を入れていますが、実際には改行を入れずにつなげてください。
GET /v1/inSkillProducts?
nextToken=VWB111111111
&maxResults=5
&stage=live
&type=SUBSCRIPTION
| パラメーター | 説明 |
|---|---|
| nextToken | 文字列です。後続のAPI呼び出しでnextToken値を使い、maxResults件の結果が表示された後の次の値を取得できます。このトークンの有効期限は24時間です。
|
| maxResults | 整数です。1回のAPI呼び出しで表示する結果の最大数です。デフォルトは100です。nextToken値を使って、後続のAPI呼び出しで残りの結果を取得できます。
|
| productId | 文字列の配列です。概要を取得するスキル内商品のIDのリストです。1つのlistInSkillProducts呼び出しで、最大50個のスキル内商品IDを指定できます。productIdパラメーターはnextTokenまたはmaxResultsパラメーターと共に使用する必要があります。 |
| stage | 「development」、「live」のいずれかです。結果を指定されたステージのみにフィルタリングします。 |
| type | 次のいずれかになります。 SUBSCRIPTION、ENTITLEMENT、CONSUMABLE。結果を指定されたスキル内商品のタイプのみにフィルタリングします。
|
| status | 次のいずれかになります。 INCOMPLETE、COMPLETE、CERTIFICATION、PUBLISHED、SUPPRESSED。スキル内商品のステータスでフィルタリングします。
|
| isAssociatedWithSkill | 次のいずれかになります。 ASSOCIATED_WITH_SKILL、NO_ASSOCIATIONs。スキル内商品を、スキルに関連付けられているかどうかでフィルタリングします。
|
応答
正常な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"
}
エラー
| 400 | 不正なリクエストです。必須パラメーターが存在しないか、形式が正しくない場合に返されます。 |
| 401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
| 429 | 受信リクエストが多すぎます。 |
| 500 | 内部サーバーエラーです |
特定のスキル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
| パラメーター | 説明 |
|---|---|
| nextToken | 文字列です。後続のAPI呼び出しでnextToken値を使い、maxResults件の結果が表示された後の次の値を取得できます。このトークンの有効期限は24時間です。
|
| maxResults | 整数です。1回のAPI呼び出しで表示する結果の最大数です。デフォルトは100です。nextToken値を使って、後続のAPI呼び出しで残りの結果を取得できます。
|
応答
正常な応答では、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"
}
エラー
| コード | 説明 |
| 400 | 不正なリクエストです。必須パラメーターが存在しないか、形式が正しくない場合に返されます。 |
| 401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
| 404 | リクエストされたリソースが見つかりません。 |
| 429 | 受信リクエストが多すぎます。 |
| 500 | 内部サーバーエラーです |
スキル内商品に関連付けられたスキルのリストを取得する
スキル内商品に関連付けられたスキルのリストを返します。
リクエスト
/v1/inSkillProducts/{productId}/stages/{stage}/skills
応答
スキルのリストは、スキルのリストへのURLを提供する_linksオブジェクトで返されます。複数のページが返される場合、次のページへのURLも提供されます。
{
"associatedSkillIds": [
"string"
],
"_links": {
"self": {
"href": "string"
},
"next": {
"href": "string"
}
},
"isTruncated": true,
"nextToken": "string"
}
エラー
| コード | 説明 |
| 401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
| 404 | リクエストされたリソースが見つかりません。 |
| 429 | 受信リクエストが多すぎます。 |
| 500 | 内部サーバーエラーです |
スキル内商品をスキルに関連付ける
スキル内商品をスキルに関連付けます。
リクエスト
PUT /v1/inSkillProducts/{productId}/skills/{skillId}
応答
204が返されます。コンテンツはありません。
エラー
| コード | 説明 |
| 400 | 不正なリクエストです。必須パラメーターが存在しないか、形式が正しくない場合に返されます。 |
| 401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
| 403 | リクエストは許可されていません。 |
| 404 | リクエストされたリソースが見つかりません。 |
| 429 | 受信リクエストが多すぎます。 |
| 500 | 内部サーバーエラーです |
スキル内商品とスキルの関連付けを解除する
スキル内商品とスキルの関連付けを削除します。商品もスキルも、そのほかの部分に変更はありません。
この関連付け解除は、開発ステージのスキルで行うことができます。公開中のスキルでこの関連付けを削除する場合は、スキルの再認定を申請する必要があります。
リクエスト
productIdとskillIdの両方が呼び出しで指定されます。
DELETE /v1/inSkillProducts/{productId}/skills/{skillId}
応答
正常な応答ではコード204が返され、コンテンツはありません。
エラー
| コード | 説明 |
| 400 | 不正なリクエストです。必須パラメーターが存在しないか、形式が正しくない場合に返されます。 |
| 401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
| 403 | リクエストは許可されていません。 |
| 404 | リクエストされたリソースが見つかりません。 |
| 412 | 前提条件が失敗しました。 |
| 429 | 受信リクエストが多すぎます。 |
| 500 | 内部サーバーエラーです |
開発者アカウントの買い切り型購入をリセットする
スキル内商品のタイプがENTITLEMENTまたはCONSUMABLEの場合、デフォルトでは、商品を購入したユーザーはその商品を永久に所有します。タイプがSUBSCRIPTIONでありユーザーが商品にアクセスし続けるために繰り返し料金を支払う必要があるインスタンスとは対照的です。スキル開発者が簡単にテストを実施できるよう、このAPIは、開発者アカウントが指定されたproductIDで持っているすべてのアクティブな買い切り型購入をリセットします。このAPIは商品そのものに影響を与えることはなく、スキルの開発者アカウントが持っている開発ステージの買い切り型購入のみをサポートします。
リクエスト
DELETE /v1/inSkillProducts/{productId}/stages/{stage}/entitlement
応答
正常な応答ではコード204が返され、コンテンツはありません。
エラー
| コード | 説明 |
| 400 | 不正なリクエストです。必須パラメーターが存在しないか、形式が正しくない場合に返されます。 |
| 401 | 認可トークンが無効または期限切れか、リソースに対するアクセス権限がありません。 |
| 403 | リクエストは許可されていません。 |
| 404 | リクエストされたリソースが見つかりません。 |
| 412 | 前提条件が失敗しました。 |
| 429 | 受信リクエストが多すぎます。 |
| 500 | 内部サーバーエラーです |
応答の例外
リクエストが成功しなかった場合、次のような形式になります。
{
"id": string,
"message": string
}