amazon-search

Amazon 検索

Frevana を通じて Amazon の商品一覧を検索します。

目的

このスキルは、Amazon の検索結果を見つけるためのものです。

入力：

• query または node のいずれか
• 任意の amazon_domain
• 任意の language
• 任意の delivery_zip
• 任意の shipping_location
• 任意の sort_by
• 任意の rh
• 任意の device
• 任意の no_cache
• 任意の async
• 任意の zero_trace
• 任意の page
• 任意の output。デフォルトは ./out/amazon-search-<timestamp>-<pid>.json

出力：

• Amazon の検索結果を含む、検証済みのレスポンス JSON

このスキルはレスポンスが JSON であることを検証し、変更せずに返します。ユーザーから明示的に変換を依頼されない限り、返されたデータを書き換えたり、再構成したりしないでください。

このスキルに必要なもの

• query または node のいずれか
• 任意の amazon_domain
• 任意の language
• 任意の delivery_zip
• 任意の shipping_location
• 任意の sort_by
• 任意の rh
• 任意の device
• 任意の no_cache
• 任意の async
• 任意の zero_trace
• 任意の page
• 環境変数の FREVANA_TOKEN、または今回の実行に限り明示的に指定する --token の上書き値
• curl
• bash
• python3

実行順序

リクエストをシンプルで確実なものにするため、次の手順に従います。

1. ユーザーが query または node のいずれか一方だけを指定していることを確認します。
2. その場で作成した curl コマンドではなく、スクリプトを優先します。
3. まずスクリプトに FREVANA_TOKEN を読み込ませます。
4. 対話型シェルで使用する場合、FREVANA_TOKEN が設定されていなければ、スクリプトから入力を促すことがあります。
5. 非対話型またはエージェントのワークフローでは、トークンが設定されていない場合はすぐに処理を中止し、FREVANA_TOKEN を設定するか、--token を明示的に指定するようユーザーに伝えます。
6. 検証済みのレスポンス JSON は、デフォルトで ./out/amazon-search-<timestamp>-<pid>.json に保存します。または、ユーザーが指定した --output のパスに保存します。
7. 検証済みのレスポンス JSON を返すか、ユーザーが全データを必要としていない場合は、関連性の高い商品一覧を要約します。

コマンド

基本的な検索

bash <skill-path>/scripts/search_amazon.sh \
  --query "wireless mouse"

ページと配送先 ZIP コードを指定した検索

bash <skill-path>/scripts/search_amazon.sh \
  --query "wireless mouse" \
  --delivery-zip 10001 \
  --page 2

カテゴリーノードによる検索

bash <skill-path>/scripts/search_amazon.sh \
  --node 283155 \
  --amazon-domain amazon.com \
  --language en_US

並べ替え、デバイス、配送先を指定した検索

bash <skill-path>/scripts/search_amazon.sh \
  --query "wireless mouse" \
  --shipping-location "Seattle,Washington,United States" \
  --sort-by price-asc-rank \
  --device mobile

レスポンス JSON をファイルに保存

bash <skill-path>/scripts/search_amazon.sh \
  --query "wireless mouse" \
  --delivery-zip 10001 \
  --page 1 \
  --output ./out/amazon-search-result.json

今回の実行に限りトークンを上書き

bash <skill-path>/scripts/search_amazon.sh \
  --query "wireless mouse" \
  --token "your bearer token"

リクエストのマッピング

スクリプトは、CLI オプションを次のようにリクエスト本文にマッピングします。

{
  "query": "wireless mouse",
  "amazon_domain": "amazon.com",
  "language": "en_US",
  "delivery_zip": "10001",
  "shipping_location": "Seattle,Washington,United States",
  "sort_by": "price-asc-rank",
  "rh": "n:283155,p_76:1249146011",
  "device": "mobile",
  "no_cache": true,
  "async": false,
  "zero_trace": false,
  "page": 1
}

ルール：

• query または node のいずれか一方だけを指定します。
• page は指定がない場合、デフォルトで 1 になります。
• delivery_zip は shipping_location と併用できます。エンドポイントでは delivery_zip が優先されます。
• スクリプトはローカルの --output を保存先としてのみ使用し、リクエストフィールド output は送信しません。

レスポンス形式

API は JSON を返します。このスキルはレスポンスが JSON であることを検証し、変更せずに返します。

出力

• 成功時：スクリプトはレスポンス本文が JSON であることを検証し、標準出力に出力します。
• デフォルトでは、同じ JSON が ./out/amazon-search-<timestamp>-<pid>.json に保存されます。
• --output を指定した場合：同じ JSON が指定されたファイルパスに書き込まれます。
• 失敗時：スクリプトはレスポンス本文または解析エラーを出力し、ゼロ以外の終了コードで終了します。

Notes

• --query または --node のどちらか一方だけを指定してください
• --query と --node を同時に指定しないでください
• ユーザーがマーケットプレイス固有の Amazon ドメインを必要とする場合は、--amazon-domain を使用してください
• エンドポイントで Amazon の言語を上書きする必要がある場合は、--language を使用してください
• 現在の amazon_domain と language の列挙型スナップショットについては、references/enums.md を参照してください
• ユーザーが後続の結果や1ページ目以降の選択肢を求める場合は、--page を使用してください
• 地域ごとの出品状況や配送に関する案内が重要な場合は、--delivery-zip を使用してください
• --delivery-zip の代わりに市区町村／州／国を指定する場合は、--shipping-location を使用してください
• --sort-by は、サポートされている値 review-rank、price-asc-rank、price-desc-rank、date-desc-rank、relevanceblender と組み合わせる場合にのみ使用してください
• --device は、サポートされている値 desktop、mobile と組み合わせる場合にのみ使用してください
• --no-cache、--async、--zero-trace は、ブール値 true または false と組み合わせる場合にのみ使用してください
• curl が見つからない場合は、処理を中止して、curl をインストールするようユーザーに伝えてください
• python3 が見つからない場合は、処理を中止して、python3 をインストールするようユーザーに伝えてください
• Bearer トークンをユーザーにそのまま返さないでください
• ユーザーが全ペイロードを求めていない限り、生の JSON をそのまま出力せず、ユーザーが実際に必要としている商品一覧を要約してください

プロンプトの例

中国語

• 「Amazon で wireless mouse を検索して」
• 「wireless mouse を調べて。2ページ目、ZIP は 10001」
• 「カテゴリーノード 283155 で Amazon の検索結果を調べて」
• 「wireless mouse を調べて。価格の安い順で、モバイルの結果」
• 「Amazon の検索結果を調べて、生の JSON をファイルに保存して」

英語

• 「Amazon で wireless mouse を検索して」
• 「ZIP 10001 で wireless mouse の Amazon 検索結果の2ページ目を表示して」
• 「Amazon のカテゴリーノード 283155 を検索して」
• 「Amazon で wireless mouse を検索して。モバイルで、価格の安い順に並べ替えて」
• 「このキーワードで Amazon を検索して、生の JSON をファイルに保存して」