亚马逊商品数据缺少关联与时效，选品和监控就会失去准确性

1. 亚马逊商品数据 API 是什么，能解决哪些问题？

商品目录、Listing 和 Offer 为什么不能混成一个对象？

亚马逊商品数据 API是一类通过程序获取商品相关信息的接口。调用方可以按 ASIN 查详情，也可以从关键词、类目、榜单或卖家页面发现商品。接口输出可能是结构化 JSON，也可能是页面 HTML 或 Markdown；输出形式不同，业务端需要承担的解析工作也不同。

“商品数据”不是一个天然边界清晰的对象。目录内容描述商品是什么，例如品牌、型号和规格；卖家 Listing 表达某个卖家的刊登及经营信息；Offer 描述某个卖家在给定条件下的报价；页面观测则记录某次访问看到的内容。相同 ASIN 下可以涉及不同卖家的报价，页面选中的购买选项也未必代表商品族的全部选项。

建模时至少区分商品实体与商品观测。前者负责身份和关联，后者保存当时的价格、配送、评价与证据。否则，“更新商品价格”可能覆盖掉另一个邮区或另一个卖家的历史，系统看似一直有最新值，却无法解释昨天发生了什么。一次响应可以贡献多个对象，但不应靠同一个主键覆盖所有对象。

读者需要的是当前页面、历史序列，还是授权账户数据？

这三种需求对应不同采购问题。当前页面数据关心本次读取的条件；历史序列关心过去是否已经采集、保存和标准化；授权账户数据关心账户角色和业务权限。今天开始调用实时接口，不能凭空得到过去一年的价格历史。某个页面写有可售提示，也不能据此访问卖家后台的订单或库存账本。

举一个假设任务：品牌团队想知道竞品是否连续降价。只取今天的价格，能回答“本次看到多少”，不能回答“是否连续下降”。至少还要有同口径历史观测，并排除规格、卖家、币种与优惠条件发生变化的情况。需求单上应写“可比较的价格序列”，而不是只列一个 price 字段。

如果目标是补全商品库，图片、标题和属性可能比分钟级价格更重要。如果目标是报价告警，身份与地区证据不能省。对 AI Agent 而言，还要让工具返回来源、时间和未知状态，让模型知道哪些结论不能下。接口选择因此始于业务任务，而不是从字段数量或调用单价开始。

什么样的交付物才算解决了商品数据需求？

建议把需求写成“对象、范围、动作、证据”四部分。例如：美国站某个竞品集合，在两个配送地区观察可比较报价，达到业务设置的变化条件后提醒运营，并能回溯原始响应。这样的描述可以推导商品发现、详情采集、地区核验、历史保存和告警审核，不会把责任留在一句“获取商品信息”里。

数据交付还应说明缺失如何表示、错误怎样处理、更新由谁触发。对目录补图而言，价格未知未必使记录失效；对地区比价而言，地区未确认就应阻止该记录进入比较。可用性是相对于用途的判断，没有一个能替所有业务作决定的全局“成功”标记。

2. 商品详情接口能返回哪些字段，哪些信息不能据此推断？

如何建立有业务含义的字段清单？

字段清单应该同时写明对象、原始形态、单位和业务用途。不要把“能返回 price”当成价格需求已解决，也不要把“有 images 数组”当成媒体可直接复用的许可。下面的分组用于设计验收，不表示每种数据源、每个市场和每件商品都必然提供这些字段。

一个字段是否必填，应由输出任务决定。例如果要计算同规格单位价，包装数量就是核心字段；若只是识别新出现的 ASIN，缺少包装数量未必需要拒收。把一套字段规则套到所有类目，会把服装尺码、电子设备容量和食品净含量混成无法比较的“size”。

文档里的类型和示例不一致时，应相信哪一个？

先保留差异，再验证目标响应。商品接口文档可能用概括类型描述某组字段，而示例展示的是嵌套数组；接口版本、解析器和页面结构也可能变化。集成代码不应仅凭表格里写着 object 或 string[] 就无条件展开，应结合当前示例、真实试用响应和支持说明确认契约。

以本次核验的 Pangolinfo 文档为例，商品详情示例位于外层 data.json 下，任务对象内再包含 data.results。它不是顶层直接出现 title 和 price 的扁平对象。文档还区分 coupon、savingsPercentage、promotions 和 discountTypes；这些字段分别表达不同优惠信息，不能仅因都与“折扣”有关就覆盖同一列。商品接口文档

标准化时建议保留原值和解析值两列。例如金额保存页面字符串、十进制数值与币种；规格保存原始标签、归一后的属性名、数值和单位。转换失败时保留原始证据与原因，不要写成零。这样既能让分析使用统一结构，也能在规则有误时回放修正。

单位价格需要先确认销售单位。假设 A 是两件装、售价 100，B 是相同规格的单件、售价 60，按件比较才会得到 50 与 60。若两件装中的单件容量不同，这个换算仍不成立。把包装数量、每件净含量和计量单位拆开保存，才能决定按件、按重量还是按容量比较；商品标题中出现的数字不能未经核验就当作数量。

如何处理空值、字段漂移和无法归因的缺失？

空字符串、null、缺键只说明响应形态，不能单独证明商品不适用、源页没有内容或采集失败。应区分“未请求”“文档未承诺”“返回为空”“解析失败”“有证据确认源页无此信息”。无法确认根因时保留未知，这比看似整齐的默认值更适合后续排查。

项目在 2026-09-14 留存的 A01.08 记录显示，同父商品的两个样本存在 48 与 49 条属性的差异，划线价标签分别为 List Price 与 Typical price。这些历史观察支持“按含义对齐、保留价格标签”的设计，却不能估计问题发生率。本次没有重新执行那组商品采集，也不把当时的取值当作当前页面状态。

如果需要字段级实现，可继续阅读亚马逊商品数据字段契约。使用其中历史样本时仍应遵循证据边界：不能只凭空值形态下根因结论。采购层要验收的是字段能否支撑任务，而不是要求供应商消除所有源页面差异。

3. 官方接口、自建采集和第三方 API 应怎样选？

SP-API 能提供哪些商品与报价信号？

SP-API 不是单一的商品详情接口，而是一组有角色、授权和操作边界的业务 API。Catalog Items 服务于目录检索与商品信息，Product Pricing 服务于报价相关业务；需要评价主题时，还有 Customer Feedback API。把这些能力混成一个“官方 API 支持/不支持”的勾选项，会掩盖实际接入差异。

Amazon 的 Catalog Items v2022-04-01 搜索参考列出 relationships、salesRanks、images、attributes 等数据集。Product Pricing 文档则列出最多 20 个 ASIN 的批量 Featured Offer 查询，以及最多 40 个 SKU 的 FOEP 请求。这足以纠正“官方没有变体、排名或竞争报价”的说法，但不意味着每个账户都可以无条件访问全部数据。目录搜索参考、报价接口说明

评估官方路线时，应把具体操作、所需角色、市场和业务用途写进表格。确认一个商品在目录中存在，不等于已经获得目标卖家在目标邮区的最终购买价格。即使接口提供地区样本，也要核对该字段定义，不能将它替换成任意消费者地址的结算结果。

Creators API 与公开页面采集面向的是同一种用途吗？

截至本次核验，Amazon 官方已将 PA-API 5 标为弃用，并指向 Creators API。Creators API 面向符合计划要求的联盟购物内容，提供 SearchItems、GetItems、GetVariations 和 GetBrowseNodes 等操作。新项目应查后继接口的接入与使用要求，不照搬旧 PA-API 教程。弃用说明、Creators API 介绍

路线选择要看数据用途。为联盟内容展示商品，与为内部研究长期保存跨地区观测，是不同的项目需求。即使某个接口在技术上返回了所需字段，也要确认缓存、展示、保存和再分发的条件。此处需要检查适用条款，不能把某项接入资格解释为所有用途的许可。

什么时候应采用自建、托管或混合方案？

自建的收益是控制权，代价是持续维护；托管的收益是把一部分采集工作交出去，代价是需要验证供应商边界。两者都不会替你确定什么叫同款、可比价格或有效评论。若业务定义尚未完成，换一种采集工具只会把模糊之处搬到另一条链路。

混合方案也不等于把几个字段拼成一条“更完整”的记录。目录来自官方接口，价格来自公开页面，评价来自另一服务时，各组字段应保留独立来源和时间。下游看到的是组合视图，而不是声称所有值都在同一时刻、同一页面被观察到。

4. 如何通过 ASIN、关键词、类目和店铺发现商品？

为什么商品发现和详情补全应分成两步？

按 ASIN 获取亚马逊商品数据，适合已有目标清单的任务；关键词、类目、榜单和店铺则用于建立候选集合。发现结果中的标题和价格可以帮助筛选，但不能假定它包含商品详情页的所有规格、媒体和购买条件。将两步拆开，才能分别衡量发现覆盖与详情可用性。

例如，要监控一个类目的新品，可以先保存每次发现的候选 ASIN、入口、位置和时间，再对新增或需要刷新的商品补采详情。不要每次遍历都把整个结果集合按最高频率重抓；也不要因为某次列表里没看到一个 ASIN，就断言它已下架。列表变化可能来自排序、分页、入口或可见范围变化。

关键词搜索反映查询下的结果集合，类目页反映分类入口，店铺页反映该入口可见的卖家商品；它们不是同一个总体。采样报告应写明“从哪些入口发现”，否则“覆盖率很高”缺少分母。若业务要求已知竞品全部可追踪，应另外维护核验过的目标清单。

批量与分页有哪些不能忽略的限制？

Amazon Catalog Items v2022-04-01 的搜索请求中，identifiers 最多 20 个，单次 marketplaceIds 最多 1 个，而且 identifiers 与 keywords 不能放在同一次请求里。这里的 20 是该操作的参数上限，不是所有商品 API 的通用批量能力；多个市场应按接口要求分别组织任务。官方参数定义

Pangolinfo 的 Amazon Scraper API提供商品详情、关键词、类目、店铺、热卖榜和新品榜等解析入口。当前文档明确 pageCount 仅适用于 amzProductOfSeller，最大为 3。请求三页只证明处理了文档限定的页数，不能在交付说明里改写成“已经获取全店商品”。其他入口的翻页方式也应逐项核对，不能共享一个未经确认的参数。解析器与分页参数

分页任务应记录入口参数、页标识、处理状态和去重结果。若采用游标，要保留任务内的续传位置；若采用页码，要识别排序变化导致的重复和遗漏。结束条件应来自接口返回或事先约定的范围，而不是“连续几页没看到新商品”就推断整个市场已经遍历完成。

父子 ASIN 与跨市场同款如何关联？

父子关系表示商品族，不能替代具体购买选项。记录父 ASIN、子 ASIN、选项名称和来源时间，并区分“本次发现的关系”与“业务确认的关系”。某条响应列出若干变体，只能证明本次返回了这些条目；测试全族覆盖需要独立参照，不能让返回列表同时当作分母。

跨市场匹配也不能只比较标题。相似标题可能对应不同包装、插头、净含量、容量或型号后缀。优先核对可验证的标识和关键规格，再用相似度辅助候选匹配。Google Merchant Center 对商品标识的说明也要求按变体处理 GTIN，提醒数据使用者不能把颜色、尺寸变化全部压到一个标识上。商品标识说明

实际匹配流程可以输出“确认同款”“同族不同选项”“待人工核验”三种业务状态。跨市场比价只接收满足其规则的记录，而选品研究可能允许比较相似规格。把这两种任务分开，避免研究阶段的模糊匹配偷偷进入自动价格告警。

新增 ASIN 也需要定义。第一次被本系统发现，不等于商品第一次上市；页面 first_date 可能缺失，也需要核对字段含义。保留 first_seen_at 与来源发布日期两个概念，才能区分“新发现的老商品”和“有证据支持的新上架商品”。

5. 怎样获取可比较的价格、优惠和配送数据？

现价、参考价和优惠券分别回答什么问题？

一个价格数字至少要连接币种、商品选项、卖家、成色、数量和时间。要计算折扣，还需要参考价标签；要计算消费者可能支付的金额，还需要运费、优惠资格、数量条件和税费口径。没有这些条件，就只能报告页面观察值，不能把它包装成所有买家的成交价。

参考价的标签具有业务含义。List Price、Typical price 或其他本地化标签不应仅因为都出现在划线位置就合并成“原价”。若基准改变，折扣率序列也可能发生断点。记录标签及解释证据，必要时暂停跨基准比较，而不是把数值解析成功当成折扣计算成功。

优惠券也不是默认已经生效的价格。领券、会员、购买数量、订阅或其他资格都可能改变适用范围。文档将促销条件与现价分开返回时，应用应该保留这种分离。不要把一个百分比优惠与一个金额优惠机械相减，更不要在没有证据时假设多种优惠可以叠加。

同一商品为什么会有多个有效报价？

同一个子 ASIN 可以出现不同销售方、成色或履约条件。Featured Offer 是特定语境下的推荐购买报价，不等于全部卖家报价，也不能把未出现推荐报价解释为市场没有供给。监控目标若是某个竞品卖家，应追踪卖家身份；若是页面推荐报价，则应把卖家变化作为事件单独保留。

把“卖家更换”和“同一卖家降价”分开，会改变告警处理方式。前者可能需要运营检查供给结构，后者才进入既定价格策略。一个只比较前后 price 的系统，会将这两类事件写成同一种降价，从而给业务制造错误的确定性。

库存同样需要克制解释。公开页面写有可售、剩余数量提示或预计送达，不代表你拿到了卖家的完整库存；采购限制也不一定是仓库剩余量。业务若需要授权账户的库存核算，应使用相应业务接口，并在报告中与公开市场可售观察分列。

邮区、运费和时间如何改变比较结论？

地区监控应显式传入目标邮区，并保存请求值与响应核验结果。Pangolinfo 当前文档说明，未传 bizContext.zipcode 时后台会为该市场选择邮区。因此，默认请求不适合被当成长期固定地区的观测；传入邮区后，也应检查服务提供的地区证据，而不是将请求意图直接写成已验证结果。

本次文档还注明 shippingFee 的 “0” 可代表免运费或没有运费信息。这是一个有业务后果的字段歧义：若没有其他证据，不能据此计算“已确认含运费总价”。保留运费状态，例如已知免费、已知收费、未知，再决定是否进入到手价比较。其余来源若有不同定义，也应按各自契约处理。运费与地区字段说明

一个假设算例：报价 A 为 100 美元，已确认运费 10 美元；报价 B 为 106 美元，但运费未知。可计算 A 的已知商品与运费合计为 110 美元，却不能因此断定 B 更便宜。若后来证实 B 免运费，并且成色、数量和优惠条件一致，比较才具备该层面的依据；税费仍需按任务定义处理。

时间是另一项购买条件。请求发送时间、源页面采集时间、响应接收时间和业务使用时间不应互相冒充。服务没有提供源采集时间时，应明确记录“源时间未知”，而不是用本地接收时间制造实时性。比较窗口由业务容忍度确定，例如是否允许不同商品相隔一小时采集，不能由接口返回顺序替业务决定。

跨币种报告还要把商品原币价格与分析用换算价格分开。记录汇率来源、汇率时间、转换精度及舍入规则，不把报告换算值写回源价格。即便金额已经换成同一种货币，税费、包装和配送条件仍可能不同；汇率转换只消除表达单位的一项差异，不会自动建立同口径的购买成本。历史回算采用当时汇率还是当前汇率，也应由分析目的决定并在报表注明。

6. BSR、评分与评论能支持哪些判断？

为什么不能把 BSR 换算成没有误差的销量？

Amazon 官方将 BSR 解释为商品在同类目中的相对销售表现，并区分 BSR 与搜索排名。这个定义意味着排名必须连同市场、类目和时间理解：不同类目的第 100 名，不等于相同销量；某个关键词搜索位置的变化，也不等同于 BSR 变化。Amazon BSR 说明

排名是排序结果，不是销售流水。要从排名推估销量，需要额外模型、训练或校准数据以及误差评估。若只拥有 BSR，报告应写“排名上升”或“在该类目中的相对位置变化”，不能直接写“销量增长了某个百分比”。同样，页面销售提示若表达区间或阈值，也不能转成精确订单数。

榜单之间也要保留差异。Amazon 的商品研究说明将 Movers & Shakers 描述为过去 24 小时销售排名增幅较大的商品，并说明其按小时更新。这适合发现近期变化，但不能用来定义每个商品详情字段的更新频率，也不能证明某个采集接口按小时保存了完整历史。Amazon 商品研究说明

因此，选品流程可用榜单发现候选，再用连续观察排查偶发波动。将类目、节点和榜单类型一起保存，能够识别商品分类变化造成的排名断点。只存一个 rank 数字，会让后续模型在不知道分类已变的情况下继续拟合趋势。

星级、评分数量和评论明细为什么不能互相替代？

页面星级是聚合结果，评分数量不等于可获取的文字评论数，一页评论也不等于所有评价。比较两件商品的口碑，至少要说明市场、时间、变体范围、筛选条件和可见样本。只采低星评价，适合寻找问题线索，却不能以其情绪比例代表全部买家。

需要亚马逊评论采集时，应单独定义评论对象：评论标识、关联商品、日期、星级、文本、媒体和筛选条件。商品详情页的少量评论或 Customer Says 类摘要可以作为入口，不能替代评论明细任务的分页和覆盖验收。归属不明确的记录应待核验，不按请求 ASIN 覆盖所有返回评论的商品身份。

官方也有评价洞察路线。Customer Feedback API 当前说明数据每周刷新、仅提供英文，覆盖列出的 7 个 Amazon 商店；评价洞察可以在 ASIN 和 browse node 层级提供，退货洞察则在 browse node 层级。这说明“主题洞察”“原始评论”和“实时页面摘要”是不同产品形态，选型应按研究问题决定。Customer Feedback API

怎样让评论分析产生可追溯的产品建议？

可以先定义主题，例如尺寸偏差、安装困难或包装破损，再保存每个主题对应的证据片段、计数分母和商品范围。模型生成的主题名称是分析结果，不应覆盖原始评论。业务人员应能从“某问题被提及”回到对应记录，核对是否存在翻译、讽刺、重复或归属错误。

跨语言比较时，先说明是否做了翻译，以及主题分类是否使用同一规则。不同语言的文本长度、表达方式和采样可见性会影响结果，不能把模型输出的小数当成精度保证。对于样本不足的商品，显示证据数量和限制，比给一个没有稳定依据的综合分更有用。

同样，评论里出现一项抱怨不等于产品缺陷已经被验证。它适合触发调查或设计访谈，而不是直接成为认证、合规或安全结论。商品数据 API 提供观察材料，分析方法和业务验证决定材料能支撑多强的判断。

7. 商品数据怎样用于选品、竞品监控、目录补全和 AI Agent？

选品研究如何从“榜单热门”走向可核验假设？

假设团队准备研究一个家居细分类目。发现阶段先从类目、关键词和榜单建立候选，保留入口与发现时间；详情阶段补充规格、价格、卖家、评价摘要和分类；分析阶段再将同一商品族的变体归组，避免把多个颜色当成多个独立品牌竞争者。

输出不应只是一张“潜力商品排名”。更有用的是一组可验证假设：某个价格带是否缺少某种规格，领先商品的负面主题是否指向未满足需求，观察到的排名改善是否跨多个时间点持续。每个假设连接证据和需要补查的信息，不把相关性写成因果。

类目样本的分母也应公开。只从某个关键词第一页发现商品，就不能将其统计称为全类目市场份额。可以报告“在本次候选集合内的品牌占比”，并说明发现范围。若需要市场规模，应补充有依据的销量或交易数据模型，不能让 API 返回的商品数代替市场规模。

竞品监控如何区分市场变化与采集变化？

监控需要先冻结目标定义：追踪具体子 ASIN、某个卖家 Offer，还是页面当前推荐报价。假设某条记录价格下降，但卖家也变了，系统应生成“报价主体变化”，而不是只生成“同一卖家降价”。若规格切换，则先暂停比较并请求核验。

告警可以经过事件识别、证据检查和业务阈值三层。事件识别发现数值变化；证据检查排除身份、币种、地区和时间不一致；业务阈值决定是否值得通知。阈值由业务容忍度与试点误报情况制定，本文不建议一套通用于所有类目的百分比。

当一批商品同时出现价格为空，优先排查共同原因，例如任务失败、地区设置或解析变化，再解释为市场缺货。监控报告应同时显示采集覆盖与商品事件，避免数据质量下降被业务误读为竞品集体下架。对高影响的价格动作，可要求复采确认或人工审核。

目录补全如何避免把错误规格传播到多个渠道？

目录补全的目标是形成可信的商品主数据，而不是把任何非空值都填进去。品牌、型号、容量、包装数量和图片应有来源优先级。不同来源冲突时，保留冲突并制定审核规则；不能只因为某条记录更新时间更晚，就认定它更准确。

一个常见设计是把原始来源层与已审核目录层分开。前者保留采集内容，后者只发布通过校验的值。对单位变换记录换算规则，对媒体保留来源与使用条件，对描述保留版本。这样发现一次规格误配时，可以定位受影响的下游字段，而不是重新检查整个商品库。

如果需要将数据用于对外页面，应另行核对文本与媒体的使用条件。能取得图片 URL，不等于有权复制图片到所有渠道。对内部分析和对外分发设置不同输出权限，既方便业务复用，也能减少来源与用途混淆。

AI Agent 怎样使用实时商品数据而不编造缺失信息？

通过 Amazon Data MCP等工具入口，Agent 可以在任务中请求商品数据。工具接入解决“如何获取”的问题，但不会自动解决“该相信到什么程度”。工具结果应包含观测对象、市场、请求条件、可用时间信息和状态，不能只向模型传入一段去掉来源的自然语言摘要。

例如，用户询问“哪一款送到指定邮区更便宜”，Agent 需要比较同口径报价，核对运费与优惠资格。若某条运费未知，应说明缺少比较条件或请求补充，而不是自行按零计算。若源时间未知，应避免声称“此刻实时最低价”。

还要将数据读取与业务写操作分开。采集工具输出的商品文本属于外部内容，其中的指令性文字不能成为 Agent 的系统指令。调价、下单或修改目录应有独立授权与审计记录。工具预算、最大调用次数和超时停止条件也应写进工作流，防止模型反复尝试造成不可控成本。

8. 如何用 Pangolinfo 获取并处理商品数据？

第一次请求需要准备哪些参数？

准备 API Key、目标市场、ASIN 和配送地区，再根据任务选择解析器。商品详情使用 amzProductDetail；关键词、榜单和店铺发现使用各自入口。不要把一条详情请求的参数原样复制到所有解析器，也不要把展示示例当成可用于任何市场的默认配置。

Amazon Scraper API当前商品接口文档列出 13 个市场，以及 JSON、rawHtml 和 Markdown 输出选项。这是 2026-09-28 查阅文档时的范围，不是对所有字段在所有市场都有相同覆盖的承诺。下列请求按文档整理；需要你自己的密钥，本次写作没有执行付费商品采集。

export PANGOLINFO_API_KEY='YOUR_API_KEY'
curl --request POST 'https://scrapeapi.pangolinfo.com/api/v1/scrape' \
  --header "Authorization: Bearer $PANGOLINFO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "",
    "parserName": "amzProductDetail",
    "site": "amz_us",
    "content": "B0B4NLGCH5",
    "format": "json",
    "bizContext": {"zipcode": "10041"}
  }'

请求中的邮区是要求，不是核验结果；请求中的 ASIN 也是目标，不是无需检查的返回身份。成功收到响应后，还应确认外层业务状态、任务状态和结果列表，再交给应用规则判断。HTTP 200 只回答传输层的一部分问题。

如何用 Python 保存证据并处理嵌套响应？

下面是可独立保存为 fetch_product.py 的 Python 3 示例，只使用标准库。传入 –fixture 可以读取本地 JSON，便于离线检查响应处理；在线模式需要密钥且可能消耗额度。程序将原始响应保存后再解析，不输出密钥，也不把接收时间伪装成源页面采集时间。

"""One product request or offline response fixture; Python standard library."""
import argparse
import json
import os
from datetime import datetime, timezone
from pathlib import Path
from urllib.error import HTTPError
from urllib.request import Request, urlopen
from uuid import uuid4

ENDPOINT = "https://scrapeapi.pangolinfo.com/api/v1/scrape"


def product_results(payload):
    if not isinstance(payload, dict) or payload.get("code") != 0:
        raise ValueError("Outer API status failed")
    data = payload.get("data")
    tasks = data.get("json") if isinstance(data, dict) else None
    if not isinstance(tasks, list) or not tasks:
        raise ValueError("Expected nonempty data.json task list")
    products = []
    for task in tasks:
        if isinstance(task, str):
            task = json.loads(task)
        if not isinstance(task, dict) or task.get("code") != 0:
            raise ValueError("Product task status failed")
        result_data = task.get("data")
        rows = result_data.get("results") if isinstance(result_data, dict) else None
        if not isinstance(rows, list) or not rows:
            raise ValueError("Expected nonempty data.results list")
        if not all(isinstance(row, dict) for row in rows):
            raise ValueError("Expected product objects")
        products.extend(rows)
    return products


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--asin", required=True)
    parser.add_argument("--site", default="amz_us")
    parser.add_argument("--zipcode", required=True)
    parser.add_argument("--fixture", type=Path)
    parser.add_argument("--output", type=Path, default=Path("captures"))
    args = parser.parse_args()
    args.output.mkdir(parents=True, exist_ok=True)
    raw_path = args.output / ("response-" + uuid4().hex + ".json")
    started_at = datetime.now(timezone.utc).isoformat()
    if args.fixture:
        raw = args.fixture.read_bytes()
    else:
        key = os.environ.get("PANGOLINFO_API_KEY")
        if not key:
            raise RuntimeError("Set PANGOLINFO_API_KEY before an online request")
        body = {"url": "", "parserName": "amzProductDetail",
                "site": args.site, "content": args.asin, "format": "json",
                "bizContext": {"zipcode": args.zipcode}}
        request = Request(ENDPOINT, data=json.dumps(body).encode(),
                          headers={"Authorization": "Bearer " + key,
                                   "Content-Type": "application/json"},
                          method="POST")
        try:
            with urlopen(request, timeout=30) as response:
                raw = response.read()
        except HTTPError as error:
            raw_path.write_bytes(error.read())
            raise RuntimeError(f"HTTP {error.code}; response saved at {raw_path}") from None
    received_at = datetime.now(timezone.utc).isoformat()
    raw_path.write_bytes(raw)
    payload = json.loads(raw)
    products = product_results(payload)
    output = {
        "mode": "fixture" if args.fixture else "online",
        "request_started_at": started_at,
        "response_received_at": received_at,
        "source_captured_at": None,
        "requested_context": {"site": args.site, "asin": args.asin,
                              "zipcode": args.zipcode},
        "destination_verified": None,
        "raw_response_path": str(raw_path),
        "records": [{"returned_asin": row.get("asin"),
                     "identity_match": row.get("asin") == args.asin,
                     "title": row.get("title"), "price_raw": row.get("price")}
                    for row in products],
    }
    print(json.dumps(output, ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()

示例故意只做一次请求。HTTP 错误、超时和业务状态失败应交给调用方记录与处置，不能不分原因无限重试。文档表格与示例对 data.json 元素形态的描述有差异，因此代码兼容对象和 JSON 字符串；其他结构不符合预期时停止处理，避免把错误响应当成空商品。

代码输出还没有达到“可比价格记录”的程度。它保留原始 price 与请求上下文，并将源时间和地区核验标为未知。实际适配器需要从有效证据补齐币种、卖家、成色、优惠条件、选中规格与运费状态，再交给相应任务验收。这里宁可让缺失可见，也不凭字段名猜出一个可下单价格。

哪些检查应放在接入层，哪些应由业务决定？

接入层检查鉴权、响应格式、任务成功与目标对象；标准化层处理类型、单位与字段映射；业务层判断是否能用于选品、比价或目录发布。三层输出不同错误原因。一个未知配送地区可以阻止比价，却不必阻止保存该商品的图片来源。

保留适配器版本也有价值。如果之后发现 size 被误解为存储容量，应能用原始响应重新转换，而不是重新购买所有历史观测。对文档未说明的字段，不急于给它永久含义；将样本、问题和预期用途交给供应商确认，再更新契约与回归样本。

离线测试能证明解析分支按预期工作，不能证明当前商品真实值、访问成功率或地区采集生效。正式试点应另外保留请求、响应、页面核对与通过率记录，并将这几类证据分开。这样上线评审能看清哪些能力被代码验证，哪些能力被实际采集验证。

9. 如何把一次采集扩展为持续运行的数据服务？

发现任务、刷新任务与历史存储怎样分工？

发现任务负责扩充候选商品，刷新任务负责更新已知目标，两者不必采用相同周期。业务可以按商品重要性、字段变化价值和允许延迟划分刷新策略，例如关注集合优先于低频研究样本。具体周期应由试点结果决定，不应把“接口可实时调用”理解为所有商品都值得高频刷新。

建议在原始响应之外保存商品观测表，记录市场、请求与返回身份、请求地区、核验状态、来源时间、接收时间和转换版本。对尚未取得的历史不做补造；需要历史回填时，核对数据源是否有相应记录及其采样口径。回填与实时任务要分开标识，避免历史导入覆盖最新事件。

缓存键同样属于业务语义。只用 ASIN 做键，会把不同市场、地区或解析请求混在一起。缓存键至少包含影响返回结果的请求条件；缓存策略还应写明何时失效和是否允许下游使用旧值。为了可用性保留旧记录可以是合理选择，但必须同时显示它的时间与状态。

新鲜度应按使用时刻计算。若源采集时间有可靠证据，数据年龄等于业务使用时间减去源采集时间；队列等待、缓存停留和下游处理都会消耗这段预算。接口三秒返回，也可能携带更早的内容，因此低响应时延不能证明数据年龄短。没有源时间时，只能报告已知的接收后停留时间，并保留源年龄未知，而不是把未知项按零计入指标。

限流、并发和重试为什么要分开设计？

并发数决定同时在途的任务数，请求速率决定单位时间提交多少次，两者不是同一个参数。一个响应变慢的服务，即使速率不变，也会积累更多在途任务。调度器应同时约束并发、速率和队列等待，避免只把线程数调大就宣称吞吐已提升。

Amazon 文档说明 SP-API 使用令牌桶限流，而且限制与操作、账户和应用等因素有关。某个操作的默认速率不能套给所有操作，响应头也不一定包含全部限制。这支持按操作和账户管理节流的设计；第三方服务则应按其自己的额度、并发与计费契约配置。SP-API 限流说明

重试要先分类。鉴权或参数错误应修正后再提交；可恢复的临时失败可以采用有上限的退避与抖动，并在服务提供 Retry-After 时尊重它。对于超时但服务端可能已完成的任务，要先核对任务查询、幂等或去重能力；不能无依据假定再次提交不会重复计费。

如何识别静默数据错误并保留恢复路径？

质量监控应同时看技术状态与业务字段。技术层统计任务完成、格式错误和时延；数据层按市场、类目和解析器统计必需字段覆盖、身份匹配与地区确认；业务层统计可比记录比例和误报告警。一个总成功率会把这些问题遮在同一个分母里。

对价格和库存相关事件，可以留出隔离区保存待核验记录，而不是删除或补默认值。解析器更新时，先用保留样本回放，检查字段含义、类型与通过状态的变化，再逐步扩大使用。若新版本造成异常，应能回滚转换规则，并从原始响应恢复结果。

供应商故障切换也需验证语义。两个来源都叫 price，不代表包含相同税费、配送或优惠条件。切换后应标出来源变化，重建可比性判断；在证据不足时暂停受影响告警。业务连续性不等于必须持续输出一个数字，必要时输出“暂不可比较”更能保护决策。

10. 怎样计算成本、验收供应商并控制使用边界？

为什么请求单价不足以代表实际成本？

先把计划拆成任务量。假设需要跟踪 2,000 个子 ASIN、2 个市场、每个市场 3 个地区，每天采集 4 次，并假设每次只产生一个目标观测，则一天计划观测数为 2,000 × 2 × 3 × 4＝48,000。这个假设还没有计入发现任务、补采、评论分页或重试，也不是任何服务的计费承诺。

若某个接口支持批量请求，不能直接用观测数除以批量上限就得到费用。需要确认计费按请求、页面、任务、成功结果还是 Credits；同时确认不同解析器、返回格式和失败类型是否同价。页面数、调用数和商品数之间可能是一对多关系，采购表应该把这些单位列开。

更适合比较的指标是每千条业务可用观测成本：同周期相关费用 ÷ 去重后通过验收的观测数 × 1,000。费用范围应明确包含哪些 API、必要重试、存储、转换和异常处理；若把人工排错排除在外，也要写清楚，不能拿口径不同的两个数字比较供应商。

一个假设算例：同周期费用 120 美元，取得 10,000 条响应，其中 8,000 条满足某个比价任务，成本为每千条可用观测 15 美元。若按全部响应计算，则是 12 美元。差额来自分母差异，不是供应商隐藏涨价。详细拆解可参考亚马逊数据 API 可用记录成本。

采购试点如何避免被少量成功样本说服？

先用小样本找失败类型，再分层扩大。两个变体、两个地区、两个时间点形成 8 次观测，可以检验上下文流程，却不能证明生产成功率。扩展时应覆盖计划使用的市场、类目、规格形态、价格缺失、不可配送、优惠条件和高变体数量等场景。

为每项指标写清分子与分母。例如，身份匹配率的分母是需要身份匹配的有效任务，地区确认率的分母是指定地区且要求核验的观测，价格可比率的分母是进入该比较任务的候选记录。排除项要列出，不能把最困难的失败都排除后再宣称“接近全部成功”。

不要仅让供应商展示它挑选的商品。采购方应提交自己的任务集，保留失败和复测结果。涉及业务容忍度的门槛由双方在测试前约定，而不是看完结果再移动门槛。试点报告应能让没有参与演示的同事复核结论。

比较两家服务时，还要控制观测时间差。先固定目标、市场、邮区、字段规则和允许时间窗，再尽量在同一窗口运行。若一方上午采集、另一方晚上采集，价格不同不能直接判定其中一家错误。对争议记录保留各自原始响应，补做页面核对，并将“源内容发生变化”与“采集或解析错误”分开。适配器调试使用的样本和最终验收样本也宜区分，避免规则只适应已经看过的商品。

获取、保存、分析和再分发需要分别确认什么？

商品数据治理应记录来源、取得时间、用途和保存策略。接口提供访问能力，不等于授予所有下游使用权。官方接口按适用条款使用，联盟数据尤其应核对相应内容许可；第三方数据也需查看服务约定以及源内容的使用边界。Creators API 许可入口

对包含评论文本、用户媒体或作者信息的任务，先判断研究所需的最小字段，设置访问控制与保留期限。不要为了“以后可能有用”默认保留和传播所有内容。对外发布图片、评论摘录或生成式总结，应另行评估使用条件与输出风险；此处提供治理检查项，不代替针对具体用途的法律判断。

业务上还需要责任分工：供应商说明采集与字段行为，数据团队维护转换与质量检查，业务方定义何时可以采取动作。三方都不能用“API 已成功返回”替代自己的责任。将这些边界写清楚，才有可能在出现错误告警时定位问题，而不是在多个系统之间互相推诿。

读完后应怎样开始一个可评估的试点？

选一个业务任务，建立目标清单，写明市场、地区、时间容忍度和必需字段。随后用亚马逊商品数据 API文档组织最小请求集，保存原始响应，验证对象与语义，再扩大到异常场景。需要评论时单独接入 Amazon Review API，不要用商品页摘要替代评论数据集。

试点结束应交付可复查的结果：哪些任务可用、哪些条件未知、哪些失败可恢复，以及每千条可用记录花费多少。决定是否扩大采购的依据，应是这份证据与业务价值，而不是一次成功演示。先把你最不能接受的错误写进验收表，再让接口证明它是否适合这项工作。