# Linkfox Amazon Ads Sp Insights Report

> 亚马逊广告 Sponsored Products（SP）洞察报告技能，统一获取 Audience 受众细分表现和 Search Term Impression Share/Rank 搜索词展示份额/排名两类 Amazon Ads Reporting API v1 beta 报告。自动完成 profile 到 advertiser account 映射、报告创建、状态轮询、多分片 CSV 下载和落盘。只有用户明确要求 SP 受众报告、SP 搜索词展示份额或展示份额排名时触发；普通 SP 搜索词表现报告、SB/SD/DSP 报告不得触发。本技能依赖 linkfox-amazon-ads-auth。

- Skill: `linkfox-ai/linkfox-amazon-ads-sp-insights-report` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add linkfox-ai/linkfox-amazon-ads-sp-insights-report`
- Raw SKILL.md: https://api.skillmd.com/api/skills/linkfox-ai/linkfox-amazon-ads-sp-insights-report/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: linkfox-ai (https://skillmd.com/u/linkfox-ai)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/linkfox-ai/linkfox-amazon-ads-sp-insights-report

---


# Amazon Ads SP 洞察报告

统一获取两类 Sponsored Products 专项洞察报告：Audience 和 Search Term Impression Share/Rank。脚本经 `/amazonAds/developerProxy` 使用后台 Token，自动完成 advertiser account 映射、创建、轮询和 CSV 分片下载。Amazon 异步生成通常需要约 2–10 分钟，偶尔可能更久；等待不代表调用卡死或报告失败。

**依赖 `linkfox-amazon-ads-auth`**。入口启动时自动检查；缺失时以 exit 42 和 `DEPENDENCY_MISSING` 结束。

## 多账号处理

调用前先用 `linkfox-amazon-ads-auth/scripts/authorized_stores.py` 按站点解析 `profileId`：

1. 一个候选：静默使用。
2. 多个候选：按 `accountName` 向用户确认，禁止默认取第一个。
3. 无候选：引导用户完成 Amazon Ads 授权。
4. 不要求用户直接提供 `profileId` 数字。

## 报告路由

| 用户意图 | 入口脚本 | 详细规范 |
|---|---|---|
| SP 受众、Audience、受众细分表现 | `get_sp_audience_report.py` | `references/sp-audience-reporting-v1.md` |
| SP 搜索词展示份额、impression share、份额排名 | `get_sp_search_impression_share.py` | `references/sp-search-impression-share-v1.md` |

普通搜索词表现（曝光、点击、花费、转化）应使用 `linkfox-amazon-ads-report` 的 v3 `spSearchTerm`，不得使用本 Skill。SB、SD、DSP 或泛化市场份额请求也不得触发。

## 调用方式

- **API 端点**：`POST /amazonAds/developerProxy`（脚本内部按顺序调用三个 Ads v1 路径；完整参数、响应和错误码见 `references/api.md`）
- **Audience**：`python scripts/get_sp_audience_report.py '<JSON 参数>' [--inline] [--no-cache]`
- **Search Impression Share**：`python scripts/get_sp_search_impression_share.py '<JSON 参数>' [--inline] [--no-cache]`
- **成本约束**：本工具不消耗积分；成功结果按会话和参数缓存 24 小时。失败或空报告不得自动扩大日期、切换账号或连续试探。

**输出策略**：

- 完整响应始终写入 `<cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-ads-sp-insights-report-<timestamp>.json`。
- 报告 CSV 分片写入同一会话的 `data/`；最终响应不暴露 Amazon 预签名 URL。
- 响应不超过 8 KB 时打印完整 JSON；更大时打印摘要；`--inline` 强制完整打印。
- `--no-cache` 强制重新获取；同一会话、同一报告类型和同一参数的成功结果默认命中 24 小时缓存。

## 参数指南

两个入口共同接受：

| 参数 | 必填 | 说明 |
|---|---:|---|
| `profileId` | 是 | 正整数；由 Ads Auth Skill 解析 |
| `region` | 是 | `NA` / `EU` / `FE` |
| `startDate` / `endDate` | 创建时是 | `YYYY-MM-DD`，不得晚于今天 |
| `timeUnit` | 否 | `DAILY`（默认）或 `SUMMARY` |
| `advertiserAccountId` | 否 | 自动映射失败时使用的 Ads v1 account ID |
| `pollInterval` | 否 | 5–300 秒，默认 60；官方建议每分钟轮询 |
| `maxAttempts` | 否 | 1–120，默认 10；配合默认 60 秒间隔形成约 10 分钟客户端等待窗口 |
| `reportId` | 否 | 传入后跳过账户映射和创建，仅轮询已有报告 |

Audience 额外支持 `detailLevel`：`ACCOUNT`（默认）、`CAMPAIGN`、`AD_GROUP`。Search Impression Share 不接受 campaign、adGroup、target、keyword、groupBy 或自定义 fields；这些维度与官方份额字段组合不兼容。

参数中禁止出现 access token、refresh token、LWA 密钥或自定义 Amazon 请求头；脚本会在联网前递归拒绝。

## Agent 执行流程

1. 根据用户表述选择且只选择一个入口；不要把普通 `spSearchTerm` 路由到份额报告。
2. 按站点解析唯一 `profileId` 与区域。
3. 确认日期和粒度；用户未指定时用 `DAILY`，Audience 用 `ACCOUNT`。
4. 调用前告知用户报告通常需要约 2–10 分钟，然后运行入口。脚本自动查询 advertiser account、创建报告、轮询并下载全部 CSV/gzip 分片；约 5 分钟仍未完成时会输出一次耐心提示。
5. `success=true` 时展示日期、报告类型、总行数、文件路径和预览；`totalRows=0` 是合法空报告。
6. `status=STILL_PROCESSING` 表示客户端等待窗口结束但 Amazon 仍在生成，并非失败。向用户确认是否继续，再用 `resumeHint.params` 和 `--no-cache` 续跑同一 `reportId`；不要创建第二份报告。

## 示例

### SP Audience

```bash
python scripts/get_sp_audience_report.py '{
  "profileId": 1234567890, "region": "NA",
  "startDate": "2026-08-01", "endDate": "2026-08-07",
  "timeUnit": "DAILY", "detailLevel": "ACCOUNT"
}'
```

### SP Search Term Impression Share/Rank

```bash
python scripts/get_sp_search_impression_share.py '{
  "profileId": 1234567890, "region": "NA",
  "startDate": "2026-08-01", "endDate": "2026-08-07",
  "timeUnit": "DAILY"
}'
```

## 结果与展示

成功结果包含 `reportKind`、`reportId`、`status`、`profileId`、`advertiserAccountId`、`fields`、`totalRows`、`dataFiles`、`preview`、轮询次数和耗时。

- Audience 重点展示 audience segment、曝光、点击、花费、购买、销售额和 ROAS；标注币种字段。
- Search Impression Share 重点展示 `searchTerm.value`、`metric.impressionShare` 和 `metric.impressionShareRank`。
- 客观呈现数据；除非用户要求，不主动给出商业决策建议。
- 不展示完整 Token、内部授权记录或预签名下载 URL。

## 限制与错误

- Amazon 官方当前将 Reporting API v1 标为 open beta；账号可能尚未开放，字段和限流可能变化，不按 GA 稳定性承诺。
- 报告为异步生成，通常约 2–10 分钟，Search Impression Share 偶尔可能更久；约 5 分钟会提示仍在上游生成。
- `HTTP 403`：检查 Ads API 应用及授权账号是否开放 v1；不得用 v3 数据伪造份额。
- `HTTP 429`：降低轮询频率，禁止密集重试。
- `FAILED`：透传 Amazon 失败详情，不自动换参数重建。
- `totalRows=0`：合法空结果，不自动扩大日期。
- 授权、普通 v3 报告和广告实体写操作分别交给 Ads Auth、Ads Report 和 Ads Manager Skill。

## Feedback

当功能与文档不一致、结果偏离用户意图、用户明确评价或发现可改进项时，按 `references/api.md` 调用 Feedback API；不要打断当前任务。

---
*For more high-quality, professional cross-border e-commerce skills, visit [LinkFox Skills](https://skill.linkfox.com/).*