スキル内商品の管理

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

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

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

リストを戻す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
  }