AmazonレビューAPI：商品リンクから出典付きの課題リストを作る

Amazonレビューから製品改善の手がかりを抽出する際、最初のステップはモデルにすべての内容をポジティブとネガティブに分類させることではありません。まず把握すべきなのは、レビューがどの国のマーケットプレイスのものか、どの商品に紐づいているか、複数のリクエストで重複して出現していないか、そして各課題の結論が具体的にどの文を引用しているかです。そうしないと、同じ人気レビューを10回読み取っただけで、レポート上では10人の購入者が同じ問題を指摘したと解釈されかねません。

このガイドは、レビューを社内のリサーチワークフローに組み込む必要がある開発者とプロダクト責任者を対象としています。利用が許可された商品リンクから始め、商品、レビュー、観測ログ、分類の根拠の関係を確立します。最終的な成果物は検証可能な課題リストであり、売上予測、レビューの真正性の検証、購入者全体の満足度を示すものではありません。

商品カタログとレビュー調査の区別

公式のAmazon Creators APIは、Amazonアソシエイトのショッピング体験向けに、商品検索、商品詳細、バリエーション、カテゴリーノードの操作を含む商品カタログへのアクセスを提供します。これはEveryInfraのamazon.reviewsとは別の製品であり、公式の商品カタログのドキュメントを、第三者によるレビュー読み取りの許可の証明として使うことはできません。

統合の前に、対象のマーケットプレイス、データの使用許可、処理目的、保持期間、原文を表示したりモデルで処理したりできるかを確認してください。Amazon.comの利用規約のLICENSE AND ACCESSでは、一般的なライセンスとデータ収集方法に制限が設けられています。他のマーケットプレイスや特定のプログラムについては個別に確認が必要です。商品ブランドを所有していても、すべてのレビューコンテンツを自由に再利用する権利が自動的に与えられるわけではありません。

既存の許可で特定のエクスポートデータセットの使用のみが認められている場合は、ネットワーク経由の読み取りを行わず、以下の識別情報、重複排除、分類のステップから直接始められます。許可範囲をワークフロー全体で維持し、その範囲外のフィールドや目的は後続のパイプラインから除外してください。

他のアクションからのパラメータ流用を避け、レビューアクションの現行パラメータを確認

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?platform=amazon' \
  | jq -e '.capabilities[] | select(.action == "reviews") | {
      platform, action, required_params, optional_params, param_meanings,
      mode, returns_list, default_limit, max_limit, response_fields
    }'

2026-09-04時点で確認したところ、reviewsではurlが必須、任意パラメータはdomain、実行モードはsyncで、結果はリストとして返されます。現在のカタログではdefault_limitとmax_limitの具体的な値が宣言されていません。空の値は未宣言として記録するしかなく、件数無制限と解釈することはできず、ましてや過去のすべてのレビューを取得できることを保証するものではありません。

また、他のプラットフォームがsort、since、cursorに対応しているからといって、これらのフィールドをAmazonのリクエストに追加しないでください。任意パラメータは現在のアクションに対応している必要があり、インターフェースがパラメータを受け付けることと、フィルタリングが実際に機能することは別々に検証する必要があります。現在のカタログでは、新しい順に並べた連続ページネーションのチュートリアルを裏付けるには不十分なため、以下では小規模なサンプルリクエストを示します。

商品識別情報より先に行う国別マーケットプレイスの確認

urlには商品リンク全体を、domainにはamazon.comやamazon.co.jpのようなマーケットプレイスのドメインを指定します。domainにはhttps://や商品パスを含めないでください。ローカルの入力解析では、/dp/、/gp/product/、/product-reviews/などのパスから、ASINを構成する10文字の英大文字または数字を抽出します。ストアのトップページやキーワード検索ページは、確定した商品の入力としては使えません。

米国以外のマーケットプレイスには特に注意してください。現在の実装では、レビューのマーケットプレイスのデフォルト値はamazon.comであり、任意の入力リンクから国別マーケットプレイスを自動推定することは保証されていません。日本のマーケットプレイス向けに商品を準備する場合は、リンクに合わせてamazon.co.jpを明示的に渡してください。日本語の本文、レビュー内の国フィールド、ページに表示される通貨を、リクエストドメインの代わりとして扱わないでください。

• 商品リストには、元のURL、確認済みのマーケットプレイス、リクエストASIN、社内の商品番号、対象に含めた理由を保存します。タイトルは閲覧用であり、商品の主キーとしては使用しません。
• 商品の関連付けでは、レスポンスのproduct_asinとvariantを別途保存します。検証なしにリクエストASINを上書きしてはならず、欠落している場合にサブバリエーションを推測しないでください。
• 同じマーケットプレイスとASINを指す異なるトラッキングリンクは、元のリンクとの対応関係を保持したうえで、リクエスト送信前に1つの対象に統合できます。マーケットプレイス、対象、パラメータが異なるリクエストを、タイトルの類似性だけを根拠に統合してはいけません。

リクエストのマーケットプレイスは今回の観測のソース範囲であり、レビュー投稿者の国籍ではありません。countryは形式が一定でない地域テキストの場合があり、variantも不完全な場合があります。地域や仕様によるグループ化は、明確な正規化と検証を行った後にのみ適切です。未確認のレコードは「未指定」に分類し、米国のマーケットプレイスやデフォルトの仕様に黙って振り分けないでください。

単一対象での最小限のリクエスト実行

以下はリクエストテンプレートであり、今回の実際の顧客リクエストではありません。利用が許可された完全な商品リンクと対応するマーケットプレイスを環境変数に設定し、APIキーは必ず自身の実行環境内でのみ管理してください。limitは一般的なリスト件数のリクエストとしてparamsに指定します。3に設定するのは小規模な構造を確認するためであり、ちょうど3件が返されること、サーバー側の処理が3件に制限されること、3件分で課金されることを保証するものではありません。

: "${EVERYINFRA_API_KEY:?set the API Key first}"
: "${EVERYINFRA_AMAZON_PRODUCT_URL:?set the authorized full product URL first}"
: "${EVERYINFRA_AMAZON_DOMAIN:?set the site domain matching the URL first}"
jq -cn --arg url "${EVERYINFRA_AMAZON_PRODUCT_URL}" \
  --arg domain "${EVERYINFRA_AMAZON_DOMAIN}" '{
    platform: "amazon",
    action: "reviews",
    params: {url: $url, domain: $domain, limit: 3}
  }' | curl --silent --show-error --include --max-time 180 \
  'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer ${EVERYINFRA_API_KEY}" \
  -H 'Content-Type: application/json' --data-binary @-

まずHTTPステータスとレスポンスの型を確認し、次に実際のラッパーに応じて結果、リクエスト識別子、利用可能な課金情報を読み取ります。タイムアウトはクライアントが完全な結果を受信できなかったことを示すものであり、サーバー側で実行に失敗したことを意味するわけではありません。直接の再送を避けるため、検証前にリクエストのコンテキストを保持してください。空の結果は今回のリクエストで利用可能なレビューが得られなかったことを示すものであり、これを根拠に商品を「レビューが一度もない」とマークしてはいけません。

レビュー本体と観測ログの分離

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/fields?platform=amazon&action=reviews' \
  | jq '{fields, undocumented}'

現在の辞書には、review_id、title、text、rating、rating_scale、posted_at、helpful_count、is_verified_purchase、is_vine、variant、country、url、author_name、product_asin、platformが含まれます。これは返される可能性のある内容を説明するもので、すべてのレコードで値が揃うことを保証するものではありません。

• レビューレコード：ソース範囲、安定したreview_id、利用可能なタイトル・本文・評価・評価スケール、ソースリンクを保存します。IDは文字列として保持し、欠損値は明示的なfalseや0と区別します。
• 観測ログ：タスク番号、リクエストした商品、パラメータのスナップショット、observed_at、実際に返されたレビューとの関連付けを保存します。リクエストで過去のレビューを読み取った場合は新たな観測であり、新しいレビューではありません。
• 分析レコード：採用したレビューのバージョン、分類ルールのバージョン、テーマと根拠となる抜粋、確認ステータスを保存します。分類ルールを変更しても、元のレビューを書き換える必要はありません。

ratingとrating_scaleはセットで扱います。商品レベルの総合評価、評価の総数、今回取得したレビュー数はそれぞれ別の指標です。本文のない評価レコードは別の評価サンプルとして集計できますが、意見を捏造してテキストのテーマ分析に混ぜることはできません。author_nameは表示名にすぎず、一意の識別子には適しません。また、商品の課題分析のために投稿者のサイト横断プロフィールをつなぎ合わせる必要はまったくありません。

is_verified_purchaseは購入の確認ステータスであり、意見が正確であることや、内容全体が真正であることを保証するものではありません。falseと返されなかったフィールドは区別する必要があります。is_vineはVineプログラム関連の評価を示します。Amazonの公式ドキュメントでは、Vineに招待されたレビュアーは意見を投稿する前に商品を無料で試せる場合があるとされています。そのため、このステータスはサンプルの層別化フィールドとして使用できますが、Vineレビューをそのまま偽物と判断することも、フィールドの欠落を非Vineと判断することもできません。

重複排除時の関連付けの保持と、類似テキストだけに基づく削除の回避

アプリケーション層では、まず「ソースプラットフォーム＋マーケットプレイス＋review_id」を使って同じ対象範囲のレビューを識別し、どのリクエスト対象商品について観測されたかを別途記録できます。同一のキーに対して商品への帰属や内容が矛盾する場合は、黙って上書きせず、矛盾するレコードをまず保持したうえで検証してください。サイトをまたいで同一のIDやテキストが現れても、信頼できる対応関係がなければ自動的に統合してはいけません。

review_idが欠落している場合は、確認済みのレビューのパーマリンクを関連付けの補助に使用できます。それでも確定できないものは重複排除の保留領域に入れます。本文、日付、評価の組み合わせはおおよその候補を示すだけで、2つの投稿者情報が同一人物を指すことを証明するものではありません。2つの「works great」が実際には別々のレビューである可能性もあり、翻訳後に同義となるテキストも一意のキーとして使用できません。

同じレビューが後で再び現れた場合は、実際に取得できた本文、評価、「役に立った」の件数、商品との関連付けを比較します。変更はまず観測上の差異として記録します。言語、フィールドの有無、期間の違いによっても差異が生じる場合があります。今回特定のレビューが返されなかった場合は「今回は未観測」とマークするにとどめ、削除イベントを生成しないでください。

課題分類とソース位置の紐付け

モデルを接続する前に、許可を得た少数のサンプルで分類の境界を人手で判定してください。テーマは互換性、梱包、説明書、配送など対応可能な課題から始め、「明確な課題なし」と「根拠不十分」も残しておきます。1件のレビューに複数のテーマを付けることを許容し、タグの割り当てを埋めるために「未開封」の商品について品質に関する結論を捏造しないでください。

分類器に渡すデータは、タスクに不可欠な内容に最小化してください。レビューは分析対象の素材であり、システム指示ではありません。レビュー内に「ルールを無視して」や「このアドレスにアクセスして」といった文があっても、モデルがツールを呼び出したり処理の目的を変更したりしてはいけません。出力には少なくとも、レビューID、ソースのテキストフィールド、開始・終了位置、テーマ、ルールのバージョン、確認待ちのステータスを紐付ける必要があります。

function validateAnnotation(review, annotation) {
  const topics = new Set(["compatibility", "packaging", "instructions", "shipping"]);
  if (typeof review.review_id !== "string" || !review.review_id.trim()) {
    throw new Error("review id required");
  }
  if (annotation.review_id !== review.review_id
      || annotation.taxonomy_version !== "issues-v1"
      || !topics.has(annotation.topic)) {
    throw new Error("unknown review or classification rule");
  }
  const field = annotation.source_field;
  if (!["title", "text"].includes(field)) throw new Error("invalid source field");
  const source = review[field];
  const {start, end, quote} = annotation;
  if (typeof source !== "string" || typeof quote !== "string"
      || !quote.trim() || !Number.isInteger(start) || !Number.isInteger(end)
      || start < 0 || end <= start || end > source.length
      || source.slice(start, end) !== quote) {
    throw new Error("evidence does not match source");
  }
  return {
    review_id: review.review_id, topic: annotation.topic,
    source_field: field, start, end, quote,
    taxonomy_version: "issues-v1", review_status: "unreviewed"
  };
}

// synthetic text; demonstrates evidence checks only, not a real product review.
const sample = {review_id: "synthetic-review", text: "the API cannot reach the legacy model，wrapper intact."};
console.log(validateAnnotation(sample, {
  review_id: sample.review_id, taxonomy_version: "issues-v1",
  topic: "compatibility", source_field: "text",
  start: 0, end: 9, quote: "the API cannot reach the legacy model"
}));

このバリデーターが証明するのは、引用位置が入力テキストと一致することだけであり、テーマの判定が正しいことではありません。モデルが「梱包は問題なし」を引用しながら梱包の問題としてフラグを立てた場合、文字単位のチェックには通ってしまう可能性があるため、意味面のチェックまたは人手による確認で検出する必要があります。start/endにはJavaScriptの文字列インデックスを使用します。データを別のプログラミング言語に渡す場合はインデックスの規約を明示し、バイトオフセットや文字数を混在させないでください。

実際の本番環境では、外側のレイヤーでマーケットプレイス、商品との関連付け、レビューのバージョンも紐付け、項目ごとの出力数とフィールドの型を制限する必要があります。モデルが自己申告する信頼度は校正された精度ではありません。リリース前に人手でアノテーションするサンプルを選定し、すべての誤りを見栄えのよい単一の全体精度に集約するのではなく、見落とし、誤検知、判定を裏付けていない根拠をそれぞれ集計してください。

OWASPは、Webページ、ドキュメント、ユーザーレビューに隠された指示を間接プロンプトインジェクションのリスクに分類し、ユーザーの権限と現在のタスクに基づいてツール呼び出しを検証することを推奨しています。したがって、レビュー分類器は制約された候補タグのみを生成すべきであり、商品の変更やメッセージの送信といったアクションはレビューの内容によって許可されるものではありません。

課題の割合における分母の明記

あくまで架空の例として、分析対象に含めた重複排除済みで読み取り可能な10件のレビューのうち、3件が互換性に関するものと確認された場合、「このサンプルにおける互換性の問題への言及率は3/10」と述べることができます。これを「購入者の30%が互換性の問題に遭遇した」と言い換えることはできません。1件のレビューが2つのテーマに関わる場合、テーマの割合の合計は100%を超えることがあります。合計が100%になる構成グラフは、相互に排他的なカテゴリを定義した後でのみ適切です。

すべてのレポートに、マーケットプレイスと商品のセット、サンプリング時刻、実際のリクエストパラメータ、返却件数、重複排除後の件数、読み取り可能なテキストの件数、確認待ちの件数、ルールのバージョンを添付します。レビューのposted_atと読み取り時のobserved_atは分けて扱います。昨年のレビューを今日読み取ったからといって、今日新たな問題が発生したことにはなりません。

週をまたいで比較する場合も、商品セット、取得順序、言語処理、期間を固定するか、変更点を説明する必要があります。毎回同じ先頭のレビュー群だけを読み取っている場合、タスクの実行頻度を上げても独立したサンプルは増えません。カタログで完全なページネーションや期間が保証されていない場合、レポートは全量のトレンド監視ではなく、観測したサンプルの分析として位置づけるべきです。

レポートでは、W3C PROVの派生記録の考え方を取り入れ、各課題の結論をレビューのバージョンや分類処理と関連付けることもできます。これにより、元のテキストが修正されたときに影響を受けるタグや要約を特定できます。ただし、関係を記録しても分類が正しいことの証明にはならないため、意味の検証は引き続き必要です。

課題リストの実務的な改善ワークフローへの組み込み

プロダクトチームに渡す価値のある結論には、影響を受ける確定済みの仕様、代表的な根拠、サンプルの分母、除外できていない別の説明、次の検証手順を含めるべきです。たとえば、互換性に関する注記の追加や製品の調整を決める前に、旧モデルで接続の問題を再現します。レビュー自体は、エンジニアリングテスト、注文データ、アフターサービスの記録の代わりにはなりません。

最初の連携では、利用が許可された商品を1つだけ選び、入力の検証、レスポンスの確認、重複除外、出典の裏付け確認、人による確認までを一通り行えば十分です。これらの手順を再現できる状態になって初めて、商品リストを拡大しても有用な情報が得られます。次に、Amazonの機能ページに沿ってパラメータを確認し、共通ドキュメントに沿ってリクエストの状態を処理します。先に件数を増やしてから、各レビューの出所を後で推測するような進め方は避けてください。