linkfox-sorftime-walmart-keyword-research

Walmart キーワード調査

Sorftime のエンドポイントを 1 つ使用して、Walmart US のキーワードを調査するか、保存済みキーワードライブラリを明示的に管理します。

主な概念

• リクエストごとに operation を正確に 1 つ送信します。複数のキーワード操作を自動的な探索チェーンとして実行しないでください。
• フラットな JSON 本文を使用します。業務データで入れ子にできるのは、marketQuery の任意の pattern オブジェクトのみです。
• operation の値は大文字と小文字を区別します。別の操作、ページ、またはフィルターは、それぞれ追加の有料呼び出しとなります。
• favoriteAdd と favoriteChange は外部アカウントデータを変更するため、明示的で曖昧さのないユーザーの依頼が必要です。

操作の振り分け

意図	operation	必須入力	Sorftime リクエスト
現在の人気キーワードを絞り込む	marketQuery	なし。フィルターは任意	5
名前から人気キーワードを見つける	searchByName	name	1
人気キーワードの商品を見つける	searchProducts	keyword	5
キーワードの指標を確認する	detail	keyword	1
商品に関連付けられたキーワードを見つける	productKeywords	productId	1
関連キーワードを広げて調べる	relatedKeywords	keyword	5
キーワードを保存済みに追加する	favoriteAdd	keyword	1
保存済みキーワードを削除または移動する	favoriteChange	keyword、command	0
保存済みキーワードまたはフォルダーを一覧表示する	favoriteList	command	1

呼び出す前に、条件付きパラメーターの完全な一覧を references/api.md で確認してください。

パラメーターガイド

• marketQuery：pattern.keyword、pattern.rankCondition、pattern.searchVolumeCondition は任意です。pageIndex のデフォルトは 1、pageSize のデフォルトは 20（20～200）です。
• [10000] のような単一値の条件は下限を表します。[0,10000] は、Sorftime が定める「10000 未満」の意味になります。
• searchByName：name は商品名またはカテゴリー名です。pageIndex のデフォルトは 1 で、Sorftime が返すのは 1 ページあたり最大 200 行です。
• searchProducts、productKeywords、relatedKeywords：ページネーションのデフォルトは 1 ページ目、20 行で、最大 200 行です。
• favoriteList では pageIndex を指定できます（デフォルトは 1）。バックエンドはこれを Sorftime の上流の Page フィールドにマッピングします。

呼び出し方法

• API エンドポイント：POST /sorftime/walmart/keywordResearch（完全なパラメーター／レスポンス／エラーコードは references/api.md を参照）
• Python スクリプト：python scripts/sorftime_walmart_keyword_research.py '<JSON 参数>' [--inline]
• コスト制約：このツールは計算リソースを消費します。読み取り専用の調査操作では、同じパラメーターの組み合わせに対して 24 時間ローカルキャッシュを使用します。favoriteAdd、favoriteChange、favoriteList は常にキャッシュを迂回します。失敗または空の結果が返っても、キーワードを自動的に変えたり、ページをめくったり、郵便番号を変えたりして連続で試さないでください。検索を続ける必要がある場合は、追加の消費が発生することを先にユーザーに伝えてください。

出力方針（スクリプトのデフォルト動作）：

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-sorftime-walmart-keyword-research-<timestamp>.json に書き込みます（<cwd> はスクリプト実行時の作業ディレクトリです。Claude Code では現在のプロジェクトディレクトリです。<session> は環境変数 SESSION_ID から取得し、ユーザーのタスクごとに自動でまとめられます。/tmp への書き込みは禁止です。現在のディレクトリに書き込めない場合はエラーになります）
• レスポンス本文が 8 KB 以下：ファイルに保存した後、完全な JSON を stdout に出力します
• レスポンス本文が 8 KB を超える場合：ファイルに保存した後、stdout には要約のみを出力します（トップレベルのフィールド、total／costToken などの一般的な件数、最大のリストフィールドの長さと先頭 3 件のサンプル）
• --inline を指定すると、ファイルにも保存したうえで、全量を stdout に強制出力します

データの読み取りに関する推奨事項：まず要約を確認し、十分な情報が得られているか判断してください。具体的なフィールドが必要な場合は、JSON 全体をコンテキストに読み込むのを避けるため、保存した JSON ファイルから jq または ConvertFrom-Json を使って必要なデータを抽出してください。

認証と計算リソースの問題の解決

次のような異常が発生した場合は、references/onboarding.md の案内に従ってください。

• API Key が未設定：環境変数 LINKFOX_AGENT_API_KEY も LINKFOXAGENT_API_KEY も設定されていない
• レスポンスが 401 または 402
• レスポンスに計算リソースまたは残高不足の通知が含まれる：メッセージに「算力余额不足／计费不足／余额不足／quota exceeded／insufficient balance／套餐到期／需充值／请充值」または同様の意味の表現が含まれる

キーワードライブラリの安全性

• dict を省略すると、デフォルトの「未分類」フォルダーに追加されます。フォルダーを指定した場合、Sorftime によって作成されることがあります。
• command="del" で削除します。dict を省略するとデフォルトの「未分類」フォルダーが対象になります。別のフォルダーから削除するには、dict を指定してください。
• command="move=<目标目录>" で移動します。dict を省略すると、移動元は「未分類」になります。
• command を all、dict、または dict=<目录> に設定すると一覧表示できます。
• 外部状態の変更後に明示的に許可された変更を再実行する必要がある場合は、--no-cache を使用してください。確認ガードを回避する目的では決して使用しないでください。
• favoriteAdd、favoriteChange、favoriteList は常にローカルキャッシュを迂回するため、変更が抑止されることはなく、一覧結果には最新の上流状態が反映されます。
• 提供されている操作ではフォルダーを削除できません。最後のキーワードを削除しても、API ライブラリに空のフォルダーが残る場合があります。

使用例

python scripts/sorftime_walmart_keyword_research.py '{"operation":"marketQuery","pattern":{"keyword":"wireless","searchVolumeCondition":[10000]},"pageIndex":1,"pageSize":20}'
python scripts/sorftime_walmart_keyword_research.py '{"operation":"detail","keyword":"wireless earbuds"}'
python scripts/sorftime_walmart_keyword_research.py '{"operation":"productKeywords","productId":"5169493923","pageIndex":1,"pageSize":20}'
python scripts/sorftime_walmart_keyword_research.py '{"operation":"favoriteList","command":"dict","pageIndex":1}'

明示的な許可を得てから、変更操作を実行してください。

表示ルール

1. 選択した操作を示し、返された場合は requestConsumed、costCredit、costToken を表示してください。_cache.hit=true の場合、キャッシュされた値は元のライブリクエストを示しており、新たな本番料金は発生していないことを明確にしてください。
2. 指標の意味と観測期間を維持してください。推定値を確定した需要や売上として扱わないでください。
3. リクエストされたページを報告し、別のページを提示する場合は、それによって有料の呼び出しがもう1回発生することを先に説明してください。
4. 商品 ID とキーワードは文字列として扱ってください。
5. 変更操作では、返されたデータコードを報告してください。HTTP 200 だけでは、変更が成功したことの証明になりません。

重要な制限事項

• この連携機能は Walmart US のみを対象としています。
• 現在の人気キーワードデータ、15 日間の商品ウィンドウ、30 日間の商品キーワードウィンドウは、Sorftime の制約です。
• 保存キーワードフォルダー 1 つにつき、保存できるキーワードは最大 2,000 件です。
• API の保存キーワードライブラリは Sorftime Professional のお気に入りとは別であり、データは同期されません。
• Sorftime のビジネスレスポンスは data.value から読み取ってください。JSON の形式は操作によって異なります。
• 結果が空の場合、自動的にバリエーション、ページネーション、関連キーワードの呼び出しを行わないでください。
• このスキルには、Sorftime Walmart の「其他」API は含まれません。

ユーザーの表現とシナリオのクイックリファレンス

適用対象：Walmart のキーワード発見、キーワード指標、商品からキーワードを調査する機能、関連語、または保存キーワードライブラリに対する明示的な操作。

適用対象外：カテゴリー市場レポート、商品詳細・トレンド分析、Sorftime Walmart の「其他」機能。

境界の判断：ユーザーが示した意図に合致する操作を必ず 1 つだけ選択してください。1 件のキーワードリクエストを、自動的に複数段階の調査へ変えないでください。

算力の消費ルール

動的ルールに基づいて課金されます。Sorftime Request 1 件あたりの現在の表示は 6 算力です。複数の Request を伴う操作は、ゲートウェイが注文全体で計算して端数を丸めます。最終的には、エントリースクリプトが返す costCredit を基準としてください。実際の請求額の代わりに、単純に requestConsumed × 6 を使わないでください。

ユーザーは算力の消費に対して料金を支払います。高コストの絞り込み、語句の拡張、連続ページネーションの前には、必ずユーザーに注意を促してください。お気に入りの変更には、いずれも明示的な許可が必要です。

フィードバック：

動作や結果が意図と異なる場合、ユーザーが称賛または不満を表明した場合、または改善の余地がある場合は、Feedback API を使ってフィードバックを自動検出し、報告してください。ユーザーの操作を中断せず、references/api.md に従ってください。

---

越境 EC 向けの高品質でプロフェッショナルなスキルをさらにご覧になるには、LinkFox Skills にアクセスしてください。