linkfox-mpstats-ozon-product-search

MPSTATS Ozon 商品検索

このスキルは、ロシア語のキーワードまたは SKU リストを使って、MPSTATS 分析データベース内の Ozon（ロシア）商品を検索します。Ozon 商品の発見と競合調査の入口であり、後続の詳細調査（ブランド／カテゴリー／販売者／詳細／トレンド）は通常、ここで返される ID を起点に行います。

主な概念

MPSTATS の Ozon 対応範囲：Ozon はロシア最大の総合カテゴリー型マーケットプレイスです。MPSTATS は Ozon の商品リスティングと販売履歴をインデックス化しています。このエンドポイントが返すのは、基本情報カードのみです。フィールドは 10 個で、productId／title／productPageUrl／imageUrl／brand／brandId／sellerName／sellerIdに加え、sourceType／sourceToolです。SKU ごとの価格／販売数／評価／在庫／売上高／ランキングはここでは返されません。バックエンドの OzonProductSearchItem DTO は意図的に限定されています。これらの指標を取得するには、mpstats-ozon-product-detail（一括で完全なカード、36 フィールド）または brand/category/seller-products の詳細調査（39 フィールド）を続けて実行してください。

言語要件：キーワードはロシア語（キリル文字）、または Ozon のストアフロントで実際に使われているラテン文字表記で入力する必要があります。ユーザーが英語または中国語のキーワードを指定した場合は、まずロシア語に翻訳し、その翻訳を明記してください。

最低 1 つの入力が必要：入力スキーマでは両方のフィルターが任意とされていますが、ツールの業務ルールでは keyword／productIds の少なくとも一方を指定する必要があります。両方を組み合わせて結果を絞り込むこともできます。ブランドまたは販売者を対象とした検索には、代わりに mpstats-ozon-brand-products／mpstats-ozon-seller-products を使用してください。

パラメーター

パラメーター	型	必須	説明
keyword	string	条件付き	ロシア語の検索キーワード。例：кроссовки（スニーカー）
productIds	array<integer|string>	条件付き	Ozon SKU リスト
startDate	string	いいえ	統計期間の開始日。YYYY-MM-DD。デフォルトは 1 年前
endDate	string	いいえ	統計期間の終了日。YYYY-MM-DD。デフォルトは昨日。今日または未来の日付は指定できません

keyword／productIds の少なくとも一方を指定する必要があります。エンドポイントが 1 回の呼び出しで返すレコードは最大約 36 件です（上流側で確認されている上限）。ページネーション／並べ替え／フィルターの入力はありません。代わりにキーワード／SKU と日付範囲で絞り込んでください。

呼び出し方法

• API エンドポイント：POST /mpstats/ozon/productSearch（全パラメーター／レスポンス／エラーコードは references/api.md を参照）
• Python スクリプト：python scripts/mpstats_ozon_product_search.py '<JSON 参数>' [--inline]
• コスト上の制約：このツールは計算リソースを消費します。同一セッションで同じパラメーターの組み合わせを使う場合、デフォルトでは 1 回のみ呼び出します。スクリプトには 24 時間のローカルキャッシュがあります。失敗または結果が空の場合に、キーワードを自動で変更したり、ページをめくったり、郵便番号を変更したりして連続して試すことは禁止されています。検索を続ける必要がある場合は、追加のコストが発生することを先にユーザーに伝えてください。

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

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

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

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

次の異常が発生した場合は、references/onboarding.md の案内に従って問題を解決してください。

異常な状況

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

使用例

1. キーワード検索 — ロシア語でスニーカーを検索

{"keyword": "кроссовки"}

2. SKU リストによる一括逆引き

{"productIds": [1786874757, 151623766, 142257239]}

3. 期間を指定した検索

{"keyword": "футболка", "startDate": "2025-02-01", "endDate": "2025-02-28"}

他の Ozon スキルとの連携方法

1. キーワード検索 → 詳細調査：検索 → productId を選択 → mpstats-ozon-product-detail（一括指標）または mpstats-ozon-product-trend（単一 SKU の時系列データ）を呼び出します。
2. ブランドの詳細調査：ブランドを対象に、全指標付きの商品リスティングを取得するには、ブランドの表示名を指定して mpstats-ozon-brand-products を直接呼び出します。
3. 販売者の詳細調査：販売者を対象に、全指標付きの商品リスティングを取得するには、販売者 ID を指定して mpstats-ozon-seller-products を直接呼び出します。

表示ルール

1. 識別情報の列を先頭にする — このエンドポイントが返すのは識別情報のフィールド10個のみです。表の先頭には productId、title、brand、sellerName を配置し、productPageUrl ／ imageUrl は補助列として含めてください。価格／売上／評価／在庫の列は追加しないでください。レスポンスには含まれていません。
2. ロシア語のタイトル — 元のロシア語タイトルをそのまま保持してください。ユーザーから求められた場合は、英語または中国語の翻訳を提示してもかまいません。
3. 結果件数 — このエンドポイントが返すレコードは最大約36件で、ページネーションには対応していません。total が返された件数を上回る場合は、ページの追加取得ではなく、キーワード／SKUの対象を絞るか、日付範囲を狭めるよう提案してください。
4. 業務指標の照会は必ず詳細取得に誘導する — このレスポンスに業務指標は含まれません。ユーザーが売上／価格／評価／在庫／回転率／ランキングを尋ねた場合は、必ず mpstats-ozon-product-detail（単件または一括）か、*-products の詳細取得機能に誘導してください。識別情報のフィールドから数値を捏造したり推定したりしないでください。
5. エラー処理 — code ／ errcode が200以外の場合は、msg ／ errmsg に基づいて理由を説明し、入力の調整を提案してください（keyword ／ productIds の少なくとも一方を指定する、ロシア語を使用する、日付範囲を狭める）。

重要な制限事項

• keyword ／ productIds の少なくとも一方が必須 — inputSchema では required が空ですが、このツールの業務ルールにより、空のペイロードは拒否されます。
• ロシア語／ラテン文字のみ — ロシア語以外のキーワードでは、通常、結果が空になります。
• 日付範囲 — endDate に今日または未来の日付は指定できません。データはT-1です。
• 厳格な結果件数上限 — 上流は1回の呼び出しにつき最大約36件を返し、ページネーション／並べ替え／フィルターには対応していません。この制限は回避できないため、クエリの対象を絞ってください。
• 業務指標なし — 価格／売上／評価／在庫／回転率／ランキングは、このエンドポイントのレスポンスに一切含まれません。バックエンドの OzonProductSearchItem DTO で宣言されているのは、識別情報のフィールド10個のみです。これは厳密な契約であり、単にデータが少ないということではありません。日付を変えて再度呼び出せば、欠けている指標フィールドを取得できるとは考えないでください。

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

対象 — Ozonの商品検索／識別情報の解決：

ユーザーの発言	シナリオ
「Ozonでスニーカー／ヘッドホンなどを検索して」	キーワード検索
「OzonのSKUリストがあるので、商品名を取得して」	SKUの一括逆引き
「このキーワードをロシア語に翻訳してOzonで検索して」	言語をまたいだ商品検索

対象外 — 商品検索を超える情報が必要な場合：

• SKUごとの正確な売上／収益／在庫／評価指標 → mpstats-ozon-product-detail（カードの一括取得）または *-products の詳細取得スキルを使用してください。
• ブランドを指定した商品一覧 → mpstats-ozon-brand-products を直接使用してください。
• 販売者を指定した商品一覧 → mpstats-ozon-seller-products を直接使用してください。
• 単一SKUの時系列トレンド → mpstats-ozon-product-trend を使用してください。
• WildberriesまたはロシアのOzon以外のマーケットプレイス → ここでは対象外です。
• カテゴリーツリーのナビゲーション／ロシア語のカテゴリー階層の検索 → 既知のパスを指定して mpstats-ozon-category-products を使用してください。

適用範囲の判断：ユーザーがOzonの商品を検索または特定したい場合は、まずここを使用してください。すでにIDや属性（ブランド／カテゴリー／販売者）が分かっていて、それに紐づく指標を知りたい場合は、対応する詳細取得スキルを直接使用してください。

計算リソース消費ルール

動的ルールに基づいて課金されます：計算リソース消費量 = 12。一覧が空の場合は0です。

重要：このスキルのサービスは倍率に応じて動的に計算されるため、一度に多くの計算リソースを消費する場合があります。必ずユーザーに伝え、続行するかどうかはユーザーに判断してもらってください。

フィードバック：

以下のいずれかに該当する場合は、フィードバックAPIを通じてフィードバックを自動検出し、報告してください。

1. このスキルで説明されている機能または目的が、実際の動作と一致しない
2. スキルの結果がユーザーの意図に合わない
3. ユーザーがこのスキルに対する不満または称賛を表明する
4. 改善できると思われる点がある

references/api.md の指定に従ってフィードバックAPIを呼び出してください。ユーザーの作業を中断しないでください。

---

高品質でプロフェッショナルな越境ECスキルをもっと利用するには、LinkFox Skills を設定してください。