ASK CLIを使用したスキル内商品の作成と管理

ASK CLIを使用したスキル内商品の作成と管理

スキル内でプレミアムコンテンツを提供するには、1つ以上のスキル内商品を定義してスキルに関連付けます。スキル内商品では、購入の仕方や価格などの詳細を定義します。スキル内商品をスキルに追加するには、Alexa Skills Kitコマンドラインインターフェース（ASK CLI）を使用できます。

前提条件

スキル内商品を作成するには、スキル内課金をサポートするロケールでカスタムスキルを作成する必要があります。対象のロケールについては、スキル内商品をサポートしている言語とロケールを参照してください。

ASK CLIのバージョン2以降をインストールしている必要があります。最新バージョンを入手するには、ASK CLIクイックスタートのインストール手順に従ってください。

スキル内商品の各支払いモデルについて、JSONスキーマ定義を理解します。 買い切り型、サブスクリプション型、消費型の支払いモデルがあります。商品を定義するには、商品情報を追加してスキーマを変更します。詳しくは、商品スキーマの各部分を参照してください。JSONファイルで商品を定義します。

スキル内商品に使用するCLIコマンドの概要

スキル内商品を管理するには、以下のCLIコマンドを使用できます。

スキルのスキル内商品を確認する

get-isp-list-for-vendorコマンドを使用すると、Amazon開発者アカウントで作成したすべての商品のリストを取得できます。スキルに関連付けられた商品のリストを取得するには、ask smapi get-isp-list-for-skill-id --skill-id <skill-id>を使用します。

以下は、開発者のアカウントを使用して作成したすべての商品のリストを取得するCLIコマンドの例です。

$ cd my-existing-skill-name

$ ask smapi get-isp-list-for-vendor
{
    "_links": {
        "next": {
            "href": "/v1/inSkillProducts?vendorId=MMMMMRZ"
        },
        "self": {
            "href": "/v1/inSkillProducts?vendorId=MMMMMRZ"
        }
    },
    "inSkillProductSummaryList": [{
            "editableState": "EDITABLE",
            "lastUpdated": "2021-02-26T18:18:41.275Z",
            "nameByLocale": {
                "ja-JP": "楽しいサブスクリプション"
            },
            "pricing": {
                "amazon.co.jp": {
                    "defaultPriceListing": {
                        "currency": "JPY",
                        "price": 99
                    },
                    "releaseDate": "2021-02-26T00:00:00Z"
                },
                "amazon.com": {
                    "defaultPriceListing": {
                        "currency": "USD",
                        "price": 0.99
                    },
                    "releaseDate": "2021-02-09T00:00:00Z"
                }
            },
            "productId": "amzn1.adg.product.39e08b9f-8699-4988-b859-10173cf31d82",
            "promotableState": "IN_SKILL_ONLY",
            "purchasableState": "PURCHASABLE",
            "referenceName": "testSubscription",
            "stage": "development",
            "status": "COMPLETE",
            "type": "SUBSCRIPTION"
        },
        {
            "editableState": "EDITABLE",
            "lastUpdated": "2022-02-15T20:29:23.220Z",
            "nameByLocale": {
              "ja-JP": "宝探しプラス"
            },
            "pricing": {
                "amazon.co.jp": {
                    "defaultPriceListing": {
                        "currency": "USD",
                        "price": 0.99
                    },
                    "releaseDate": "2021-02-15T00:00:00Z"
                },
                "amazon.it": {
                    "defaultPriceListing": {
                        "currency": "EUR",
                        "price": 0.99
                    },
                    "releaseDate": "2022-02-15T00:00:00Z"
                }
            },
            "productId": "amzn1.adg.product.c376ccf7-8c27-40eb-919c-0686a5bdd074",
            "promotableState": "IN_SKILL_ONLY",
            "purchasableState": "PURCHASABLE",
            "referenceName": "AddConsumableProduct",
            "stage": "development",
            "status": "INCOMPLETE",
            "type": "CONSUMABLE"
        },
        {
            "editableState": "EDITABLE",
            "lastUpdated": "2021-07-07T19:31:19.074Z",
            "nameByLocale": {
                "ja-JP": "5ゴールドコイン"
            },
            "pricing": {
                "amazon.co.jp": {
                    "defaultPriceListing": {
                        "currency": "USD",
                        "price": 0.99
                    },
                    "releaseDate": "2021-02-15T00:00:00Z"
                }
            },
            "productId": "amzn1.adg.product.8761329b-7d48-44ba-9425-b28fc30b3f5a",
            "promotableState": "IN_SKILL_ONLY",
            "purchasableState": "PURCHASABLE",
            "referenceName": "testOneTimePurchase",
            "stage": "development",
            "status": "COMPLETE",
            "type": "ENTITLEMENT"
        }
    ],
    "isTruncated": false
}

スキル内商品を作成してスキルにリンクする

新しいスキル内商品を作成するには、1つ以上の商品定義を含むJSONファイルを作成します。商品定義には、ベンダーIDと支払いモデルのスキル内商品スキーマを含めます。商品を作成するには、create-isp-for-vendorコマンドを使用します。商品をスキルにリンクするには、associate-isp-with-skillコマンドを使用します。商品をスキルにリンクしたら、新しい商品のスキルコードを更新します。JSONファイルの内容についての詳細は、新しいスキル内商品の作成リクエスト本文を参照してください。

以下は、商品を作成し、スキルにリンクして、スキルに関連付けられた商品のリストを取得するCLIコマンドの例です。

$ cd my-existing-skill-name

# 新しい商品を作成します
$ ask smapi create-isp-for-vendor --create-in-skill-product-request file:./product_definition.json

{
  "productId": "amzn1.adg.product.9333d53e-d66d-44d3-9ab6-1c73b1f6dee8"
}

# 商品をスキルに関連付けます
$ ask smapi associate-isp-with-skill --product-id  amzn1.adg.product.9333d53e-d66d-44d3-9ab6-1c73b1f6dee8 --skill-id amzn1.ask.skill.45f6f820-5e75-43f4-994a-b560c6a8803c

コマンドは正常に実行されました。

# スキルに関連付けられた商品を確認します
$ ask smapi get-isp-list-for-skill-id --skill-id amzn1.ask.skill.45f6f820-5e75-43f4-994a-b560c6a8803c

{
  "_links": {
    "next": {
      "href": "/v1/skills/amzn1.ask.skill.45f6f820-5e75-43f4-994a-b560c6a8803c/stages/development/inSkillProducts"
    },
    "self": {
      "href": "/v1/skills/amzn1.ask.skill.45f6f820-5e75-43f4-994a-b560c6a8803c/stages/development/inSkillProducts"
    }
  },
  "inSkillProductSummaryList": [
    {
      "editableState": "EDITABLE",
      "lastUpdated": "2022-02-23T18:30:06.840Z",
      "nameByLocale": {
        "en-GB": "Treasure Finders Plus",
        "ja-JP": "宝探しプラス"
      },
      "pricing": {
        "amazon.co.uk": {
          "defaultPriceListing": {
            "currency": "GBP",
            "price": 1.54
          },
          "releaseDate": "2018-12-28T01:25:00Z"
        },
        "amazon.com": {
          "defaultPriceListing": {
            "currency": "USD",
            "price": 1.99
          },
          "releaseDate": "2018-12-28T01:25:00Z"
        }
      },
      "productId": "amzn1.adg.product.9333d53e-d66d-44d3-9ab6-1c73b1f6dee8",
      "promotableState": "ALL_AMAZON_CHANNELS",
      "purchasableState": "PURCHASABLE",
      "referenceName": "TreasureFinderSubscription",
      "stage": "development",
      "status": "COMPLETE",
      "type": "SUBSCRIPTION"
    }
  ],
  "isTruncated": false
}

スキル内商品を更新する

開発中ステージの既存商品を変更するには、商品定義のJSONファイルを更新します。商品定義には、ベンダーIDと支払いモデルのISPスキーマを含めます。商品を変更するには、update-isp-for-productコマンドを使用します。JSONファイルの内容についての詳細は、新しいスキル内商品の作成リクエスト本文を参照してください。

以下は、既存商品を変更するCLIコマンドの例です。

$ cd my-existing-skill-name

# 変更したい商品の商品IDを取得します
$ ask smapi get-isp-list-for-skill-id --skill-id amzn1.ask.skill.45f6f820-5e75-43f4-994a-b560c6a8803c

{
  "_links": {
    "next": {
      "href": "/v1/skills/amzn1.ask.skill.45f6f820-5e75-43f4-994a-b560c6a8803c/stages/development/inSkillProducts"
    },
    "self": {
      "href": "/v1/skills/amzn1.ask.skill.45f6f820-5e75-43f4-994a-b560c6a8803c/stages/development/inSkillProducts"
    }
  },
  "inSkillProductSummaryList": [
    {
      "editableState": "EDITABLE",
      "lastUpdated": "2022-02-23T18:30:06.840Z",
      "nameByLocale": {
        "en-GB": "Treasure Finders Plus",
        "ja-JP": "宝探しプラス"
      },
      "pricing": {
        "amazon.co.uk": {
          "defaultPriceListing": {
            "currency": "GBP",
            "price": 1.54
          },
          "releaseDate": "2018-12-28T01:25:00Z"
        },
        "amazon.com": {
          "defaultPriceListing": {
            "currency": "USD",
            "price": 1.99
          },
          "releaseDate": "2018-12-28T01:25:00Z"
        }
      },
      <span class="red">"productId": "amzn1.adg.product.9333d53e-d66d-44d3-9ab6-1c73b1f6dee8"</span>,
      "promotableState": "ALL_AMAZON_CHANNELS",
      "purchasableState": "PURCHASABLE",
      "referenceName": "TreasureFinderSubscription",
      "stage": "development",
      "status": "COMPLETE",
      "type": "SUBSCRIPTION"
    }
  ],
  "isTruncated": false
}

# 商品定義を更新します
$ ask smapi update-isp-for-product --product-id amzn1.adg.product.9333d53e-d66d-44d3-9ab6-1c73b1f6dee8 --in-skill-product file:./treasure_finder.json --stage development

コマンドは正常に実行されました。

# 更新された商品定義を確認します
$ ask smapi get-isp-summary --product-id amzn1.adg.product.9333d53e-d66d-44d3-9ab6-1c73b1f6dee8 --stage development
{
  "inSkillProductSummary": {
    "editableState": "EDITABLE",
    "lastUpdated": "2022-02-23T21:31:58.457Z",
    "nameByLocale": {
      "en-GB": "Treasure Finders Plus",
      "ja-JP": "宝探しプラス"
    },
    "pricing": {
      "amazon.co.uk": {
        "defaultPriceListing": {
          "currency": "GBP",
          "price": 2.54
        },
        "releaseDate": "2021-12-28T01:25:00Z"
      },
      "amazon.com": {
        "defaultPriceListing": {
          "currency": "USD",
          "price": 2.99
        },
        "releaseDate": "2021-12-28T01:25:00Z"
      }
    },
    "productId": "amzn1.adg.product.9333d53e-d66d-44d3-9ab6-1c73b1f6dee8",
    "promotableState": "IN_SKILL_ONLY",
    "purchasableState": "PURCHASABLE",
    "referenceName": "TreasureFinderSubscription",
    "stage": "development",
    "status": "COMPLETE",
    "type": "SUBSCRIPTION"
  }
}

商品を削除する

スキルの公開中バージョンで商品が提供されたことがなければ、開発中ステージで商品をスキルから削除できます。商品を削除する前に、後で使用する時に備えて別の場所にファイルをバックアップすることをお勧めします。

以下は、商品IDを指定して商品を削除する方法の例です。

$ cd my-existing-skill-name

# 指定した商品IDの商品を削除します
$ ask smapi delete-isp-for-product --product-id amzn1.adg.product.9333d53e-d66d-44d3-9ab6-1c73b1f6dee8 --stage development

コマンドは正常に実行されました。

公開中のスキルで商品の提供を終了する

商品を公開した後で提供終了すると、ユーザーにネガティブな印象を与えてしまう可能性があります。商品の提供終了を避けるため、ベストプラクティスに沿ってプレミアム商品をデザインしてください。公開中の商品をどうしても終了しなければならない場合は、スキルと商品の関連付けを解除できます。この変更には、スキルの再認定を申請する必要があります。慎重に検討し、既存ユーザーのエクスペリエンスを損なうような変更は回避してください。

商品の提供を終了すると次のような影響があります。

  • ユーザーはこの商品を購入できなくなります。
  • 消費型と買い切り型の商品の場合、商品を購入したユーザーが引き続きこの商品にアクセスできるようにしてください。スキルでは、これらのユーザーを引き続きサポートする必要があります。
  • サブスクリプション型の場合、サブスクリプションを行ったユーザーが残りの期間中にその商品にアクセスできるようにしてください。期間が終わると、サブスクリプションは自動的に更新されません。

スキルを公開すると、スキルのステータスが公開中に変わり、新しい開発中バージョンが自動で作成されます。開発中バージョンには、元の公開中のバージョンと同じ情報が登録されています。開発中バージョンを使用して、スキル内商品の提供を終了します。

以下は、スキルと商品のリンクを解除する方法の例です。

$ cd my-existing-skill-name

# スキルと商品のリンクを解除します
$ ask smapi ask smapi disassociate-isp-with-skill  --product-id amzn1.adg.product.9333d53e-d66d-44d3-9ab6-1c73b1f6dee8  --skill-id amzn1.ask.skill.45f6f820-5e75-43f4-994a-b560c6a8803c

コマンドは正常に実行されました。

スキル内商品のスキルパッケージファイルの構造

スキルパッケージにスキル内商品が含まれる場合、スキルに関連付けられたそれらの商品は、ispsというフォルダにあるスキルパッケージファイルに定義されます。このフォルダには、1つ以上の商品定義ファイルと、スキルにリンクする商品を説明するisps.jsonという名前のファイルが含まれます。

以下は、product1.jsonとproduct2.jsonという2つの商品を含むスキルパッケージの例です。

SkillPackageName.zip
├── assets
├── interactionModels
├── isps
│   ├── isps.json
│   ├── product1.json
│   └── exampleDirectory
│       └── product2.json
└── skill.json

isps.jsonファイルには、作成または更新する商品、スキルに関連付ける既存商品の2つのセクションがあります。各商品定義ファイルは、スキル内商品スキーマのJSON形式に従って作成します。

以下は、作成する2つの新商品とスキルに関連付ける2つの既存商品を含むisps.jsonファイルの内容の例です。

{
  "isps": {
    "一意の商品名1": {
      "path": "file://isps/isp1.json"
    },
    "一意の商品名2": {
      "path": "file://isps/exampleDirectory/isp2.json"
    }
  },
  "associations": [
    "amzn1.adg.UUID3",
    "amzn1.adg.UUID4"
  ]
}

以下の表は、isps.jsonファイルの各オブジェクトをまとめたものです。

プロパティ 説明

isps

1つ以上の商品のリストです。それぞれに、作成または更新したい一意の参照名が付いています。各商品には、スキル内商品スキーマファイルの場所を、スキルパッケージのルートファイルであるskill.jsonファイルからの相対パスで指定するpathが含まれます。商品ファイルのディレクトリ構造に制約はありません。
参照名の有効値は、英数字とアンダースコアです。

associations

スキルにリンクする既存商品のリストです。各商品は、商品作成時にAmazonによって生成された商品IDで識別されます。商品IDを取得するには、ASK CLI、Alexa開発者コンソール、スキル内商品の管理REST APIのいずれかを使用します。

このページは役に立ちましたか？

最終更新日: 2024 年 04 月 23 日