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



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

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

前提条件

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

商品の管理のしくみ

ASK CLIを使用して作成した各商品はJSONスキーマで表わされます。これは、後述の商品を含むスキルのファイル構造で説明するようにファイルに保存されます。これらのスキルファイルのローカルコピーに変更を加えます。更新したスキルを開発者アカウントにデプロイすると、変更が有効になります。

ASK CLIは、作成するスキル内商品のタイプに合わせたスキーマを作成するためのテンプレートを提供します:サブスクリプション型買い切り型消費型

開発者コンソールでスキル内商品を管理することもできます。

商品を追加しスキルとともにデプロイするには

ASK CLIで管理しているスキルのディレクトリにいる場合、次のことができます。

  • add ispコマンドを使用して、テンプレートを使用しているスキルに商品を追加します。スキルを追加する他のオプションについては、add ispコマンドを参照してください。
  • statusコマンドを--ispフラグとともに使用して、商品のステータスをチェックします。
  • ASK CLIのデプロイコマンドを使用して、スキルをデプロイします。

以下は、既存のスキルをクローンして商品を追加し、その後開発者アカウントにスキルをデプロイするワークフローの例です。

$ ask clone 
# ローカルのワークスペースにクローンする既存のスキルをリストから選択します。
# その後そのディレクトリに移動します。

$ cd my-existing-skill-name

# ASK CLIスキルプロジェクトのルートディレクトリでコマンド「ask add isp」を実行して
# スキル内商品を追加します。

$ ask add isp

? 選択できるスキル内商品のタイプのリスト(矢印キーを使用)
> 消費型
  買い切り型
  サブスクリプション型

# この例では、矢印キーを使用して買い切り型を選択します

? 選択できるスキル内商品テンプレートのリスト(矢印キーを使用)
> Entitlement_Template

? 新しいスキル内商品の名前を入力してください:
 (Entitlement_Template) cave_quest

スキル内商品cave_questは.\isps\entitlement\cave_quest.jsonに保存されます

$ cd isp/entitlement
# cave_quest.jsonファイルに変更を加えます

$ ask status --isp
デプロイする購入可能なスキル内商品:
    (現在のスキルにスキル内商品を追加する場合は「ask add isp --file <filePath>/--isp-id <id>」を使用します)
    (現在のスキルからスキル内商品を削除する場合は「ask remove isp --file <filePath>/--isp-id <id>」を使用します)

デプロイステータス | ID   | ファイル                                    
Add           | N/A  | isps/entitlement/cave_quest.json    


# スキル内商品を含めてスキルプロジェクト全体を開発者アカウントに 
# デプロイします。デプロイ中に、スキル内商品は 
# 現在のスキルに関連付けられます。
$ ask deploy 

# 再度ステータスをチェックします

$ ask status --isp
デプロイする購入可能なスキル内商品:
    (現在のスキルにスキル内商品を追加する場合は「ask add isp --file <filePath>/--isp-id <id>」を使用します)
    (現在のスキルからスキル内商品を削除する場合は「ask remove isp --file <filePath>/--isp-id <id>」を使用します)

デプロイステータス | ID                                   | ファイル 
Update        | amzn1.adg.product.0dc13545-bb0c-1... | isps/entitlement/cave_quest.json 

# この例に表示された商品IDは切り捨てられていることに注意してください。
# statusでは完全な商品IDを次の形式で表示します。
# amzn1.adg.product.aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

商品を変更するには

ステータスが開発中の既存の商品を更新するには、次の方法があります。

  • ローカル商品ファイルに変更を加えます
  • 更新したファイルを使用してスキルをデプロイします

以下は商品を変更するワークフローの例です。

$ cd my-existing-skill-name

$ ask status --isp
デプロイする購入可能なスキル内商品:
    (現在のスキルにスキル内商品を追加する場合は「ask add isp --file <filePath>/--isp-id <id>」を使用します)
    (現在のスキルからスキル内商品を削除する場合は「ask remove isp --file <filePath>/--isp-id <id>」を使用します)

デプロイステータス | ID                                   | ファイル 
Update        | amzn1.adg.product.0dc13545-bb0c-1...  | isps/entitlement/cave_quest.json 

# 商品ファイルを開いて変更を加えます。
$ vim isps/entitlement/cave_quest.json   

# スキル内商品を含めてスキルプロジェクト全体を開発者アカウントにデプロイします。
$ ask deploy 

# この例に表示された商品IDは切り捨てられていることに注意してください。
# statusでは完全な商品IDを次の形式で表示します。
# amzn1.adg.product.aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

スキルに関連付けられた商品は、ask remove ispコマンドでリンク解除できます。商品がスキルから関連解除され、商品に関連付けられたJSONファイルが削除されます。スキルの公開バージョンで商品が購入可能になったことがない場合に限り、開発ステージのスキルから商品にこのコマンドを使用できます。

  • ask remove ispコマンドを使用して、商品のデプロイステータスを「削除」に設定します
  • ask status --ispを使用して、商品がデプロイから削除されることを確認します
  • ask deployまたは ask deploy --target ispコマンドを使用して、ローカルでの変更を開発者アカウントにデプロイします。

商品を削除する前に、後で使用する時に備えて別のロケーションにファイルをバックアップすることをお勧めします。

以下は、スキルの商品のステータスをチェックし、ファイル名を指定して商品を削除する方法を示します。

$ cd my-existing-skill-name

# 「ask status --isp」チェックを使用して、現在のスキルに関連付けられているISPをチェックします。
# スキルに関連付けられた商品のステータスはUpdateです
$ ask status --isp
デプロイする購入可能なスキル内商品:
    (現在のスキルにスキル内商品を追加する場合は「ask add isp --file <filePath>/--isp-id <id>」を使用します)
    (現在のスキルからスキル内商品を削除する場合は「ask remove isp --file <filePath>/--isp-id <id>」を使用します)

デプロイステータス | ID                                   | ファイル              
Update        | amzn1.adg.product.0dc13545-bb0c-1...  | isps/entitlement/cave_quest.json 
Update        | amzn1.adg.product.0dc13545-bb0c-2...  | isps/subscription/treasure_finders.json

# ASK CLIスキルプロジェクトのルートディレクトリで 
# removeコマンドを使用します。
$ ask remove isp --file isps/entitlement/cave_quest.json

# 再度ステータスをチェックして、ステータスがremoveになっていることを確認します。
$ ask status --isp
デプロイする購入可能なスキル内商品:
    (現在のスキルにスキル内商品を追加する場合は「ask add isp --file <filePath>/--isp-id <id>」を使用します)
    (現在のスキルからスキル内商品を削除する場合は「ask remove isp --file <filePath>/--isp-id <id>」を使用します)

デプロイステータス | ID                                   | ファイル                 
Remove       | amzn1.adg.product.0dc13545-bb0c-111-11  | isps/entitlement/cave_quest.json
Update        | amzn1.adg.product.92fef67c-2da3-111-11  | isps/subscription/treasure_finders.json

# 変更をデプロイします。
$ ask deploy --target isp

$ ask status --isp
デプロイする購入可能なスキル内商品:
    (現在のスキルにスキル内商品を追加する場合は「ask add isp --file <filePath>/--isp-id <id>」を使用します)
    (現在のスキルからスキル内商品を削除する場合は「ask remove isp --file <filePath>/--isp-id <id>」を使用します)

デプロイステータス | ID                                   | ファイル              
Update        | amzn1.adg.product.92fef67c-2da3-111-11  | isps/subscription/treasure_finders.json

# この例に表示された商品IDは切り捨てられていることに注意してください。
# statusでは完全な商品IDを次の形式で表示します。
# amzn1.adg.product.aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

商品を含むスキルのファイル構造

追加のispコマンドを使用すると、スキルプロジェクトにispsフォルダが追加され、consumableentitlementsubscriptionというサブフォルダが追加されます。consumableentitlementsubscriptionの各フォルダには、各プロジェクトの商品説明ファイル(*ispName*.json)が含まれます。

以下は、商品が追加された際にスキルプロジェクトがどのように表示されるかの例です。

skillName
│   skill.json
├───.ask
│       config
│       
├───isps
│   │   
│   ├───consumable
│   │       ispName1.json
│   │       
│   ├───entitlement
│   │       ispName2.json
│   │       
│   └───subscription
│           ispName3.json
│           
├───lambda
│   └───custom
│       │   index.js
│                       
└───models
        ja-JP.json

商品ファイルの例

商品のJSONファイルの例については、以下を参照してください。

これらのファイルはテンプレートから作成されるため、publishingInformationkeywordscustomProductPromptssmallIconUrilargeIconUriboughtCardDescriptionpricingなどの各オブジェクトをユーザーの商品に合わせて変更する必要があります。これらのフィールドの意味について詳しくは、商品スキーマの各部分を参照してください。

スキルコンフィギュレーションファイルの商品リスト

スキルに商品が関連付けられている場合、スキルのコンフィギュレーションファイル(.ask/config)には、商品ID、商品のファイルの場所、商品のステータスなどを含むin_skill_productsがあります。例を次に示します。

{
  "deploy_settings": {
    "default": {
      "skill_id": "amzn1.ask.skill.b1845aa7-0fac-1234-1111-5f1f478ca",
      "was_cloned": false,
      "merge": {
        "manifest": {
          "apis": {
            "custom": {
              "endpoint": {
                "uri": "ask-some-endpoint-profile"
              }
            }
          }
        }
      },
      "in_skill_products": [
        {
          "productId": "amzn1.adg.product.0dc13545-bb0c-111-11",
          "filePath": "isps/entitlement/cave_quest.json",
          "deploy_status": "Update",
          "eTag": "tag_1"
        },
        {
          "productId": "amzn1.adg.product.0dc13545-bb0c-222-22",
          "filePath": "isps/subscription/treasure_finders.json",
          "deploy_status": "Update",
          "eTag": "tag_2"
        },
        {
          "productId": "amzn1.adg.product.0dc13545-bb0c-333-33",
          "filePath": "isps/consumable/clues.json",
          "deploy_status": "Update",
          "eTag": "tag_3"
        }
      ]
    }
  }
}

ASK CLIリファレンス:

スキル内課金の実装: