スキル内商品サービス
Note: Sign in to the developer console to build or publish your skill.
スキル内商品サービス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
: ユーザーはこの購入を公開中のスキルで行いました。