スキル内商品サービス

スキル内商品サービスAPIの使用

ユーザーがスキルの実行時に購入できる、または既に購入済みのスキル内商品に関する情報を取得するには、このAPIを使用します。

ホストのエンドポイント

スキル内商品APIに対するすべての呼び出しのホストは、System.ObjectのapiEndpointパラメーターの値です。例：api.amazonalexa.com.

すべてのスキル内商品を取得する

このスキルで購入できるすべての商品と、アイテムがユーザーによって購入されたことがあるかどうかを取得します。

リクエスト

GET /v1/users/~current/skills/~current/inSkillProducts
Host: {event.context.System.apiEndpoint}
Accept-Language: {event.request.locale}
Authorization: Bearer {event.context.System.apiAccessToken}

パラメーター

名前 位置 説明 必須 スキーマ
authorization ヘッダー 認証と認可に使用するアクセストークンです。SPI呼び出し内でユーザーに渡されます。 ◯ 文字列
Accept-Language ヘッダー コンテキスト内のユーザーのロケールまたは言語です。 ◯ 文字列
purchasable クエリ ユーザーが購入できるかどうかに基づいて商品をフィルタリングします。 ✕ PURCHASABLEまたはNOT_PURCHASABLEのいずれかの文字列
entitled クエリ ユーザーが商品を買ったかどうかに基づいて商品をフィルタリングします。 ✕ ENTITLEDまたはNOT_ENTITLEDのいずれかの文字列
productType クエリ 商品の型です。消費型、サブスクリプション型、買い切り型のいずれかです。 ✕ 文字列CONSUMABLE、SUBSCRIPTION、ENTITLEMENTのいずれか
nextToken クエリ 応答が切り分けられたことを示します。このトークン値は、オブジェクトの次のセットのリストを表示する継続トークンとして次のリクエストで使用されます。このトークンはサービスによって使用されるopaque値です。トークンは24時間で有効期限が切れます。 ✕ 文字列
maxResults クエリ 応答本文で返される結果の最大数を設定します。この値は、上限の100より少なく取得する場合に設定します。検索条件を満たす結果が他にもあるが、maxResultsを超えるために返されない場合、応答にisTruncated = trueが含まれます。 ✕ 1から100までの整数

応答

コード 説明 スキーマ
200 成功時にスキル内商品のリストを返します。 InSkillProductsResponse
400 無効なリクエストです。 エラー
401 認証トークンが無効か、このリクエストを行うアクセス権限がありません。 エラー
500 内部サーバーエラーです エラー

応答が成功した場合、商品のリストを含むオブジェクトであるinSkillProductsが含まれます。ISPを作成すると、InSkillProductのフィールドreferenceName、type、name、summaryが設定されます。productIdは一意であることが保証されており、商品を提供するために使用できます。PURCHASABLEの値がpurchasableの商品のみがユーザーに提供されます。この値はユーザーの居住国や地域、リクエストが行われたデバイスなどの入力情報に基づいて設定されます。ユーザーは、登録の値がENTITLEDの場合のみ、プレミアムコンテンツにアクセスできます。

200応答の例

この応答例では、スキルに3つの商品があり、買い切り型、サブスクリプション型、消費型がそれぞれ1つ含まれます。ユーザーはサブスクリプション型、および消費型を2つ購入しています。

{
  "inSkillProducts": [
    {
      "productId": "amzn1.adg.product.unique-id-1",
      "referenceName": "your_product_name_1",
      "type": "ENTITLEMENT",
      "name": "Friendly Name",
      "summary": "商品の説明です。",
      "entitled": "NOT_ENTITLED",
      "purchasable": "PURCHASABLE",
      "activeEntitlementCount": 0,
      "purchaseMode": "TEST"
    },
    {
      "productId": "amzn1.adg.product.unique-id-2",
      "referenceName": "your_product_name_2",
      "type": "SUBSCRIPTION",
      "name": "Friendly Name",
      "summary": "商品の説明です。",
      "entitled": "ENTITLED",
      "purchasable": "NOT_PURCHASABLE",
      "activeEntitlementCount": 1,
      "purchaseMode": "TEST"
    },
    {
      "productId": "amzn1.adg.product.unique-id-3",
      "referenceName": "your_product_name_3",
      "type": "CONSUMABLE",
      "name": "Friendly Name",
      "summary": "商品の説明です。",
      "entitled": "ENTITLED",
      "purchasable": "PURCHASABLE",
      "activeEntitlementCount": 2,
      "purchaseMode": "TEST"
    }
  ],
  "nextToken": null,
  "truncated": false
}

商品IDでスキル内商品を取得する

指定されたユーザーおよびスキルについて、指定されたスキル内商品を取得します。

リクエスト

GET  /v1/users/~current/skills/~current/inSkillProducts/{productId}
Host: {event.context.System.apiEndpoint}
Accept-Language: {event.request.locale}
Authorization: Bearer {event.context.System.apiAccessToken}

パラメーター

名前 位置 説明 必須 型／スキーマ
Authorization ヘッダー 認証と認可に使用するアクセストークンです。これは入力メッセージのSystem.Objectで提供されます。 ◯ 文字列
Accept-Language ヘッダー 起動リクエストまたはインテントリクエストから取得するユーザーのロケールです。 ◯ 文字列
productId パス 商品IDです。 ◯ 文字列

応答

コード 説明 型／スキーマ
200 成功すると、指定されたスキル内商品を返します。 InSkillProduct
400 無効なリクエストです。 エラー
401 認証トークンが無効か、このリクエストを行うアクセス権限がありません。 エラー
404 リクエストされた商品IDは検出の対象にできません。これは、商品を含むスキルの公開中または更新されたバージョンが、まだ完全に本番にプロビジョニングされていない場合に（まれに）発生することがあります。 エラー
500 内部サーバーエラーです。 エラー

タイプスキーマ

エラー

名前 型 説明 必須
message 文字列 ユーザーが読める形式のエラー詳細です。 ✕

InSkillProducts

{
  "inSkillProducts": [
    {
      "productId": "amzn1.adg.product.unique-id-1",
      "referenceName": "your_product_name_1",
      "type": "ENTITLEMENT",
      "name": "Friendly Name",
      "summary": "商品の説明です。",
      "entitled": "NOT_ENTITLED",
      "purchasable": "PURCHASABLE",
      "activeEntitlementCount": 0,
      "purchaseMode": "TEST"
    }
  ],
  "nextToken": null,
  "truncated": false
}
名前 型 説明 必須
inSkillProductsResponse InSkillProductオブジェクトのリスト このスキルの商品のリストです。 ✕
isTruncated 文字列 結果が複数の応答に切り分けられている場合はtrue、それ以外の場合はfalseです。 ◯
nextToken 文字列 このAPI呼び出しに対する応答が切り分けられている（つまり、isTruncated応答要素の値がtrue）場合、応答にはnextToken要素も含まれています。この値を次のリクエストで継続トークンとして使用して次のオブジェクトのセットをリストできます。継続トークンは、スキル内商品APIが理解できるOpaque値です。トークンは24時間で有効期限が切れます。 ✕

InSkillProduct

{
  "productId": "amzn1.adg.product.unique-id-1",
  "referenceName": "your_product_name_1",
  "type": "ENTITLEMENT",
  "name": "Friendly Name",
  "summary": "商品の説明です。",
  "entitled": "NOT_ENTITLED",
  "purchasable": "PURCHASABLE",
  "entitlementReason": "NOT_PURCHASED",
  "activeEntitlementCount": 0,
  "purchaseMode": "TEST"
}
名前 型 説明 必須
productId 文字列 商品IDです。一意であることが保証されています。商品のオファーと購入に使用されます。 ◯
referenceName 文字列 商品の参照名です。商品を作成した際に指定したものです。 ◯
type 文字列の列挙値 商品の型です。CONSUMABLE、SUBSCRIPTION、ENTITLEMENTのいずれかです ◯
name 文字列 Accept-Languageヘッダーから取得した言語で書かれた商品の名前です。 ◯
summary 文字列 Accept-Languageヘッダーから取得した言語で書かれた商品の概要です。商品の説明で指定した概要です。 ◯
entitled 文字列 このユーザーが商品を購入したかどうかを示す列挙値です。ENTITLEDまたはNOT_ENTITLEDのいずれかになります。 ◯
entitlementReason 文字列 買い切り型のステータスの理由を示す列挙値です。入力される値には、PURCHASED（ユーザーが商品を購入した）、NOT_PURCHASED（ユーザーが商品を購入しなかった）、 AUTO_ENTITLED（ユーザーが、商品を含むサービスのサブスクリプションを行うなど、商品を自動的に購入した）があります。 ◯
purchasable 文字列の列挙値 このユーザーが商品を購入できるかどうかを示します。PURCHASABLEまたはNOT_PURCHASABLEのいずれか ◯
activeEntitlementCount 整数 ユーザーがこの商品を購入した回数です。CONSUMABLEの場合、これはユーザーが商品を購入した回数です。ユーザーが購入したアイテムを消費した回数は反映されていないことに注意してください。そのため、ユーザーのインベントリーを管理する必要があります。SUBSCRIPTIONまたはENTITLEMENTの場合は、常に0または1です。 ◯
purchaseMode 文字列の列挙値 この購入が行われた環境を示します。TEST（開発またはベータテストでの購入）またはLIVE（公開中のスキルでの購入）のいずれかになります。 ◯

列挙値の定義

  • SUBSCRIPTION： 購入すると、ユーザーはサブスクリプションの期間中コンテンツを所有できます。
  • ENTITLEMENT： 購入すると、ユーザーは永続的にコンテンツを所有できます。
  • CONSUMABLE： 購入すると、ユーザーはコンテンツを消費して再度購入できます。ユーザーは商品を複数購入してストックできます。
  • PURCHASABLE： ユーザーはこの商品を購入できます。
  • NOT_PURCHASABLE： ユーザーはこの商品を購入できません。
  • ENTITLED： ユーザーはこの商品を購入したことがあります。
  • NOT_ENTITLED： ユーザーはこの商品を購入したことがありません。
  • TEST： ユーザーはこの購入をテスト環境（開発ステージのスキルまたはベータテスト）で行いました。
  • LIVE： ユーザーはこの購入を公開中のスキルで行いました。
このページは役に立ちましたか？