google-shopping-search

Google Shopping 検索

Frevana を通じて Google Shopping の商品リストを検索します。

目的

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

入力：

• q
• 省略可能な google_domain
• 省略可能な gl
• 省略可能な hl
• 省略可能な start
• 省略可能な device
• 省略可能な sort_by

出力：

• Google Shopping の商品検索結果を含む、検証済みのレスポンス JSON
• 成功するたびにローカルファイルに保存される、同じ検証済み JSON

このスキルはレスポンスが JSON であることを検証し、ディスクに保存して、変更せずに標準出力へ返します。ユーザーが変換を明示的に求めない限り、返されたデータを書き換えたり、再構成したりしないでください。

このスキルに必要なもの

• ユーザーが指定する q
• 省略可能な google_domain
• 省略可能な gl
• 省略可能な hl
• 省略可能な start
• 省略可能な device
• 省略可能な sort_by
• 環境変数内の FREVANA_TOKEN、または今回の実行時に明示的に指定する --token オプション
• curl
• bash
• python3

実行順序

リクエストをシンプルかつ確実に処理するため、次の手順を使用します。

1. ユーザーが q または同等の商品検索クエリを指定していることを確認します。
2. 場当たり的な curl コマンドよりスクリプトを優先します。
3. まずスクリプトに FREVANA_TOKEN を読み込ませます。
4. 対話型のシェルで使用する場合、FREVANA_TOKEN がないときはスクリプトが入力を求めることがあります。
5. 非対話型またはエージェントのワークフローでは、トークンがない場合はすぐに失敗させ、FREVANA_TOKEN を設定するか、明示的に --token を渡すようユーザーに伝えます。
6. スクリプトを1回実行します。検証済み JSON が標準出力に出力され、同じ JSON がファイルに保存されます。
7. 以降の解析や要約には、検索 API を再度呼び出すのではなく、保存した JSON ファイルを使用します。
8. 検証済みのレスポンス JSON を返すか、ユーザーが全データを必要としない場合は、最も関連性の高い商品を要約します。

コマンド

基本的なショッピング検索

bash <skill-path>/scripts/search_google_shopping.sh \
  --q "wireless earbuds"

--query は --q の別名として使用できます。

国、言語、Google ドメインを指定した検索

bash <skill-path>/scripts/search_google_shopping.sh \
  --q "wireless earbuds" \
  --google-domain google.com \
  --gl US \
  --hl en

ページネーション、デバイス、並び順を指定した検索

bash <skill-path>/scripts/search_google_shopping.sh \
  --q "wireless earbuds" \
  --start 20 \
  --device mobile \
  --sort-by 1

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

bash <skill-path>/scripts/search_google_shopping.sh \
  --q "wireless earbuds" \
  --gl US \
  --hl en \
  --output ./out/google-shopping-search-result.json

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

bash <skill-path>/scripts/search_google_shopping.sh \
  --q "wireless earbuds" \
  --token "your bearer token"

固定のリクエスト形式

スクリプトは、指定されていない省略可能なフィールドを除き、次の形式のペイロードを送信します。

{
  "q": "wireless earbuds",
  "google_domain": "google.com",
  "gl": "US",
  "hl": "en",
  "start": 20,
  "device": "mobile",
  "sort_by": "1"
}

必須なのは q のみです。ユーザーが指定していない場合は、google_domain、gl、hl、start、device、sort_by の値を作り出さないでください。

レスポンス形式

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

出力

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

注意事項

• --q または --query の指定が必要です
• 結果の保存と要約のためだけにスクリプトを2回実行しないでください。スクリプトは常に、出力するものと同じ JSON を保存します。
• ユーザーが google.com などの Google ドメインを指定した場合に限り、--google-domain を使用します
• ユーザーが特定の国や地域を指定した場合は、--gl を使用します
• ユーザーが特定の言語を指定した場合は、--hl を使用します
• ユーザーが結果オフセットによるページネーションを求めた場合は、--start を使用します
• --device は desktop、mobile、tablet のいずれかに限って使用します
• ユーザーが Google Shopping の並び順として指定した場合、価格の安い順には --sort-by 1、価格の高い順には --sort-by 2 を使用します
• curl がない場合は処理を中止し、curl のインストールをユーザーに伝えます
• python3 がない場合は処理を中止し、python3 のインストールをユーザーに伝えます
• Bearer トークンをユーザーにそのまま返さないでください
• ユーザーが全データを求めない限り、未加工の JSON をそのまま出力するのではなく、ユーザーが実際に関心を持っている商品検索結果を要約します

プロンプトの例

中国語

• 「Google Shopping で wireless earbuds を検索する」
• 「Google Shopping で q=running shoes、gl=US、hl=en を確認する」
• 「Google Shopping で wireless earbuds を価格の安い順に並べて検索し、生の JSON を保存する」

英語

• 「Google Shopping で wireless earbuds を検索する」
• 「gl=US と hl=en を指定して、Google Shopping で running shoes の検索結果を確認する」
• 「Google Shopping で wireless earbuds を価格の安い順に並べて検索し、生の JSON を保存する」