AlexaショッピングアクションのAPIリファレンス
スキルにショッピングエクスペリエンスを追加するには、Amazonリテールウェブサイトで商品をお勧めするAlexaショッピングアクションAPIを使用します。スキルは、Skill Connectionsを使ってAmazonの定義済みタスクを呼び出し、Alexaショッピングの対話を開始します。Skill Connectionsを使用すると、スキルは別のスキルを使用して特定のタスクを実行します。AlexaショッピングアクションAPIを使用する前に、以下のトピックを確認してください。
APIをスキルに実装する方法の例については、スキルにAlexaショッピングアクションを実装するを参照してください。
ショッピングアクション
Alexaショッピングアクションには、次のタスクが含まれます。
ショッピングアクション | タスク名とバージョン |
---|---|
| |
| |
| |
|
リストに追加する
指定されたアイテムをユーザーのAmazonほしい物リストに追加します。現時点では、このアクションはほしい物リストでのみ機能します。Amazon買い物リストでは機能しません。
この機能は開発者プレビュー段階です。フィードバックに基づく改善や今後の機能強化によって変更される場合があります。この機能を使用するには、Amazonビジネス担当者にご相談ください。
リクエスト
ユーザーのほしい物リストに商品を追加するには、Connections.StartConnection
ディレクティブを応答に追加します。
リクエストの例
{
"type": "Connections.StartConnection",
"uri": "connection://AMAZON.AddToList/1",
"input": {
"products": [
{
"asin": "ASIN1"
}
],
"listType": "WISHLIST"
},
"token": "スキル固有のセッション情報"
}
リクエストのパラメーター
次の表は、タスク固有のinput
パラメーターの定義を示しています。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
タスクリクエストの入力パラメーターです。 |
オブジェクト |
◯ |
|
Amazon商品のリストです。 |
|
◯ |
|
商品のAmazonシステム識別子です。詳しくは、商品のASINを参照してください。 |
文字列 |
◯ |
|
リストの種類を指定します。 |
文字列 |
◯ |
応答
タスクは、アクションの結果を含むSessionResumedRequest
応答を返します。アクションが成功したかどうかを判断するには、cause.status
パラメーターとタスク固有のcause.result
パラメーターを確認します。cause.status
パラメーターには、HTTPステータスコードが含まれます。ステータスコードの一覧については、SessionResumedRequestのステータスコードアトリビュートを参照してください。
cause.result
パラメーターを確認してください。cause.status
パラメーターは、リクエストに問題がある場合でも200 OK
を返すことがあります。cause.result
パラメーターは、ショッピングアクション実行時に問題があったかどうかを示します。応答の例
以下は、成功した応答の例です。
{
"type": "SessionResumedRequest",
"requestId": "リクエストの一意ID",
"timestamp": "2022-04-11T15:15:25Z",
"locale": "ja-JP",
"cause": {
"type": "ConnectionCompleted",
"token": "スキルセッションを復元するためのスキル固有のセッション情報",
"status": {
"code": "200",
"message": "OK"
}
}
}
応答のパラメーター
次の表は、タスク固有のresult
パラメーターの定義を示しています。result
パラメーターはオプションです。戻り値の詳細については、結果コードを参照してください。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
エラーを識別します。 |
文字列 |
◯ |
|
人が読める形式でのエラーの説明です。 |
文字列 |
◯ |
結果コード
コード | メッセージ | 説明 |
---|---|---|
|
現時点では、リクエストを処理することができません。リクエストを再試行してください。このエラーが繰り返し発生する場合は、カスタマーサポートにお問い合わせください。 |
内部の問題または障害のため、Alexaショッピングでリクエストを完了できません。 |
|
この操作はこのロケールでは利用できません。 |
リクエストされたAlexaショッピングアクションはこのロケールでサポートされていません。 |
|
指定された商品はAlexaショッピングアクションでは購入できません。 |
商品がAlexaショッピングでは利用できないことを表しています。 |
|
リクエストに一致する商品は見つかりませんでした。 |
リクエストされたアイテムが見つかりませんでした。たとえば、在庫切れの場合などが考えられます。 |
|
リクエストを処理しようとした際にエラーが発生しました。後でもう一度試してください。 |
タスクの実行中に問題が発生しました。たとえば、ユーザーの設定が無効な場合や、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
パラメーターの定義を示しています。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
タスクリクエストの入力パラメーターです。 |
オブジェクト |
◯ |
|
Amazon商品のリストです。 |
|
◯ |
|
商品のAmazonシステム識別子です。 |
文字列 |
◯ |
|
スキルがAmazon Associates on Alexaプログラムに参加している場合に指定します。 |
|
✕ |
応答
タスクは、アクションの結果を含むSessionResumedRequest
応答を返します。アクションが成功したかどうかを判断するには、cause.status
パラメーターとタスク固有のcause.result
パラメーターを確認します。cause.status
パラメーターには、HTTPステータスコードが含まれます。ステータスコードの一覧については、SessionResumedRequestのステータスコードアトリビュートを参照してください。
cause.result
パラメーターを確認してください。cause.status
パラメーターは、リクエストに問題がある場合でも200 OK
を返すことがあります。cause.result
パラメーターは、ショッピングアクション実行時に問題があったかどうかを示します。応答の例
以下は、エラー応答の例です。
{
"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
パラメーターはオプションです。戻り値の詳細については、結果コードを参照してください。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
エラーを識別します。 |
文字列 |
◯ |
|
人が読める形式でのエラーの説明です。 |
文字列 |
◯ |
結果コード
コード | メッセージ | 説明 |
---|---|---|
|
現時点では、リクエストを処理することができません。リクエストを再試行してください。このエラーが繰り返し発生する場合は、カスタマーサポートにお問い合わせください。 |
内部の問題または障害のため、Alexaショッピングでリクエストを完了できません。 |
|
この操作はこのロケールでは利用できません。 |
リクエストされたAlexaショッピングアクションはこのロケールでサポートされていません。 |
|
指定された商品はAlexaショッピングアクションでは購入できません。 |
商品がAlexaショッピングでは利用できないことを表しています。 |
|
リクエストに一致する商品は見つかりませんでした。 |
リクエストされたアイテムが見つかりませんでした。たとえば、在庫切れの場合などが考えられます。 |
|
リクエストを処理しようとした際にエラーが発生しました。後でもう一度試してください。 |
タスクの実行中に問題が発生しました。たとえば、ユーザーの設定が無効な場合や、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
パラメーターの定義を示しています。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
タスクリクエストの入力パラメーターです。 |
オブジェクト |
◯ |
|
Amazon商品のリストです。 |
|
◯ |
|
商品のAmazonシステム識別子です。 |
文字列 |
◯ |
|
スキルがAmazon Associates on Alexaプログラムに参加している場合に指定します。 |
|
✕ |
応答
タスクは、アクションの結果を含むSessionResumedRequest
応答を返します。アクションが成功したかどうかを判断するには、cause.status
パラメーターとタスク固有のcause.result
パラメーターを確認します。cause.status
パラメーターには、HTTPステータスコードが含まれます。ステータスコードの一覧については、SessionResumedRequestのステータスコードアトリビュートを参照してください。
cause.result
パラメーターを確認してください。cause.status
パラメーターは、リクエストに問題がある場合でも200 OK
を返すことがあります。cause.result
パラメーターは、ショッピングアクション実行時に問題があったかどうかを示します。応答の例
以下は、エラー応答の例です。
{
"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
パラメーターはオプションです。戻り値の詳細については、結果コードを参照してください。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
エラーを識別します。 |
文字列 |
◯ |
|
人が読める形式でのエラーの説明です。 |
文字列 |
◯ |
結果コード
コード | メッセージ | 説明 |
---|---|---|
|
現時点では、リクエストを処理することができません。リクエストを再試行してください。このエラーが繰り返し発生する場合は、カスタマーサポートにお問い合わせください。 |
内部の問題または障害のため、Alexaショッピングでリクエストを完了できません。 |
|
この操作はこのロケールでは利用できません。 |
リクエストされたAlexaショッピングアクションはこのロケールでサポートされていません。 |
|
指定された商品はAlexaショッピングアクションでは購入できません。 |
商品がAlexaショッピングでは利用できないことを表しています。 |
|
リクエストに一致する商品は見つかりませんでした。 |
リクエストされたアイテムが見つかりませんでした。たとえば、在庫切れの場合などが考えられます。 |
|
リクエストを処理しようとした際にエラーが発生しました。後でもう一度試してください。 |
タスクの実行中に問題が発生しました。たとえば、ユーザーの設定が無効な場合や、Alexaショッピングに一時的な問題が発生している場合などが考えられます。 |
商品をお勧めする
ユーザーに商品をお勧めします。リクエストを応答ハンドラーのディレクティブ入力として追加します。
AMAZON.RecommendShoppingProducts
は開発者プレビュー段階です。フィードバックに基づく改善や今後の機能強化によって変更される場合があります。この機能を使用するには、Amazonビジネス担当者にご相談ください。リクエスト
ユーザーが特定の商品のお勧めを聞けるようにするには、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
パラメーターの定義を示しています。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
タスクリクエストの入力パラメーターです。 |
オブジェクト |
◯ |
|
Amazon商品のリストです。 |
|
◯ |
|
商品のAmazonシステム識別子です。 |
文字列 |
◯ |
|
スキルがAmazon Associates on Alexaプログラムに参加している場合に指定します。このアトリビューションはすべての商品に適用されます。 |
|
✕ |
応答
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プログラムに参加している公開中のスキルにのみ含めてください。
Attribution
オブジェクトを含めなかった場合は、購入について紹介料を得られません。次の表は、Attribute
オブジェクトの定義を示しています。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
アソシエイトアカウントを識別します。 |
文字列 |
◯ |
|
このスキルを追跡するためのオプションの識別子です。 |
文字列 |
✕ |
ProductEntityオブジェクト
ProductEntity
オブジェクトは、Amazon内の一意の商品を表します。商品の識別子を見つけるには、Amazonリテールウェブサイトの商品詳細ページに記載されているAmazon Standard Identification Number(ASIN)を参照してください。詳しくは、商品IDを参照してください。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
|
商品のAmazonシステム識別子です。詳しくは、商品のASINを参照してください。 |
文字列 |
◯ |
関連トピック
最終更新日: 2022 年 12 月 02 日