Amazon Ads Report — Amazon Ads 报告

Amazon Ads 报告获取 报告一站式获取：脚本自动完成报告的创建、等待（约 2–10 分钟）、下载和解压，直接返回可读的结构化数据。 脚本本身不做"该选哪些列 / 该怎么分组"的业务判断，这些由 agent 先查 references/report-types/ 下对应的 .md 文件，再显式传给脚本。 依赖 linkfox-amazon-ads-auth（脚本启动自动检查；未安装时 exit 42，stderr 打 DEPENDENCY_MISSING）。 多账号场景：调用前必须解析好 profileId 用户经常只说自然语言（"美国站"、"日本站"、"我的店铺"），本 skill 的所有脚本都必须拿到数字 profileId 才能调。 按下列顺序处理，不要跳过： 先调 linkfox-amazon-ads-auth 的 authorized_stores.py 拉出用户已授权的账号 × 站点清单。 根据用户提到的站点（映射到 countryCode，如 美国→US）匹配候选 profile： 只有 1 个候选 → 静默取对应 profileId，继续调用；不要把 profileId 数字播报给用户。 ≥ 2 个候选（同站点下多个授权账号） → 必须向用户澄清，用 accountName 问："你在美国站授权了 A 和 B 两个账号，这次用哪个？" 0 个候选 → 告知用户该站点未授权，引导去 linkfox-amazon-ads-auth 做授权。 严禁让用户直接报 profileId 数字。 严禁在歧义下"挑第一个"或"选默认"绕过澄清。 完整决策表见 linkfox-amazon-ads-auth SKILL.md 的 Usage Scenarios 第 4 节。 Core Concepts 覆盖：SP / SB 全部报告类型（以 references/report-types/ 下存在的 .md 为准；SD / ST / DSP 暂未覆盖） 一站式：脚本内部自动完成报告创建 → 等待生成（约 2–10 分钟）→ 下载 → 解压，调用方只需等最终结果 单脚本：get_report.py（覆盖 SP / SB 全部 adProduct） 元数据 vs. 运行参数： 每个报告类型的可用字段（timeUnit / groupBy / filters / 全部列名）集中在 references/report-types//.md 脚本运行参数（等待间隔、访问链接时效等）见本文件和 references/api.md 可用脚本 脚本 职责 get_report.py 一站式执行。必填 adProduct / groupBy / columns，由 agent 从 report-types/ 提取后传入 check_auth_dependency.py 检测 linkfox-amazon-ads-auth 是否安装 完整脚本参数、响应结构见 references/api.md。 Agent 调用流程 Agent 触达"拉取亚马逊广告报告"类需求时，必须按下列顺序： 定 reportTypeId：按用户意图挑选（如"上周花费"→ spCampaigns；"哪个商品卖得好"→ spAdvertisedProduct / sbPurchasedProduct；"用户搜什么词找到我"→ spSearchTerm） 查 reference：打开 references/report-types//.md frontmatter 给出：adProduct / groupBy（Configuration 表推荐的） / timeUnit(可枚举) / format / dateRange / filters Base metrics 表 给出：此报告类型允许的全部列名 向用户咨询可定制条件（用户答"默认/随便"时跳过，进入第 4 步的默认选择）： timeUnit：DAILY（按日拆分）还是 SUMMARY（汇总） columns 扩展：是否要归因列（sales7d / purchases7d / acosClicks7d / roasClicks7d）、视频指标、newToBrand 等 filters：是否过滤 campaignStatus / keywordType / adStatus 等 按用户回复或默认构造 columns（见下节 "默认条件"） 调脚本：adProduct / groupBy / columns 三个必填字段显式传入 默认条件（用户未指定时使用） 条件 默认规则 timeUnit 日期跨度 ≤ 7 天 → DAILY；> 7 天 → SUMMARY columns 身份维度 DAILY 时必含 date；SUMMARY 时必含 startDate + endDate；再追加该报告的主键字段（参考 frontmatter 中 groupBy 对应的主键，如 campaignId+campaignName / advertisedAsin+advertisedSku / searchTerm / keyword 等） columns 基础指标 impressions / clicks / cost（以该报告 Base metrics 存在的为准） columns 归因指标 仅当用户提到"销售/转化/ROI/ACOS"等意图时追加：sales7d / purchases7d / acosClicks7d / roasClicks7d（以 Base metrics 存在者为准） filters 不加（全量返回） groupBy 取 frontmatter groupBy 数组的第一个值（即 Configuration 表里 Amazon 官方推荐的主维度） 请求示例 所有 example 都显式传入三个必填字段（adProduct / groupBy / columns）。

• SP 广告活动报告（最常见）

python scripts/get_report.py '{ "profileId": 1234567890, "region": "NA", "reportTypeId": "spCampaigns", "adProduct": "SPONSORED_PRODUCTS", "groupBy": ["campaign"], "columns": ["date","campaignId","campaignName","impressions","clicks","cost"], "startDate": "2026-04-27","endDate": "2026-05-03", "timeUnit": "DAILY" }'

• SP 搜索词报告（含归因）

python scripts/get_report.py '{ "profileId": 1234567890, "region": "NA", "reportTypeId": "spSearchTerm", "adProduct": "SPONSORED_PRODUCTS", "groupBy": ["searchTerm"], "columns": ["searchTerm","keyword","matchType","impressions","clicks","cost", "sales7d","sales14d","purchases7d","acosClicks14d","roasClicks14d", "startDate","endDate"], "startDate": "2026-04-01","endDate": "2026-04-30", "timeUnit": "SUMMARY", "filters": [{"field":"keywordType","values":["BROAD","PHRASE","EXACT"]}] }'

• SB 广告组报告

python scripts/get_report.py '{ "profileId": 1234567890, "region": "NA", "reportTypeId": "sbAdGroup", "adProduct": "SPONSORED_BRANDS", "groupBy": ["adGroup"], "columns": ["adGroupId","adGroupName","impressions","clicks","cost","purchases","sales","startDate","endDate"], "startDate": "2026-04-01","endDate": "2026-04-30" }'

• 轮询一个已有 reportId（救回上次超时 / 手工恢复）

当上次运行因为客户端轮询窗口太短退出、但报告在 Amazon 侧仍在跑时，直接传入 reportId 即可跳过创建，继续轮询并下载。此模式下只需 profileId / region / reportId，其余字段不必填。 python scripts/get_report.py '{ "profileId": 1234567890, "region": "NA", "reportId": "7df1ef5d-45ba-40cc-b607-ff2148cf4f5e", "maxAttempts": 60, "pollInterval": 30 }' 自动恢复：如果调用方未传 reportId、且 Amazon 对同参数请求触发去重（返回 HTTP 425 The Request is a duplicate of : ），脚本会自动解析出老 reportId 并转为轮询该老报告，无需重试。 响应格式 成功： { "success": true, "reportId": "4ee811a0-...", "reportTypeId": "spCampaigns", "startDate": "2026-04-28", "endDate": "2026-05-04", "downloadPath": "C:/.../tmp/report_data.json", "extractedFileHttpUrl": "http://127.0.0.1:51234/download", "extractedFileHttpServeSeconds": 300 } 失败： {"error":"Upstream HTTP 400","httpStatus":400, "body":"{\"code\":\"400\",\"detail\":\"startDate to endDate range (32 days) must not exceed maximum range (31 days)\"}"} 调用原则 用户指定了 reportTypeId 就只拉那一种，不擅自替换 报告失败（非 2xx 或 status=FAILED）时如实告知错误原因，不盲目重试 成功后把报告的本地文件路径和访问链接完整展示给用户，并提醒访问链接有时效（默认 5 分