AlexaショッピングアクションのAPIリファレンス

AlexaショッピングアクションのAPIリファレンス

スキルにショッピングエクスペリエンスを追加するには、Amazonリテールウェブサイトで商品をお勧めするAlexaショッピングアクションAPIを使用します。スキルは、Skill Connectionsを使ってAmazonの定義済みタスクを呼び出し、Alexaショッピングの対話を開始します。Skill Connectionsを使用すると、スキルは別のスキルを使用して特定のタスクを実行します。AlexaショッピングアクションAPIを使用する前に、以下のトピックを確認してください。

APIをスキルに実装する方法の例については、スキルにAlexaショッピングアクションを実装するを参照してください。

ショッピングアクション

Alexaショッピングアクションには、次のタスクが含まれます。

ショッピングアクション タスク名とバージョン

リストに追加する

connection://AMAZON.AddToList/1

ショッピングカートに追加する

connection://AMAZON.AddToShoppingCart/1

商品を購入する

connection://AMAZON.BuyShoppingProducts/1

商品をお勧めする

connection://AMAZON.RecommendShoppingProducts/1

リストに追加する

指定されたアイテムをユーザーのAmazonほしい物リストに追加します。現時点では、このアクションはほしい物リストでのみ機能します。Amazon買い物リストでは機能しません。

リクエスト

ユーザーのほしい物リストに商品を追加するには、Connections.StartConnectionディレクティブを応答に追加します。

リクエストの例

{
  "type": "Connections.StartConnection",
  "uri": "connection://AMAZON.AddToList/1",
  "input": {
    "products": [
      {
        "asin": "ASIN1"
      }
  ],
  "listType": "WISHLIST"
  },
  "token": "スキル固有のセッション情報"
}

リクエストのパラメーター

次の表は、タスク固有のinputパラメーターの定義を示しています。

フィールド 説明 型 必須

input

タスクリクエストの入力パラメーターです。

オブジェクト

◯

input.products

Amazon商品のリストです。
最大アイテム数： 1。

ProductEntityオブジェクトの配列

◯

input.products[].asin

商品のAmazonシステム識別子です。詳しくは、商品のASINを参照してください。

文字列

◯

input.listType

リストの種類を指定します。
有効な値： WISHLIST

文字列

◯

応答

タスクは、アクションの結果を含むSessionResumedRequest応答を返します。アクションが成功したかどうかを判断するには、cause.statusパラメーターとタスク固有のcause.resultパラメーターを確認します。cause.statusパラメーターには、HTTPステータスコードが含まれます。ステータスコードの一覧については、SessionResumedRequestのステータスコードアトリビュートを参照してください。

応答の例

以下は、成功した応答の例です。

{
    "type": "SessionResumedRequest",
    "requestId": "リクエストの一意ID",
    "timestamp": "2022-04-11T15:15:25Z",
    "locale": "ja-JP",
    "cause": {
        "type": "ConnectionCompleted",
        "token": "スキルセッションを復元するためのスキル固有のセッション情報",
        "status": {
            "code": "200",
            "message": "OK"
        }
    }
}

応答のパラメーター

次の表は、タスク固有のresultパラメーターの定義を示しています。resultパラメーターはオプションです。戻り値の詳細については、結果コードを参照してください。

フィールド 説明 型 必須

code

エラーを識別します。

文字列

◯

message

人が読める形式でのエラーの説明です。

文字列

◯

結果コード

コード メッセージ 説明

AlexaShopping.InternalError

現時点では、リクエストを処理することができません。リクエストを再試行してください。このエラーが繰り返し発生する場合は、カスタマーサポートにお問い合わせください。

内部の問題または障害のため、Alexaショッピングでリクエストを完了できません。

AlexaShopping.InvalidTaskForMarketplace

この操作はこのロケールでは利用できません。

リクエストされたAlexaショッピングアクションはこのロケールでサポートされていません。

AlexaShopping.ItemNotEligible

指定された商品はAlexaショッピングアクションでは購入できません。
または、Alexaショッピングを使って商品にアクセスすることはできません。

商品がAlexaショッピングでは利用できないことを表しています。
たとえば、デジタル商品の場合や、法的な理由でサポートされていない商品の場合などが考えられます。

AlexaShopping.NoOffersFound

リクエストに一致する商品は見つかりませんでした。

リクエストされたアイテムが見つかりませんでした。たとえば、在庫切れの場合などが考えられます。

AlexaShopping.RetryLaterError

リクエストを処理しようとした際にエラーが発生しました。後でもう一度試してください。

タスクの実行中に問題が発生しました。たとえば、ユーザーの設定が無効な場合や、Alexaショッピングに一時的な問題が発生している場合などが考えられます。
この問題は復旧可能です。後でもう一度試してください。

ショッピングカートに追加する

指定されたアイテムをユーザーのショッピングカートに追加します。このアクションはデジタル商品以外でのみ機能します。詳しくは、Alexaショッピングアクションのよくある質問を参照してください。

リクエスト

ユーザーのショッピングカートに商品を追加するには、Connections.StartConnectionディレクティブを応答に追加します。

リクエストの例

{
  "type": "Connections.StartConnection",
  "uri": "connection://AMAZON.AddToShoppingCart/1",
  "input": {
    "products": [
      {
        "asin": "ASIN1",
        "attribution": {
            "associateId": "some.associate.id",
            "trackingId": "some.tracking.id"
        }
      }
    ]
  },
  "token": "スキル固有のセッション情報"
}

リクエストのパラメーター

次の表は、タスク固有のinputパラメーターの定義を示しています。

フィールド 説明 型 必須

input

タスクリクエストの入力パラメーターです。

オブジェクト

◯

input.products

Amazon商品のリストです。
最大アイテム数： 1。

ProductEntityオブジェクトの配列

◯

input.products[].asin

商品のAmazonシステム識別子です。
詳しくは、商品のASINを参照してください。

文字列

◯

input.products[].attribution

スキルがAmazon Associates on Alexaプログラムに参加している場合に指定します。

Attributionオブジェクト

✕

応答

タスクは、アクションの結果を含むSessionResumedRequest応答を返します。アクションが成功したかどうかを判断するには、cause.statusパラメーターとタスク固有のcause.resultパラメーターを確認します。cause.statusパラメーターには、HTTPステータスコードが含まれます。ステータスコードの一覧については、SessionResumedRequestのステータスコードアトリビュートを参照してください。

応答の例

以下は、エラー応答の例です。

{
    "type": "SessionResumedRequest",
    "requestId": "リクエストの一意ID",
    "timestamp": "2022-04-11T15:15:25Z",
    "locale": "ja-JP",
    "cause": {
        "type": "ConnectionCompleted",
        "token": "スキルセッションを復元するためのスキル固有のセッション情報",
        "status": {
            "code": "200",
            "message": "OK"
        },
        "result": {
            "code": "AlexaShopping.RetryLaterError",
            "message": "リクエストを処理しようとした際にエラーが発生しました。後でもう一度試してください。"
        }
    }
}

応答のパラメーター

次の表は、タスク固有のresultパラメーターの定義を示しています。resultパラメーターはオプションです。戻り値の詳細については、結果コードを参照してください。

フィールド 説明 型 必須

code

エラーを識別します。

文字列

◯

message

人が読める形式でのエラーの説明です。

文字列

◯

結果コード

コード メッセージ 説明

AlexaShopping.InternalError

現時点では、リクエストを処理することができません。リクエストを再試行してください。このエラーが繰り返し発生する場合は、カスタマーサポートにお問い合わせください。

内部の問題または障害のため、Alexaショッピングでリクエストを完了できません。

AlexaShopping.InvalidTaskForMarketplace

この操作はこのロケールでは利用できません。

リクエストされたAlexaショッピングアクションはこのロケールでサポートされていません。

AlexaShopping.ItemNotEligible

指定された商品はAlexaショッピングアクションでは購入できません。
または、Alexaショッピングを使って商品にアクセスすることはできません。

商品がAlexaショッピングでは利用できないことを表しています。
たとえば、デジタル商品の場合や、法的な理由でサポートされていない商品の場合などが考えられます。

AlexaShopping.NoOffersFound

リクエストに一致する商品は見つかりませんでした。

リクエストされたアイテムが見つかりませんでした。たとえば、在庫切れの場合などが考えられます。

AlexaShopping.RetryLaterError

リクエストを処理しようとした際にエラーが発生しました。後でもう一度試してください。

タスクの実行中に問題が発生しました。たとえば、ユーザーの設定が無効な場合や、Alexaショッピングに一時的な問題が発生している場合などが考えられます。
この問題は復旧可能です。後でもう一度試してください。

商品購入アクション

指定された商品を購入します。リクエストを応答ハンドラーのディレクティブ入力として追加します。

リクエスト

ユーザーが商品を購入できるようにするには、Connections.StartConnectionディレクティブを応答に追加します。

リクエストの例

{
    "type": "Connections.StartConnection",
    "uri": "connection://AMAZON.BuyShoppingProducts/1",
    "input": {
        "products": [{
            "asin": "ASIN1",
            "attribution": {
                "associateId": "some.associate.id",
                "trackingId": "some.tracking.id"
            }
        }]
    },
    "token": "PurchaseProductToken"
}

リクエストのパラメーター

次の表は、タスク固有のinputパラメーターの定義を示しています。

フィールド 説明 型 必須

input

タスクリクエストの入力パラメーターです。

オブジェクト

◯

input.products

Amazon商品のリストです。
最大アイテム数： 1。

ProductEntityオブジェクトの配列

◯

input.products[].asin

商品のAmazonシステム識別子です。
詳しくは、商品のASINを参照してください。

文字列

◯

input.products[].attribution

スキルがAmazon Associates on Alexaプログラムに参加している場合に指定します。

Attributionオブジェクト

✕

応答

タスクは、アクションの結果を含むSessionResumedRequest応答を返します。アクションが成功したかどうかを判断するには、cause.statusパラメーターとタスク固有のcause.resultパラメーターを確認します。cause.statusパラメーターには、HTTPステータスコードが含まれます。ステータスコードの一覧については、SessionResumedRequestのステータスコードアトリビュートを参照してください。

応答の例

以下は、エラー応答の例です。

{
    "type": "SessionResumedRequest",
    "requestId": "リクエストの一意ID",
    "timestamp": "2022-04-11T15:15:25Z",
    "locale": "ja-JP",
    "cause": {
        "type": "ConnectionCompleted",
        "token": "スキルセッションを復元するためのスキル固有のセッション情報",
        "status": {
            "code": "200",
            "message": "OK"
        },
        "result": {
            "code": "AlexaShopping.RetryLaterError",
            "message": "リクエストを処理しようとした際にエラーが発生しました。後でもう一度試してください。"
        }
    }
}

応答のパラメーター

次の表は、タスク固有のresultパラメーターの定義を示しています。resultパラメーターはオプションです。戻り値の詳細については、結果コードを参照してください。

フィールド 説明 型 必須

code

エラーを識別します。

文字列

◯

message

人が読める形式でのエラーの説明です。

文字列

◯

結果コード

コード メッセージ 説明

AlexaShopping.InternalError

現時点では、リクエストを処理することができません。リクエストを再試行してください。このエラーが繰り返し発生する場合は、カスタマーサポートにお問い合わせください。

内部の問題または障害のため、Alexaショッピングでリクエストを完了できません。

AlexaShopping.InvalidTaskForMarketplace

この操作はこのロケールでは利用できません。

リクエストされたAlexaショッピングアクションはこのロケールでサポートされていません。

AlexaShopping.ItemNotEligible

指定された商品はAlexaショッピングアクションでは購入できません。
または、Alexaショッピングを使って商品にアクセスすることはできません。

商品がAlexaショッピングでは利用できないことを表しています。
たとえば、デジタル商品の場合や、法的な理由でサポートされていない商品の場合などが考えられます。

AlexaShopping.NoOffersFound

リクエストに一致する商品は見つかりませんでした。

リクエストされたアイテムが見つかりませんでした。たとえば、在庫切れの場合などが考えられます。

AlexaShopping.RetryLaterError

リクエストを処理しようとした際にエラーが発生しました。後でもう一度試してください。

タスクの実行中に問題が発生しました。たとえば、ユーザーの設定が無効な場合や、Alexaショッピングに一時的な問題が発生している場合などが考えられます。
この問題は復旧可能です。後でもう一度試してください。

商品をお勧めする

ユーザーに商品をお勧めします。リクエストを応答ハンドラーのディレクティブ入力として追加します。

リクエスト

ユーザーが特定の商品のお勧めを聞けるようにするには、Connections.StartConnectionディレクティブを応答に追加します。

リクエストの例

{
    "type": "Connections.StartConnection",
    "uri": "connection://AMAZON.RecommendShoppingProducts/1",
    "input": {
        "products": [{
                "asin": "ASIN1"
            },
            {
                "asin": "ASIN2",
            },
            {
                "asin": "ASIN3"
            }
        ],
        "attribution": {
            "associateId": "some.associate.id.1",
            "trackingId": "some.tracking.id.1"
        }
    },
    "token": "RecommendProducts",
    "onCompletion": "SEND_ERRORS_ONLY"
}

リクエストのパラメーター

次の表は、タスク固有のinputパラメーターの定義を示しています。

フィールド 説明 型 必須

input

タスクリクエストの入力パラメーターです。

オブジェクト

◯

input.products

Amazon商品のリストです。
最大アイテム数： 10。

ProductEntityオブジェクトの配列

◯

input.products[].asin

商品のAmazonシステム識別子です。
詳しくは、商品のASINを参照してください。

文字列

◯

input.attribution

スキルがAmazon Associates on Alexaプログラムに参加している場合に指定します。このアトリビューションはすべての商品に適用されます。

Attributionオブジェクト

✕

応答

Alexaは、Skill Connectionsが失敗した場合にのみ応答を送信します。詳しくは、System.ExceptionEncounteredを参照してください。

応答の例

以下は、エラー応答の例です。

{
    "type": "System.ExceptionEncountered",
    "requestId": "リクエストの一意ID",
    "timestamp": "2022-04-11T15:15:25Z",
    "locale": "ja-JP",
    "error": {
        "type": "error code",
        "message": "発生したエラーの説明"
    },
    "cause": {
        "requestId": "エラーの原因となったタスクの一意ID"
    }
}

応答のパラメーター

タスク固有の応答パラメーターはありません。cause.requestIdを使用して、エラーとリクエストを関連付けます。

オブジェクトの定義

Attributionオブジェクト

対象の購入について紹介料を得るには、Attributionオブジェクトをショッピングアクションリクエストに含めます。このオブジェクトは、Amazon Associates on Alexaプログラムに参加している公開中のスキルにのみ含めてください。

次の表は、Attributeオブジェクトの定義を示しています。

フィールド 説明 型 必須

associateId

アソシエイトアカウントを識別します。

文字列

◯

trackingId

このスキルを追跡するためのオプションの識別子です。
アソシエイトアカウントの追跡IDについて詳しくは、Using Tracking IDsを参照してください。

文字列

✕

ProductEntityオブジェクト

ProductEntityオブジェクトは、Amazon内の一意の商品を表します。商品の識別子を見つけるには、Amazonリテールウェブサイトの商品詳細ページに記載されているAmazon Standard Identification Number（ASIN）を参照してください。詳しくは、商品IDを参照してください。

フィールド 説明 型 必須

asin

商品のAmazonシステム識別子です。詳しくは、商品のASINを参照してください。

文字列

◯

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

最終更新日: 2022 年 12 月 02 日