linkfox-amazon-reviews-list

Amazon Product Reviews

Amazon 商品レビューを取得・分析し、販売者が顧客のフィードバックから実用的なインサイトを引き出せるよう支援します。

基本概念

このツールは、指定した Amazon ASIN の実際の顧客レビューを 15 のマーケットプレイスから取得します。星評価ごと（1～5 つ星、各最大 100 件）の取得件数を指定したり、新しさまたは役立ち度で並べ替えたり、さまざまなフィルターを適用したりできます。1 回のリクエストで指定できる ASIN は 1 つだけです。複数の ASIN を指定する場合は、個別に呼び出してください。

呼び出し方法

• 非同期送信エンドポイント：POST /amazon/reviews/async/submit
• ポーリング照会エンドポイント：POST /amazon/reviews/async/result
• すべてのパラメーター、レスポンス、エラーコード：references/api.md を参照してください。
• Python スクリプト：python scripts/amazon_reviews.py '<JSON 参数>' [--inline]；実行ごとに送信または照会を 1 回だけ行い、すぐに返します。
• コスト上の制約：このツールは計算リソースを消費します。同一セッション内では、同じパラメーターの組み合わせでの呼び出しはデフォルトで 1 回のみです。スクリプトには 24 時間有効なローカルキャッシュがあります。失敗や空の結果を理由に、キーワードの変更、ページ送り、郵便番号の変更を自動で行って繰り返し試行してはいけません。検索を続ける必要がある場合は、追加の消費が発生することを先にユーザーへ伝えてください。

非同期呼び出しの流れ

1. 初回のスクリプト実行では /amazon/reviews/async/submit のみを呼び出し、taskId を保存してすぐに返します。同じスクリプト呼び出し内で結果を待ってはいけません。タスクがまだ実行中であることや、照会に 1 回失敗したことを理由に再送信しないでください。
2. 送信パラメーターは元のレビュー取得パラメーターと同じです。provider は渡さないでください。バックエンドは domainCode に基づいて Pango または Apify を自動選択します。実際のプロバイダーはレスポンスの provider で確認できます。
3. エージェントはユーザーのリクエストに含まれる、ほかの独立した作業を続けてもかまいません。結果が必要になったら、元のパラメーターでスクリプトを再実行するか、{"taskId":"..."} を渡してください。実行ごとに /amazon/reviews/async/result を 1 回だけ呼び出してすぐに返し、スクリプト内でループしたりスリープしたりしないでください。
4. 現時点の実測では、Pango は通常約 10~30 秒、Apify は通常約 15~60 秒で結果を返しますが、これは SLA ではありません。スクリプトは estimatedReadyInSeconds と suggestedNextCheckAfterSeconds を返します。ほかの作業を優先し、推奨時刻になってから照会してください。インターフェイスの最小ポーリング間隔に合わせて頻繁に照会しないでください。
5. タスクの作成時刻から最大 200 秒間、状況を確認します。この時間内に PENDING または RUNNING の場合は、元の taskId を保持してほかの作業を続け、約 10~20 秒後に再度照会してください。SUCCEEDED の場合は result を読み取ります。FAILED の場合は、ユーザーに error を伝えて停止します。CANCELLED の場合は、現在レビューサービスへのリクエストが多い可能性があり、実行リソースの待機中にタスクが自動キャンセルされ、料金は発生していないことを丁寧に説明し、しばらくしてから再送信するよう案内してください。
6. 200 秒を超えても PENDING または RUNNING の場合は、POLL_TIMEOUT を返して自動照会を停止し、ユーザーに同じ taskId で照会を続けるか、照会を停止して今回の結果を放棄するか選んでもらいます。新しいタスクを自動送信してはいけません。現在、手動キャンセル用のエンドポイントはありません。バックエンドは、実行リソース待ちがタイムアウトし、プロバイダーの呼び出しがまだ行われていない PENDING タスクのみを自動キャンセルします。RUNNING に移行したタスクは完了して料金が発生する可能性があります。
7. 未読み取りのタスクは、送信から最大 4 時間保持されます。SUCCEEDED、FAILED、CANCELLED のいずれかの終端状態を初めて読み取ると、バックエンドはタスクをただちに削除します。スクリプトは成功した結果をローカルファイルに保存し、タスクキャッシュには「受領済み」の状態とファイルパスのみを保持します。同じ作業ディレクトリ内では、元のパラメーターと taskId が同じタスク記録を共有します。24 時間のローカルキャッシュ有効期間内に再実行すると、ALREADY_RECEIVED、resultFile、今回の costToken: 0 が返されます。該当ファイルを読み取り、バックエンドへの再照会や再送信は行わないでください。ファイルが存在しない場合も、自動で再取得してはいけません。
8. 照会結果が「タスクが存在しない、または期限切れ」の場合は停止し、新しい有料タスクを自動作成してはいけません。ユーザーが明確に再試行を求めた場合に限り、再送信できます。
9. タスク料金は、上流の処理終了後にバックエンドが独立して精算します。送信および照会レスポンスの X-Cost-Token／costToken が 0 なのは、そのインターフェイス呼び出し自体に追加料金がかからないことを示すだけであり、タスク全体が無料という意味ではありません。実際の消費量は利用記録を確認してください。エージェントが予測式に基づいて推計したり、利用記録に追加したりしてはいけません。

スクリプトは上記の非同期フローのみを実行し、未完了の taskId をローカルにキャッシュして、後から照会できるようにします。

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

• 必ず完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-reviews-list-<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／套餐到期／需充值／请充值」が含まれる場合、または同様の意味の内容がある場合。

パラメーターガイド

パラメーター	型	必須	適用範囲	説明	デフォルト
taskId	string	はい	非同期結果	非同期送信で返されるタスク ID	-
asin	string	はい	非同期送信	Amazon 商品の ASIN	-
star1Num	integer	いいえ	非同期送信	取得する 1 つ星のレビュー数（0～100）	10
star2Num	integer	いいえ	非同期送信	取得する 2 つ星のレビュー数（0～100）	10
star3Num	integer	いいえ	非同期送信	取得する 3 つ星のレビュー数（0～100）	10
star4Num	integer	いいえ	非同期送信	取得する 4 つ星のレビュー数（0～100）	10
star5Num	integer	いいえ	非同期送信	取得する 5 つ星のレビュー数（0～100）	10
sortBy	string	いいえ	すべて	recent（新しい順）または helpful（役に立った順）	recent
formatType	string	いいえ	すべて	all_formats または current_format	all_formats
domainCode	string	いいえ	非同期送信	マーケットプレイスコード（対応マーケットプレイスを参照）。米国には com を使用	com
filterByKeyword	string	いいえ	非同期送信	キーワードでレビューを絞り込み（最大 1000 文字）	-
reviewerType	string	いいえ	非同期送信	all_reviews または avp_only_reviews（認証済み購入者のみ）	all_reviews
mediaType	string	いいえ	非同期送信	all_contents または media_reviews_only	all_contents

星評価ごとの件数のデフォルト

• 星評価の件数フィールドが指定されていない場合、star1Num から star5Num まではすべてデフォルトで 10 になります。
• 星評価の件数フィールドが 1 つでも指定されている場合、指定されていない件数はデフォルトで 0 になります。

対応マーケットプレイス

マーケットプレイス	コード
米国	com
カナダ	ca
英国	co.uk
ドイツ	de
フランス	fr
イタリア	it
スペイン	es
日本	co.jp
インド	in
オーストラリア	com.au
ブラジル	com.br
メキシコ	com.mx
オランダ	nl
スウェーデン	se
アラブ首長国連邦	ae

対応するすべてのマーケットプレイスで domainCode を使用してください。ユーザーが意図するマーケットプレイスを必ず確認してください。

使用例

1. 米国のレビューを取得（Amazon.com）

{"asin": "B08N5WRWNW", "domainCode": "com", "star1Num": 10, "star2Num": 10, "star3Num": 10, "star4Num": 10, "star5Num": 10, "sortBy": "recent"}

2. キーワードで絞り込んだ低評価レビューを取得（ドイツ）

{"asin": "B08N5WRWNW", "domainCode": "de", "star1Num": 30, "star2Num": 30, "filterByKeyword": "quality", "reviewerType": "avp_only_reviews"}

3. メディア付きの 5 つ星レビューを取得（日本）

{"asin": "B08N5WRWNW", "domainCode": "co.jp", "star5Num": 50, "star1Num": 0, "star2Num": 0, "star3Num": 0, "star4Num": 0, "sortBy": "helpful", "mediaType": "media_reviews_only"}

4. 3 つ星レビューのみを取得（星評価を明示的に指定）

{"asin": "B0FP5C63HZ", "domainCode": "com", "star3Num": 100}

表示ルール

1. データを明確に提示する：評価、タイトル、本文、日付、認証済みステータス、役に立った件数などの主要項目を含め、レビューを星評価ごとにまとめて表示します。
2. 適宜要約する：レビューが多数ある場合は、個々のレビューを列挙する前に、テーマや問題点を要約します。
3. 実行可能なインサイトを強調する：低評価レビューで繰り返し見られる不満点を取り上げ、高評価レビューでは評価されている機能を示します。
4. Vine および認証済みのラベルを表示する：Vine Voice と認証済み購入のステータスを明確に示します。
5. メディアの有無を示す：レビューに画像や動画が含まれる場合は、その旨を示します。
6. レスポンスを正規化する：生のレスポンスでマーケットプレイス固有のテキスト形式が使われている場合は、評価と役に立った件数のフィールドを正規化し、一貫した形式で表示します。
7. レビューの投稿元：各レビューの reviewCountry を使って、そのレビューがどこで投稿されたかを説明します。domainCode が示すのはクエリ対象のマーケットプレイスであり、すべてのレビューの投稿元ではありません。国名はローカライズされている場合があります（Canada と Canadá はどちらもカナダを指します）。分析では同じ国として扱ってください。reviewCountry がない場合は、domainCode や locale.country から推測せず、投稿元不明と示します。
8. エラー処理：クエリが失敗した場合は、レスポンスメッセージに基づいて理由を説明し、パラメーターの調整を提案します。
9. ASIN の単一指定制限：ユーザーが複数の ASIN について尋ねた場合は、それぞれに対して個別にリクエストを行います。

重要な制限事項

• リクエストごとに ASIN は 1 つ：一度に照会できる ASIN は 1 つのみです。
• 星評価ごとの上限：各星評価につき、1 リクエストあたり最大 100 件のレビューが返されます。
• パラメーターの適用範囲：filterByKeyword、reviewerType、mediaType は、domainCode: "com" を含む非同期送信で利用できます。
• 過去のスナップショットはありません：レビューはリアルタイムで取得されます。
• レビュー本文の言語：レビューは投稿時の原文で返されます。

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

適用可能 — Amazon の商品レビューに関するタスク：

ユーザーの発言	シナリオ
「この ASIN のレビューを見せて」	レビューの直接検索
「B08N5WRWNW の米国レビューを取得して」	マーケットプレイスを指定した検索
「顧客が不満に思っている点は？」	低評価レビューの分析
「星 1 つのレビューをすべて取得して」	星評価で絞り込んだ取得
「低評価レビューによくある問題は？」	ペインポイントの抽出
「この商品について、どんな点が好評ですか？」	高評価レビューの分析
「『battery』に言及したレビューを探して」	キーワードで絞り込んだレビュー
「写真付きのレビューを見せて」	メディアで絞り込んだレビュー
「認証済み購入者のレビューのみ」	レビュアーの種類による絞り込み
「競合他社のレビュー分析を手伝って」	競合レビューの調査
「レビューから商品改善の提案を出して」	実行可能なインサイトの抽出

適用不可 — 商品レビュー以外のデータが必要なもの：

• ABA の検索語データ／キーワード調査（代わりに ABA Data Explorer を使用してください）
• 売上推定または収益分析
• 商品リスティングのコピーライティングまたは A+ コンテンツの作成
• 広告／PPC 戦略
• 価格戦略または利益率の計算

適用範囲の判断：「商品調査」や「競合分析」が特定の ASIN の顧客レビューを読むことに集約される場合、このスキルが適用されます。検索ボリューム、キーワードランキング、売上推定、市場規模の算出を含む場合は適用されません。

計算リソースの消費ルール

取得予定のページ数に応じて動的に課金されます。P = Σ min(ceil(各星評価のリクエストレビュー数 / 10), 10) とすると、次のとおりです。

• 課金トークン：21000 × P。
• 実際の計算リソース消費量 = ceil((21000 × P) / 2000) = ceil(10.5 × P)。各リクエストごとに個別に切り上げます。
• 星評価の件数が指定されていない場合、デフォルトでは星 1〜5 の各評価で 10 件ずつ取得し、P = 5、消費量は 53 計算リソースです。
• いずれかの星評価の件数を指定した場合、指定されていない星評価は 0 になります。5 つすべての星評価に明示的に 0 を指定すると、P = 0 となり、プロバイダーは呼び出されず、計算リソースの消費量も 0 です。
• リクエストが成功しても結果が空の場合、またはキーワード、認証済み購入者、メディアのフィルター適用後に空になった場合も、予定ページ数に基づいて課金されます。一部のサブタスクが失敗しても全体が成功した場合は、予定ページ数の全体に基づいて課金されます。上流の呼び出しが完全に失敗した場合は課金されません。

一般的な消費量：1 ページ 11 計算リソース、2 ページ 21 計算リソース、5 ページ 53 計算リソース、10 ページ 105 計算リソース。

重要：料金はリクエストした取得ページ数に基づいて計算され、最終的に返されるレビュー数には基づきません。複数の星評価または大量のレビューをリクエストする前に、予定ページ数と計算リソースの消費量をユーザーに説明する必要があります。

上記の計算式は呼び出し前の見積もりにのみ使用します。実際の課金の有無と金額は、消費記録に基づいて確認してください。料金はバックエンドで独立して精算され、結果を取得しても二重に課金されません。結果を取得していない場合、照会に失敗した場合、またはローカルでの監視がタイムアウトした場合でも、タスクが無料であることを意味しません。これを根拠に消費量をゼロと報告したり、見積もり値を実際の消費量として計上したりしてはいけません。

フィードバック：

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

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

リファレンスに記載された方法に従って Feedback API を呼び出してください。ユーザーの作業を中断しないでください。

---

高品質でプロフェッショナルな越境 EC スキルについては、LinkFox Skills をご覧ください。