有料スキルインターフェースのリファレンス

有料スキルインターフェースのリファレンス

有料スキルインターフェースには、スキルの購入ステータスを確認し、Amazonの購入フローとキャンセルフローを呼び出すAPIが含まれます。

ユーザーの購入ステータスクエリ

各スキルセッションの開始時にユーザーの購入ステータスを取得し、購入フローを呼び出すか有料スキルコンテンツを継続するかを判断します。このインターフェースは、ユーザーがスキルを購入した場合または無料お試し中の場合、ENTITLEDを返します。無料お試し期間が終了している場合、ユーザーがサブスクリプションをキャンセルした場合、ユーザーが対象のスキルを購入していない場合は、NOT_ENTITLEDが返され、ユーザーがスキルを購入できるかどうかが示されます。

特定のアクティビティのユーザーの購入ステータスを取得するには、inSkillProductsリソースに対してHTTP GETリクエストを実行します。

リクエスト

クリップボードにコピーされました。

GET /v1/users/~current/skills/~current/inSkillProducts/{id}
Host: {apiEndpoint}
Accept-Language: {locale}
Authorization: Bearer {apiAccessToken}

ヘッダーパラメーターの詳細をリクエストする

フィールド 説明 型

id

有料スキルを識別します。このフィールドではスキルIDを使用します。

文字列

apiEndpoint

LaunchRequestまたはIntentRequestからSystemオブジェクトのapiEndpointプロパティに設定します。

文字列

locale

ユーザーのロケールに設定します。例：en-US

文字列

apiAccessToken

認証と認可に使用するアクセストークンです。LaunchRequestまたはIntentRequestからSystemオブジェクトのapiAccessTokenプロパティに設定します。

文字列

このリクエスト本文は空です。

応答

応答を使用して、お勧めを提示するか有料スキルコンテンツを継続するかを決定します。以下は、購入可能な開発段階のスキルへの応答の例です。

{
  "productId": "amzn1.ask.skill.efd6d738-0a1b-4f14-ae0f-6e2174bd6be3",
  "name": "スキル名",
  "type": "ENTITLEMENT",
  "summary": "スキルの説明",
  "purchasable": "PURCHASABLE",
  "entitled": "NOT_ENTITLED",
  "entitledReason": "NOT_PURCHASED",
  "activeEntitlementCount": 0,
  "purchaseMode": "TEST",
  "referenceName": ""
}

以下の表に応答コードを示します。

HTTPステータスコード HTTPステータス 説明

200

Success

リクエストされたスキルと購入ステータスを返します。

400

Invalid Request

リクエストが無効であることを示します。応答本文に、リクエストが無効である理由を示す特定のエラーメッセージを含めることができます。

401

Unauthorized

リクエストに認可トークンが含まれていない、トークンが無効または有効期限切れ、またはスキルにリクエストの権限がありません。

404

Not Found

指定されたアクティビティIDのスキルが見つかりません。このエラーは、スキルの最新版を公開し、そのスキルを本番環境で使用できない場合に表示されることがあります。

500

Server Error

サーバーでエラーが発生しました。スキルの再試行には指数バックオフを使用します。

応答本文パラメーターの詳細

成功すると、応答本文にスキル購入の詳細が含まれます。

フィールド 説明 型

productId

有料スキルを識別します。スキルIDに設定します。

文字列

name

localeリクエストパラメーターで指定された言語でのスキルの名前です。

文字列

type

スキルの支払いモデルです。
有効値： SUBSCRIPTION（サブスクリプション型）またはENTITLEMENT（買い切り型）。

列挙型文字列

summary

localeリクエストパラメーターで指定された言語でのスキルの説明です。

文字列

purchasable

ユーザーがこのスキルを購入できるかどうかを示します。ユーザーが既にスキルを所有している場合、NOT_PURCHASABLEに設定されます。
有効値： PURCHASABLEまたはNOT_PURCHASABLE。

列挙型文字列

entitled

ユーザーがこの有料スキルを使用できるかどうかを示します。
有効値： ENTITLEDまたはNOT_ENTITLED。

列挙型文字列

entitledReason

entitledのステータスの理由を示します。ユーザーが無料お試しを使用している場合やスキルを既に購入している場合は、entitledReasonがPURCHASEDになります。AUTO_ENTITLEDは、ユーザーがプロモーションの一環として、またはそのほかの理由でスキルを取得していることを意味します。有効値： PURCHASED、NOT_PURCHASED、AUTO_ENTITLED。

列挙型文字列

activeEntitlementCount

（省略可能）有料スキルについては常にゼロに設定されます。

整数

purchaseMode

ユーザーが公開中と開発段階のどちらでスキルを購入したかを示します。開発段階ではユーザーに対する課金は発生しません。
有効値： LIVEまたはTEST。

列挙型文字列

referenceName

（省略可能）有料スキルについては常に空の文字列に設定します。

文字列

エラーの場合、応答本文にエラーの理由を示すmessage文字列を含めることができます。

Buyリクエスト

Amazon購入フローを開始するには、インテントハンドラーからAlexaへの応答にConnections.SendRequestディレクティブを含めます。このディレクティブは、Skill Connectionsインターフェースを使用してBuyタスクを呼び出します。有料スキルを識別するには、productIDをスキルIDに設定します。

以下の例は、購入フローを開始するリクエストを示しています。

クリップボードにコピーされました。

このサンプルコードはAlexa Skills Kit SDK for Node.js（v2）を使用しています。

return handlerInput.responseBuilder
        .addDirective({
            type: "Connections.SendRequest",
            name: "Buy",
            payload: {
                InSkillProduct: {
                    productId: "amzn1.ask.skill.efd6d738-0a1b-4f14-ae0f-6e2174bd6be3",
                }
            },
            token: "correlationToken"
        })
        .getResponse();

クリップボードにコピーされました。

購入リクエストのConnections.SendRequestディレクティブのJSON構文です。

{
  "directives": [
    {
      "type": "Connections.SendRequest",
      "name": "Buy",
      "payload": {
        "InSkillProduct": {
          "productId": "amzn1.ask.skill.efd6d738-0a1b-4f14-ae0f-6e2174bd6be3"
        }
      },
      "token": "correlationToken"
    }
  ]
}

Buyタスクの定義

プロパティ 説明 型

type

リクエストのタイプです。
このプロパティはConnections.SendRequestに設定します。

文字列

name

呼び出すタスクの名前です。
このプロパティはBuyに設定します。

文字列

payload

購入に必要なパラメーターが含まれます。

Payloadリクエストオブジェクト

token

（オプション）購入フローが完了したときにAlexaが応答で返す文字列です。たとえば、このトークンを使用して、購入後にスキルを再開するための情報を保存できます。

文字列

リクエストをキャンセルする

キャンセルリクエストの場合は、インテントハンドラーからAlexaへの応答にConnections.SendRequestディレクティブを含めます。このディレクティブは、Skill Connectionsインターフェースを使用してCancelタスクを呼び出します。有料スキルを識別するには、productIDをスキルIDに設定します。

以下の例は、キャンセルフローを開始するリクエストを示しています。

クリップボードにコピーされました。

このサンプルコードはAlexa Skills Kit SDK for Node.js（v2）を使用しています。

return handlerInput.responseBuilder
        .addDirective({
            type: 'Connections.SendRequest',
            name: 'Cancel',
            payload: {
                InSkillProduct: {
                    productId: "amzn1.ask.skill.efd6d738-0a1b-4f14-ae0f-6e2174bd6be3",
                }
            },
            token: "correlationToken"
        })
        .getResponse();

クリップボードにコピーされました。

キャンセルリクエストのConnections.SendRequestディレクティブのJSON構文です。

{
  "directives": [
    {
      "type": "Connections.SendRequest",
      "name": "Cancel",
      "payload": {
        "InSkillProduct": {
          "productId": "amzn1.ask.skill.efd6d738-0a1b-4f14-ae0f-6e2174bd6be3"
        }
      },
      "token": "correlationToken"
    }
  ]
}

Cancelタスクの定義

プロパティ 説明 型

type

リクエストのタイプです。
このプロパティはConnections.SendRequestに設定します。

文字列

name

呼び出すタスクの名前です。
このプロパティはCancelに設定します。

文字列

payload

購入に必要なパラメーターが含まれます。

Payloadリクエストオブジェクト

token

（オプション）購入フローが完了したときにAlexaが応答で返す文字列です。たとえば、このトークンを使用して、キャンセル後にスキルを再開するための情報を保存できます。

文字列

購入とキャンセルの応答

スキルは、購入またはキャンセルリクエストの結果をConnections.Responseリクエストとして受け取ります。payloadに含まれるpurchaseResultに基づいてスキルを再開します。

以下は、購入フローへの応答の例です。

{
    "type": "Connections.Response",
    "requestId": "string",
    "timestamp": "string",
    "name": "Buy",
    "status": {
        "code": "200",
        "message": "OK"
    },
    "payload": {
        "purchaseResult": "ACCEPTED",
        "productId": "amzn1.ask.skill.efd6d738-0a1b-4f14-ae0f-6e2174bd6be3",
        "message": "任意の追加メッセージ"
    },
    "token": "correlationToken"
}

Connections.Responseの定義

プロパティ 説明 型

type

リクエストのタイプです。常にConnections.Responseに設定します。

文字列

requestId

Connections.Responseリクエストの一意のIDです。

文字列

timeStamp

Connections.Responseリクエストの時間です。

文字列

name

この応答が適用されるリクエストの名前です。
BuyまたはCancelに設定します。

文字列

status

HTTPステータスの結果です。

Statusオブジェクト

payload

購入またはキャンセルリクエストの結果を含みます。

Payload応答オブジェクト

token

（オプション）購入またはキャンセルフローが完了したときにAlexaが応答で返す文字列です。たとえば、このトークンを使用して、購入後にスキルを再開するための情報を保存できます。

文字列

オブジェクトの定義

Payloadリクエストオブジェクト

このリクエストに含まれるPayloadオブジェクトは有料スキルを定義します。

Payloadオブジェクトの詳細

プロパティ 説明 型

products

有料スキルを定義します。1つのオブジェクトを含みます。

InSkillProductオブジェクトの配列

InSkillProductオブジェクト

InSkillProductオブジェクトは有料スキルIDを定義します。AlexaはこのスキルIDを使用して購入の詳細を検索します。

InSkillProductオブジェクトの詳細

プロパティ 説明 型

productId

自分のスキルIDに設定します。

文字列

Payload応答オブジェクト

Connections.Responseリクエストに含まれているPayloadオブジェクトです。

Payloadオブジェクトの詳細

プロパティ 説明 型

purchaseResults

購入またはキャンセルリクエストの結果です。
有効値： ACCEPTED、DECLINED、ALREADY_PURCHASED、ERROR。

以下の結果に応じてスキルを継続します。

  • ACCEPTED – 購入リクエストからの結果である場合、購入フローが成功したことを示します。有料コンテンツを継続してください。キャンセルリクエストからの結果である場合、キャンセルフローが成功したことを示します。無料コンテンツを継続するか、スキルセッションを終了してください。

  • DECLINED – 購入リクエストからの結果である場合、ユーザーがスキルの購入を断ったことを示します。無料コンテンツを継続するか、スキルセッションを終了してください。キャンセルリクエストからの結果である場合、ユーザーがキャンセルを断ったことを示します。有料コンテンツを継続してください。

  • ALREADY_PURCHASED – この結果は購入リクエストのみに該当します。この結果はユーザーが以前にスキルを購入していることを示します。有料コンテンツを継続してください。

  • ERROR – 購入フローおよびキャンセルフローで、Alexaがエラーの発生理由をユーザーに伝えます。エラーメッセージを繰り返したり、ユーザーに再試行を求めたりしないでください。代わりに、スキルセッションを終了します。

文字列

productId

リクエストで送信された有料スキルIDです。

文字列

message

（オプション）キャンセルまたは購入トランザクションに関するそのほかの詳細です。

文字列

Statusオブジェクト

リクエストに含まれるStatusオブジェクトです。

Statusオブジェクトの詳細

プロパティ 説明 型

code

HTTP応答のステータス（200、400、404など）です。

文字列

message

HTTPステータスメッセージ（OKなど）です。

文字列

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

最終更新日: 2022 年 01 月 24 日