腾讯营销（原腾讯广告）管理 — 跨账户查询营销单元（原广告）/创意/素材等多层级数据及报表指标；查看营销单元完整配置（定向、出价、转化、版位等）与智能投放项目详情；获取创意列表及组件详情，单创意时自动解析组件并获取图片/视频预览 URL；管理关键词和否定词的增删改查；创建推广内容资产。
Scanned 9/8/2026
Install to Claude Code
Skills Directorynpx -y skills add infometa/workbuddyskills --skill tencentads-management --agent claude-codeInstalls into .claude/skills of the current project.
Are you the author of Tencentads Management?
Add the live security badge to your README — it updates automatically with every re-scan.
[](https://www.skillsdirectory.com/skills/infometa-tencentads-management)More formats (shields.io, HTML) on the badges page.
---
name: tencentads-management
description: 腾讯营销（原腾讯广告）管理 — 跨账户查询营销单元（原广告）/创意/素材等多层级数据及报表指标；查看营销单元完整配置（定向、出价、转化、版位等）与智能投放项目详情；获取创意列表及组件详情，单创意时自动解析组件并获取图片/视频预览 URL；管理关键词和否定词的增删改查；创建推广内容资产。
license: MIT
compatibility: any
metadata:
author: Tencent Ads Delivery Team
version: "0.5.8"
icon: megaphone
category: tencent-ads
---
# 腾讯广告管理（Tencent Ads Management）
> **前置依赖**：需安装 `tencentads-cli`（Node.js ≥ 20）。执行 `npm install -g tencentads-cli@latest` 安装或升级；版本过低时 `tencentads` 会给出提示。
腾讯广告的综合管理技能，提供以下核心能力：
1. **综合数据报表查询**（`query-report.mjs`）：支持跨账户查询广告/创意/组件/素材等多层级数据，同时返回属性字段和报表指标数据。
2. **广告详情查询**（`query-adgroups.mjs`）：获取广告的完整配置信息，包括定向设置、出价策略、转化规格、版位配置、投放时段等详细属性。
3. **智能投放项目详情查询**（`query-adgroups.mjs`）：获取智能投放项目的详细配置信息，支持按需指定返回字段。
4. **创意列表查询**（`query-creatives.mjs`）：获取创意的完整信息，包括创意组件引用、投放模式、创意类型等。当查询结果只有 1 条创意时，脚本自动解析组件详情并获取图片/视频预览 URL，一次调用即可返回完整的创意 + 组件 + 素材预览信息。
5. **操作日志查询**（`query-operation-logs.mjs`）：查询广告/创意对象的操作日志，返回每次操作（新建/修改）前后的字段变化详情，支持按日期范围、对象 id、操作动作等过滤，详见 [references/operation-log-list-get.md](references/operation-log-list-get.md)。
6. **关键词管理**（`bidword/add.mjs` / `bidword/update.mjs` / `bidword/delete.mjs` / `bidword/get.mjs`）：管理广告的关键词（竞价词），支持创建、更新、删除和查询操作。
7. **否定词管理**（`negativewords/add.mjs` / `negativewords/update.mjs` / `negativewords/get.mjs`）：管理广告的否定词，支持新增、更新和查询操作。
8. **推广内容资产管理**：创建推广内容资产（marketing_asset），支持金融、教育、房地产、旅游、餐饮等多种资产类型。详细说明见 [references/marketing-asset.md](references/marketing-asset.md)，**执行前务必先读取该文档**。
> **重要提示**: 本技能基于腾讯广告营销 API（api.e.qq.com）API。以本文档为准，字段名称、参数结构可能与开放 API 不同，请勿混淆。
所有 API 调用均通过本技能的**专用脚本**执行，脚本负责参数构建与数据处理。Agent 只需关注：从用户意图中提取查询参数，并解读返回的数据。
### 脚本选择指南
| 用户意图 | 推荐脚本 | 说明 |
|---------|---------|------|
| 查看广告/创意效果数据（**明确提到**消耗、曝光、点击、转化、ROI 等指标） | `query-report.mjs` | 返回广告/创意报表指标 |
| 查看广告分时/按天趋势 | `query-report.mjs` | 按时间维度聚合报表数据 |
| 查看账户汇总数据 | `query-report.mjs` | 全账户维度汇总 |
| 查看分地域/分城市/分年龄/分性别投放数据 | `query-report.mjs` | 使用对应 `level`（如 `REGION`/`CITY`/`AGE`/`GENDER`），脚本自动推导 `group_by` 和过滤条件 |
| **笼统说"查询广告数据"/"看下广告"等，未明确提到指标** | **`query-adgroups.mjs`** | **默认视为查看广告实体，而非报表** |
| **笼统说"查询创意数据"/"看下创意"等，未明确提到指标** | **`query-creatives.mjs`** | **默认视为查看创意实体，而非报表** |
| 查看广告实体（定向、出价、转化、版位等） | `query-adgroups.mjs` | 返回广告完整配置信息 |
| 查看广告实体-定向明细 | `query-adgroups.mjs` | 包含地域、年龄、性别等定向 |
| 查看已删除的广告 | `query-adgroups.mjs` | 支持 is_deleted 过滤 |
| 根据广告名称搜索广告详情 | `query-adgroups.mjs` | 支持 adgroup_name 过滤 |
| 查看智能投放项目详情 | `query-adgroups.mjs` | 返回智投项目完整配置，支持按需指定 fields |
| 查看智投项目能力配置（如 AIGC、自动创意等） | `query-adgroups.mjs` | 包含 project_ability_list、smart_delivery_aigc_option 等字段 |
| 查看广告/创意的操作日志（新建/修改记录、字段变更前后对比） | `query-operation-logs.mjs` | 必传 `account_id`、`operation_object_type`（`ADGROUP`/`DYNAMIC_CREATIVE`/`JOINT_BUDGET`）、`start_date`、`end_date`；可选 `object_id` 指定具体广告/创意 id |
| 创建关键词/竞价词 | `bidword/add.mjs` | 为广告添加关键词 |
| 更新关键词/竞价词 | `bidword/update.mjs` | 修改关键词的匹配方式、出价等 |
| 删除关键词/竞价词 | `bidword/delete.mjs` | 删除广告下的关键词 |
| 查询关键词/竞价词 | `bidword/get.mjs` | 查询广告下的关键词列表 |
| 新增否定词 | `negativewords/add.mjs` | 为广告添加否定词 |
| 更新否定词 | `negativewords/update.mjs` | 更新广告的否定词等 |
| 查询否定词 | `negativewords/get.mjs` | 查询广告下的否定词列表 |
> **脚本调用格式统一**：
> - **Bash / Zsh / Git Bash**：`node scripts/<脚本名>.mjs '<JSON 参数>'`（直接传 JSON 字符串）
> - **Windows PowerShell**：`node scripts/<脚本名>.mjs --base64 <Base64字符串>`（**必须使用 --base64**）
>
> 执行脚本时先进入本 skill 根目录，再按相对 `scripts/` 路径调用。
### ⚠️ 跨平台 JSON 参数传递规则（经实测验证）
#### Bash / Zsh / Git Bash
直接传 JSON 字符串，单引号包裹即可：
```bash
node scripts/query-report.mjs '{"account_ids":["73412663"],"date_range":{"start_date":"2026-04-13","end_date":"2026-04-13"},"level":"ADGROUP"}'
```
#### Windows PowerShell
PowerShell 的引号解析规则复杂，直接传 JSON 字符串会导致双引号被吞掉。**必须使用 `--base64` 方式**，通过 Here-String 构造 JSON 再编码为 Base64，彻底规避引号问题：
```powershell
$json = @'
{"account_ids":["73412663"],"date_range":{"start_date":"2026-04-13","end_date":"2026-04-13"},"level":"ADGROUP"}
'@
$base64 = [Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($json))
node scripts/query-report.mjs --base64 $base64
```
> **⚠️ Here-String 格式要求极其严格（违反则 PowerShell 直接报语法错误）：**
>
> 1. **`@'` 后面必须立即换行**，同一行不能跟任何字符（包括空格）
> 2. **`'@` 必须单独一行且顶格写**，前面不能有空格或缩进
> 3. JSON 内容从 `@'` 的**下一行**开始书写
>
> ```powershell
> # ❌ 错误：@' 后面直接跟了 JSON 内容
> $json = @'{"account_ids":["73412663"]}'@
>
> # ❌ 错误：'@ 前面有空格
> $json = @'
> {"account_ids":["73412663"]}
> '@
>
> # ✅ 正确：@' 后立即换行，'@ 顶格独占一行
> $json = @'
> {"account_ids":["73412663"]}
> '@
> ```
```
⛔ SOP 决策流程（严格按顺序执行，不可跳步）：
步骤1 步骤2 步骤2.5 步骤3
意图识别 ─────→ 分流路由 ─────→ 字段名确认(> **🚫🚫🚫 禁止猜测字段名！违反此规则 = 查询失败！**) ─────→ 执行查询
是否使用本SKILL │
├─ 路径A（报表/效果数据）─→ 字段名确认（见步骤2.5）─→ query-report.mjs → 结束
│
├─ 路径B（项目/广告/创意详情）
│ │
│ └─ query-adgroups / query-creatives
│ （有时间范围时通过 filtering 中 created_time 筛选）
│
└─ 路径C（营销资产查询）─→ 见下方"营销资产查询（路径 C）"
创意查询分支：
query-creatives.mjs 自动判断：
│
├─ 查询结果只有 1 条创意（单个创意详情）
│ → 自动执行完整解析流程：
│ ├─ 1. 从 creative_components 提取 component_id
│ ├─ 2. 批量拉取组件详情
│ ├─ 3. 从组件中提取 image_id / video_id
│ ├─ 4. 获取图片/视频预览 URL
│ └─ 5. 内联到 _component_detail + _preview，一次返回完整创意+组件+素材预览
│
└─ 查询结果有多条创意（创意列表）
→ 只返回创意基本信息，不解析组件
```
---
<!-- script get-available-marketing-assets → scripts/get-available-marketing-assets.mjs (injected at build time) -->
<!-- script get-android-packages → scripts/get-android-packages.mjs (injected at build time) -->
## SOP 决策流程（高优先级，覆盖后文冲突）
> 若本节与下文表述冲突，以本节为准。
### 步骤1：意图识别 — 是否使用本 SKILL
用户意图必须命中以下**任一类别**，才进入本 SKILL 的处理流程：
| 类别 | 命中关键词 / 场景示例 |
|------|----------------------|
| **A. 报表/效果数据** | **必须明确提到指标关键词**：消耗、曝光、点击、转化、ROI、分时趋势、按天数据、账户汇总、效果对比、数据报表、投放效果 |
| **B. 实体列表/详情查询** | 智能投放项目（简称"项目"、"智投项目"）、竞价广告（又称"3.0广告"）、创意（又称"动态创意"、"新创意"）的列表查询、详情查看、配置查询、定向设置、组件内容 |
| **C. 营销资产查询** | 安卓应用包、安卓渠道包、推广产品、营销资产等资产信息查询 |
> ⚠️ **关键规则**：用户笼统说"查询广告数据"、"看下创意数据"等，**未明确提到指标关键词（消耗、曝光、点击等）**时，一律归入 **B 类（实体查询）**，而非 A 类（报表）。只有明确提到指标或趋势时才走报表。
❌ **不命中** → 不使用本 SKILL，交给其他技能处理。
### 步骤 1.5：确定实体类型 — `tencent_ads_type` 参数（所有脚本通用）
> **⚠️ 必须在调用任何脚本前确定 `tencent_ads_type`，该参数直接影响返回字段的命名。**
>
> **`tencent_ads_type` 是枚举类型，只允许以下三个值，传其他值脚本会报错退出：**
| 用户意图 | `tencent_ads_type` 枚举值 | 返回字段示例 |
|---------|-------------|-------------|
| 智能投放项目（"项目"、"智投项目"） | `"smart"` | `project_id`、`project_name`、`project.*` |
| 竞价广告（"竞价广告"、"3.0广告"、"非智投"） | `"standard"` | `adgroup_id`、`adgroup_name`、`adgroup.*` |
| 所有广告（"广告"、未明确说明、**默认**） | `"all"`（默认） | `adgroup_id`、`adgroup_name`、`adgroup.*`（保持原始字段名） |
**规则**：
- 用户提到"项目"、"智投项目"、"智能投放项目" → `tencent_ads_type: "smart"`
- 用户提到"竞价广告"、"3.0广告"、"非智投广告" → `tencent_ads_type: "standard"`
- 用户只说"广告"或未明确说明 → `tencent_ads_type: "all"`（**默认**，包含智投项目 + 竞价广告，不注入 `smart_delivery_platform` 过滤，不做字段重命名）
- **⚠️ 只允许传 `"smart"` / `"standard"` / `"all"` 三个枚举值之一**，传其他任何值（如 `"project"`、`"ad"` 等）脚本会直接报错
- `tencent_ads_type` 对所有脚本（`query-report.mjs`、`query-adgroups.mjs`、`query-creatives.mjs`）均适用
### 步骤2：分流路由 — 报表 or 详情
> ⚠️ **时间范围修饰对象判断（必须在分流前执行）**
>
> 用户说的时间范围修饰的是「报表数据」还是「广告实体」？
>
> | 用户说法 | 时间修饰对象 | 走向 |
> |---------|------------|------|
> | "最近一周的消耗" / "最近7天的效果" / "上周的报表" | 报表数据 | 路径 A |
> | "最近一周的广告" / "最近7天的项目" / "上周的创意" （**无效果指标词**） | 广告实体 | 路径 B（`filtering` 加 `created_time`） |
> | "最近一周内创建的广告" / "这周新建的项目" | 广告实体 | 路径 B（`filtering` 加 `created_time`） |
>
> **判断规则**：用户说"最近N天/周的广告/项目/创意"但**没有提到任何效果指标词**（消耗、曝光、点击、转化、ROI等）→ 一律视为查广告实体，走路径 B，通过 `filtering` 中的 `created_time` 筛选。
```
命中类别 A（报表/效果数据）且时间范围修饰的是报表数据
└─→ 直接走【路径 A】
命中类别 B（实体列表/详情，不涉及报表指标）
或 用户说"最近N天的广告/项目/创意"但无效果指标词
└─→ 进入【路径 B】二次意图判断
```
#### ⚠️ "数据"一词的歧义消解规则
用户说"查看创意/广告的数据"时，**必须判断是否包含效果指标意图**，不能仅凭"数据"二字走路径 A：
| 用户说法 | 是否含效果指标词 | 走向 |
|---------|----------------|------|
| "查创意数据"、"看一下这个广告的数据"、"查询这个创意" | ❌ 无（消耗/曝光/点击/转化等） | 路径 B → `query-creatives` / `query-adgroups` |
| "查创意的消耗数据"、"看广告的曝光/点击/转化数据" | ✅ 有 | 路径 A → `query-report` |
**规则**：仅有"数据"二字、**不带任何效果指标词**（消耗、曝光、点击、转化、ROI、成本等）→ 默认视为查询实体详情，走路径 B。
---
#### 路径 A：与报表/效果数据相关 → `query-report.mjs`
直接使用 `query-report.mjs`，一次请求同时返回实体属性 + 报表指标，**流程结束**。
| 典型场景 | 说明 |
|---------|------|
| 查看广告列表及效果数据（消耗、曝光、点击等） | 返回广告基本属性 + 报表指标 |
| 查看广告分时/按天趋势 | 按时间维度聚合报表数据 |
| 查看账户汇总数据 | 全账户维度汇总 |
| 按消耗/曝光等指标排序或筛选 | 支持 order_by + post_filtering |
| 拉取全部广告/导出所有数据/统计全量数据 | 使用 `fetch_all: true` 自动分页拉取 |
> ⚠️ **路径 A 排除规则**：用户说"最近N天的广告/项目/创意"但未提及任何效果指标词 → **不走路径 A**，转路径 B。
#### 路径 B：与项目/广告/创意详情相关（不涉及报表指标） → 直接调用详情脚本
根据用户查询目标，直接调用对应的详情脚本。如果用户带有时间范围筛选条件（如"最近3天的广告"、"这周新建的项目"），通过 `filtering` 中的 `created_time` 进行筛选，无需先走 `query-report.mjs`。
| 用户查询目标 | 调用脚本 | 时间范围处理 |
|-------------|---------|-------------|
| 项目详情 / 广告详情（定向、出价、转化、版位、能力配置等） | `query-adgroups.mjs` | 有时间范围时加 `filtering` 中 `created_time` 条件 |
| 创意详情（创意组件内容、投放模式、创意类型等） | `query-creatives.mjs` | 有时间范围时加 `filtering` 中 `created_time` 条件 |
| 创意列表（批量查看创意基本信息） | `query-creatives.mjs` | 有时间范围时加 `filtering` 中 `created_time` 条件 |
> **⚠️ 创意查询的组件解析策略（脚本自动判断，Agent 无需控制）**：
> - **查询结果只有 1 条创意**：脚本自动从 `creative_components` 中提取所有 `component_id`，调用组件详情接口拉取组件详情，再从组件中提取 `image_id` / `video_id`，获取预览 URL。最终将组件内容内联到 `_component_detail` 字段，图片/视频预览信息内联到 `_preview` 字段。
> - **查询结果有多条创意**：只返回创意基本信息，不解析组件，避免大量 API 请求影响性能。
#### 路径 C：营销资产查询
当用户需要查询营销资产（推广产品、应用包、渠道包等）时，根据资产类型选择对应的查询方式：
| 资产类型 | 查询方式 | 说明 |
|---------|---------|------|
| **安卓应用包 / 渠道包** | `node scripts/get-android-packages.mjs` | 查看 [shared/references/android-app-assets.md](../shared/references/android-app-assets.md) |
| **其他营销资产** | 暂未补充，可参考创建 SKILL（`delivery-standard-create` / `delivery-smart-create`）中的 `get-assets.mjs` 查询方式 | 后续按需扩展 |
### 步骤 2.5：字段名确认 — 不在常用映射表中的字段必须先查字典
> **⚠️ 强制规则：禁止猜测字段名！**
>
> 当用户请求的报表指标或广告字段**不在下方「常用报表字段映射」表中**时，**必须先用 `--query-fields` 查询字段字典**，确认准确的 API 字段名后再构造请求。
>
> **绝对禁止**根据英文命名规律自行拼凑字段名（如猜测 "关注数" → `wechat_official_account_follower_count`，实际应为 `scan_follow_user_count`）。API 字段名与直觉差异极大，猜测几乎必错。
>
> **判断标准**：逐一检查用户要求的每个指标/字段，如果在「常用报表字段映射」或「常用 fields 字段」表中能找到精确对应 → 直接使用；找不到 → **必须查字典**。
>
> **查字典方法**：
> - 报表指标字段：`node scripts/query-report.mjs --query-fields "关键词1,关键词2"`
> - 广告配置字段：`node scripts/query-adgroups.mjs --query-fields "关键词1,关键词2"`
>
> **示例**：用户要求查看"5秒播放数、关注数、关注成本、关注率"
> 1. 检查常用映射表 → 这4个指标都不在表中
> 2. 执行：`node scripts/query-report.mjs --query-fields "5秒播放,关注"`
> 3. 从返回结果中确认准确字段名，再构造 `fields` 参数
### 步骤3：执行查询 — 快速参考
| 脚本 | 核心能力 | 典型入参 |
|------|---------|---------|
| `query-report.mjs` | 跨账户报表 + 属性查询 | `account_ids` + `date_range` + `tencent_ads_type` |
| `query-adgroups.mjs` | 广告/项目完整配置详情 | `account_id` + `adgroup_ids` + `tencent_ads_type` |
| `query-creatives.mjs` | 创意列表 + 单创意自动解析组件/素材预览 | `account_id` + `adgroup_ids` 或 `creative_ids` + `tencent_ads_type` |
| `query-operation-logs.mjs` | 广告/创意操作日志（新建/修改字段变更详情） | `account_id` + `operation_object_type` + `start_date` + `end_date`，可选 `object_id` |
---
## 脚本：query-report.mjs
> **这是本技能的核心脚本**，封装了报表查询的全部复杂逻辑。
### 脚本自动处理的逻辑（Agent 无需关心）
1. **标准过滤条件**：根据 `level` 自动构建基础过滤条件 + 智投/非智投区分条件（通过 `LEVEL_FILTERING_CONFIG` 配置驱动）
- 广告层级（ADGROUP 等）：`adgroup.brand_ad_type` + `adgroup.campaign_type` + `adgroup.smart_delivery_platform`
- 创意层级（DYNAMIC_CREATIVE）：`dynamic_creative.brand_ad_type` + `adgroup.campaign_type` + `dynamic_creative.smart_delivery_platform`
- 维度层级（REGION/CITY/AGE/GENDER 等）：使用对应 `report.*` 前缀
2. **模糊搜索字段自动切换**：`fuzzy_name` 在广告层级使用 `adgroup.fuzzy_name`，在创意层级使用 `dynamic_creative.fuzzy_name`
3. **group_by 推导**：根据 `level` 自动推导合适的 `group_by`（如 ADGROUP → `["adgroup_id"]`，DYNAMIC_CREATIVE → `["dynamic_creative_id"]`，REGION → `["area_id"]`）
4. **fields 补全**：未指定 `fields` 时，自动包含该 level 的默认属性字段 + 常用报表字段
5. **返回数据裁剪**：移除空对象和无效字段，减少 Agent 解析负担
6. **默认排序**：未指定 `order_by` 时，自动使用 `[{"sort_field": "report.default_order_by", "sort_type": "ASCENDING"}]`，**Agent 无需手动传 `order_by`，除非用户明确要求按某个指标排序**
### 调用方式
```bash
node scripts/query-report.mjs '<JSON 参数>'
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `account_ids` | string[] | **是** | 广告主账号 ID 数组（如 `["123"]` 或 `["123", "456"]`），单账户也用数组格式 |
| `date_range` | struct | **是** | 报表统计时间窗口 `{ "start_date": "YYYY-MM-DD", "end_date": "YYYY-MM-DD" }`。**注意：这是报表系统的统计区间，不是广告创建时间或投放时间。** 按创建时间筛选广告实体请用 `filtering` 中的 `adgroup.created_time`。 |
| `tencent_ads_type` | enum | 否 | 广告实体类型，**枚举值只允许 `"smart"` / `"standard"` / `"all"` 三者之一**，默认 `"all"`。详见步骤 1.5 |
| `level` | enum | 否 | 数据维度，默认 `"ADGROUP"`。可选：ADVERTISER / ADGROUP / DYNAMIC_CREATIVE / COMPONENT / BIDWORD / CHANNEL / REGION / CITY / AGE / GENDER / IMAGE / VIDEO / QUERYWORD / LANDING_PAGE / MARKETING_ASSET / AUDIENCE / JOINT_BUDGET_RULE / PRODUCT_CATALOG / AOI / PROJECT_CREATIVE / VIDEO_AGGREGATION / CREATIVE_ASSET / VIDEO_HIGHLIGHT / WECHAT_SHOP_PRODUCT 等 |
| `adgroup_ids` | string[] | 否 | 指定广告 ID 列表（传入后自动切为指定 ID 查询模式） |
| `creative_ids` | string[] | 否 | 指定创意 ID 列表 |
| `component_ids` | string[] | 否 | 指定组件 ID 列表 |
| `fields` | string[] | 否 | 自定义返回字段（不传则自动补全属性+报表字段） |
| `group_by` | string[] | 否 | 自定义聚合维度（不传则根据 level 自动推导） |
| `time_line` | enum | 否 | 时间口径，默认 `"REQUEST_TIME"` |
| `order_by` | struct[] | 否 | 排序条件。**通常不需要传**，脚本会自动使用默认排序。仅当用户明确要求按某个指标排序时才传，如 `[{"sort_field": "report.cost", "sort_type": "DESCENDING"}]` |
| `filtering` | struct[] | 否 | 额外自定义过滤条件（追加到标准过滤之后） |
| `post_filtering` | struct[] | 否 | 后置过滤条件（基于报表指标筛选） |
| `page` | integer | 否 | 页码，默认 1 |
| `page_size` | integer | 否 | 每页条数，默认 20 |
| `fetch_all` | boolean | 否 | 是否自动分页拉取全部数据，默认 false。开启后忽略 `page` 参数，自动翻页直到拉完所有数据（`page_size` 自动提升至至少 100 以减少请求次数）。详见下方 **`fetch_all` 使用规则** |
| `is_total` | boolean | 否 | 是否全账户汇总，默认 false |
| `report_only` | boolean | 否 | 仅查报表数据（不返回实体属性），默认 false |
| `fuzzy_name` | string | 否 | 名称模糊搜索。广告层级（ADGROUP）时搜索广告名称，创意层级（DYNAMIC_CREATIVE）时搜索创意名称 |
### 使用示例
#### 1. 查询所有广告列表（最常用，默认模式）
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"}}'
```
> 不传 `tencent_ads_type`、`fields`、`group_by` 时，脚本默认 `tencent_ads_type: "all"`（智投项目 + 竞价广告全部返回） + 默认属性与报表字段 + `group_by: ["adgroup_id"]`。
#### 2. 查询智投广告
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"tencent_ads_type":"smart"}'
```
#### 3. 查询指定广告 ID 的数据
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"adgroup_ids":["72536365535"]}'
```
> 传了 `adgroup_ids` 后，脚本自动切换到 `specified` 模式，只使用 ID 过滤，不加基础 3 条和智投/非智投条件。
#### 4. 查看指定广告的分时趋势
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"adgroup_ids":["72536365535"],"group_by":["date","hour"],"page_size":100}'
```
> 分时查询：`group_by` 使用 `["date", "hour"]`，脚本自动精简 fields 只保留报表指标。
#### 5. 查看指定广告的按天趋势
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-19","end_date":"2026-03-25"},"adgroup_ids":["72536365535"],"group_by":["date"]}'
```
#### 6. 按消耗排序
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"order_by":[{"sort_field":"report.cost","sort_type":"DESCENDING"}]}'
```
#### 7. 用后置过滤筛选高消耗广告
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"post_filtering":[{"field":"report.cost","operator":"GREATER","values":["100000"]}]}'
```
#### 8. 查询创意级别数据
查询智投项目下的创意列表：
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"level":"DYNAMIC_CREATIVE","tencent_ads_type":"smart"}'
```
查询竞价广告下的创意列表：
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"level":"DYNAMIC_CREATIVE","tencent_ads_type":"standard"}'
```
按创意名称模糊搜索（`fuzzy_name` 在创意层级自动使用 `dynamic_creative.fuzzy_name`）：
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"level":"DYNAMIC_CREATIVE","fuzzy_name":"品牌创意"}'
```
按投放模式筛选（只看组件化创意），通过 `filtering` 追加：
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"level":"DYNAMIC_CREATIVE","filtering":[{"field":"dynamic_creative.delivery_mode","operator":"EQUALS","values":["DELIVERY_MODE_COMPONENT"]}]}'
```
按创意状态筛选（竞价广告创意用 `DYNAMIC_CREATIVE_STATUS_*`，智投项目创意用 `SMART_DYNAMIC_CREATIVE_STATUS_*`）：
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"level":"DYNAMIC_CREATIVE","tencent_ads_type":"standard","filtering":[{"field":"dynamic_creative.system_status","operator":"IN","values":["DYNAMIC_CREATIVE_STATUS_PENDING","DYNAMIC_CREATIVE_STATUS_ACTIVE"]}]}'
```
按创意类型筛选（客户自建 vs 妙思自动生成）：
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"level":"DYNAMIC_CREATIVE","filtering":[{"field":"dynamic_creative.source","operator":"EQUALS","values":["AD_CREATIVE_SOURCE_NORMAL"]}]}'
```
> **创意层级自动处理说明**：
> - `operation_status` 过滤自动使用 `dynamic_creative.operation_status`（不是 `adgroup.operation_status`）
> - 智投/非智投区分自动使用 `dynamic_creative.smart_delivery_platform`（不是 `adgroup.smart_delivery_platform`）
> - `fuzzy_name` 自动使用 `dynamic_creative.fuzzy_name`（不是 `adgroup.fuzzy_name`）
#### 9. 查询账户汇总数据
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"is_total":true,"page_size":1}'
```
#### 10. 按名称模糊搜索广告
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"fuzzy_name":"品牌推广"}'
```
#### 10.5. 多账户同时查询
```bash
node scripts/query-report.mjs '{"account_ids":["39412855","73412663"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"}}'
```
> `account_id` 支持传入数组，一次请求同时查询多个账户的数据。返回结果中每条数据包含 `account_id` 字段，可区分所属账户。
#### 10.6. 自动分页拉取全部广告数据
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"fetch_all":true}'
```
> 开启 `fetch_all` 后，脚本自动翻页拉取所有数据，最终返回的 `page_info` 中 `total_number` 为全部条数，`total_page` 固定为 1。
##### `fetch_all` 使用规则
| 用户意图 | `fetch_all` 值 | 说明 |
|---------|---------------|------|
| 普通列表查询（"查看广告"、"看下效果"） | `false`（默认） | 只需要当前页数据，默认返回 20 条 |
| "拉取全部广告" / "导出所有数据" / "一共有多少条广告" | `true` | 用户明确要求全量数据 |
| "帮我统计所有广告的消耗总和" / 需要对全量数据做聚合分析 | `true` | 需要拉取全部后才能汇总计算 |
| "查看所有消耗大于 100 的广告" / 全量筛选 | `true` | 需要全量数据才能完整筛选 |
| "列出全部在投广告" / "所有正在投放的项目" | `true` | 用户要求完整列表 |
| 用户明确指定了 page / page_size | `false` | 用户自行控制分页，不需要自动拉取 |
> ⚠️ **判断关键词**：当用户使用"全部"、"所有"、"一共"、"总共"、"导出"、"拉取全量"、"完整列表"等词汇时，应设置 `fetch_all: true`。
> 当用户只是普通查询或明确指定了分页参数时，保持默认 `fetch_all: false`。
```
#### 11. 查询指定广告的分地域投放数据（受众分析-地域报表）
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"level":"REGION","adgroup_ids":["72536365535"]}'
```
> **分地域查询关键点**：当用户要求"分地域"、"按地域"、"各地区"、"省份分布"等维度查看投放数据时，**必须使用 `level: "REGION"`**，脚本会自动推导 `group_by: ["area_id"]` 和正确的过滤条件。同理，"分城市" → `level: "CITY"`，"分年龄" → `level: "AGE"`，"分性别" → `level: "GENDER"`。**切勿使用 `level: "ADGROUP"` 来查询地域/城市/年龄/性别维度的数据。**
#### 12. 按创建时间筛选广告/项目（adindex 实体过滤）
> **适用场景**：用户说"最近 N 天内创建的项目/广告"、"本周新建的广告"等——这是对**广告实体**的筛选，不是报表时间窗口。
> - `date_range` 用近期时间（如当天）即可，其值不影响广告实体的筛选
> - 创建时间用 `filtering` 中的 `adgroup.created_time`，值为 **`YYYY-MM-DD HH:mm:ss` 格式**（如 `"2026-03-18 00:00:00"`），脚本内部自动转为时间戳
查询最近一周内创建的智投项目（不关心报表数据）：
```bash
node scripts/query-report.mjs '{
"account_ids": ["39412855"],
"date_range": {"start_date": "2026-03-27", "end_date": "2026-03-27"},
"tencent_ads_type": "smart",
"filtering": [
{"field": "adgroup.created_time", "operator": "GREATER_EQUALS", "values": ["<7天前 YYYY-MM-DD 00:00:00>"]},
{"field": "adgroup.created_time", "operator": "LESS_EQUALS", "values": ["<今天 YYYY-MM-DD 23:59:59>"]}
],
"fields": [
"account_id",
"adgroup.adgroup_id",
"adgroup.adgroup_name",
"adgroup.configured_status_cn",
"adgroup.system_status_cn",
"adgroup.smart_delivery_platform",
"adgroup.project_ability_spec",
"adgroup.begin_date"
]
}'
```
> `fields` 里不含 `report.*` 字段时，`date_range` 仅作为接口必填项存在，对结果无实质影响。
#### 13. 查询创意资产（文案素材）级别数据
当用户要查文案素材（标题/描述）维度的投放效果时，使用 `CREATIVE_ASSET` 级别。注意：过滤条件使用 `report.*` 字段，不使用 `adgroup.*` 字段。
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"level":"CREATIVE_ASSET","group_by":["creative_asset_id","adgroup_id","dynamic_creative_id"],"order_by":[{"sort_field":"report.cost","sort_type":"DESCENDING"}],"fields":["creative_asset.creative_asset_id","creative_asset.creative_asset_name","creative_asset.component_id","creative_asset.component_type","creative_asset.component_value","creative_asset.component_custom_name","creative_asset.account_id","report.cost","report.view_count","report.valid_click_count","report.ctr","report.thousand_display_price","report.cpc","report.conversions_rate","report.adgroup_id","report.dynamic_creative_id"],"filtering":[{"field":"report.brand_ad_type","operator":"EQUALS","values":["BRAND_AD_TYPE_NONE"]},{"field":"report.campaign_type","operator":"EQUALS","values":["CAMPAIGN_TYPE_NORMAL"]},{"field":"report.creative_asset_sub_type","operator":"IN","values":["DESCRIPTION","TITLE"]}]}'
```
> **CREATIVE_ASSET 查询要点**：
> - `level` 设为 `"CREATIVE_ASSET"`，`group_by` 包含 `"creative_asset_id"`
> - `filtering` 使用 `report.*` 字段（如 `report.brand_ad_type`、`report.campaign_type`、`report.creative_asset_sub_type`），**不使用** `adgroup.*` 字段
> - 按素材子类型过滤文案：`report.creative_asset_sub_type` IN `["DESCRIPTION", "TITLE"]`
#### 14. 查询组件级别数据
```bash
node scripts/query-report.mjs '{"account_ids":["39412855"],"date_range":{"start_date":"2026-03-25","end_date":"2026-03-25"},"level":"COMPONENT"}'
```
### 返回结构
```json
{
"file_path": "/absolute/path/to/output/report_39412855_ADGROUP_20260325_20260325_20260325T103000.json",
"summary": {
"total_rows": 150,
"page_info": {
"page": 1,
"page_size": 20,
"total_number": 150,
"total_page": 8
},
"level": "ADGROUP",
"date_range": { "start_date": "2026-03-25", "end_date": "2026-03-25" },
"account_ids": [39412855],
"tencent_ads_type": "all"
},
"preview": [
{
"account_id": 39412855,
"adgroup": {
"adgroup_id": 123456,
"adgroup_name": "广告名称",
"configured_status": "AD_STATUS_NORMAL"
},
"report": {
"cost": 10000,
"view_count": 50000,
"valid_click_count": 1200,
"ctr": "2.40"
}
}
]
}
```
> **输出说明**：脚本会将完整查询结果写入 `output/` 目录下的 JSON 文件，stdout 只返回文件路径、摘要信息和前 3 条预览数据。模型可通过 `file_path` 读取完整数据文件，编写实时分析脚本生成数据报告。
> **数据文件格式**：`output/report_<账户ID>_<level>_<日期范围>_<时间戳>.json`，内容为 `{ "list": [...], "page_info": {...} }`。
### 常用报表字段映射（用户描述 → fields 字段名）
当用户提到以下指标时，请在 `fields` 参数中使用对应的字段名：
| 用户描述 | fields 字段名 | 说明 |
|---------|-------------|------|
| 消耗/花费 | `report.cost` | 广告消耗金额 |
| 曝光量/展示量 | `report.view_count` | 广告曝光次数 |
| 点击量 | `report.valid_click_count` | 有效点击次数 |
| 点击率/CTR | `report.ctr` | 点击率 |
| 转化数/转化量 | `report.conversions_count` | 转化次数 |
| 转化成本 | `report.conversions_cost` | 每次转化的成本 |
| 转化率 | `report.conversions_rate` | 转化率 |
| 落地页按钮点击量 | `report.lan_button_click_count` | 落地页按钮点击次数 |
| 账户余额 | `report.balance` | 账户剩余金额 |
| 出价/出价金额 | `report.cost_price` | 广告出价 |
| 营销内容 | `report.marketing_content` | 营销内容信息 |
| 地域/地区 | `report.area` | 地域名称（分地域查询时使用） |
| 千次曝光成本/CPM | `report.thousand_display_price` | 每千次曝光成本 |
| 点击均价/CPC | `report.click_cost` | 每次点击成本 |
| 深度转化数 | `report.deep_conversions_count` | 深度转化次数 |
| 深度转化成本 | `report.deep_conversions_cost` | 深度转化成本 |
| 微信加粉成本 | `report.wechat_cost_stage1` | 微信加粉阶段成本 |
| 企微加粉成本 | `report.wechat_cost_stage2` | 企微加粉阶段成本 |
> **提示**：当用户要求查看多个指标时，请将所有对应的 `report.*` 字段都加入 `fields` 数组中。如果用户没有明确指定指标，可以不传 `fields`，脚本会自动使用默认字段集。
>
> **⚠️ 强制规则**：上表仅列出最常用的 18 个字段，报表系统共有 854 个字段。**如果用户提到的指标不在上表中，必须先执行 `node scripts/query-report.mjs --query-fields "关键词"` 查询字段字典，确认准确字段名后再构造请求。禁止自行猜测或拼凑字段名。**
---
## 核心脚本
| 脚本 | 用途 |
|------|------|
| query-report.mjs | 跨账户查询广告/创意/素材的列表数据+报表指标（核心入口，融合属性查询与效果数据） |
| query-adgroups.mjs | 获取广告完整配置信息（定向、出价、转化、版位等） |
| query-creatives.mjs | 获取创意列表及组件详情；单创意时自动解析组件并获取图片/视频预览 URL |
## 请求参数
### 必填参数
| 参数名 | 类型 | 说明 | 限制 |
|--------|------|------|------|
| date_range | struct | 日期范围 | 最早支持365天内数据 |
| date_range.start_date | string | 开始日期 | YYYY-MM-DD，≤ end_date |
| date_range.end_date | string | 结束日期 | YYYY-MM-DD，≥ start_date |
| level | enum | 数据维度级别 | 见下方 level 枚举值 |
### 可选参数
| 参数名 | 类型 | 说明 | 限制/默认值 |
|--------|------|------|------------|
| account_id_list | integer[] | 广告主账号 ID 列表 | 最多 400 个，不支持代理商 ID |
| filtering | struct[] | 前置过滤条件 | 数组 1-40 个，见下方过滤条件说明 |
| or_filtering | struct[][] | 二维过滤条件（OR 逻辑） | 数组 1-40 个 |
| post_filtering | struct[] | 后置过滤条件（基于报表指标筛选） | 数组 1-32 个 |
| order_by | struct[] | 排序字段 | 最多 2 个排序条件，示例：`[{"sort_field": "report.cost", "sort_type": "DESCENDING"}]` |
| time_line | enum | 时间口径 | REQUEST_TIME / REPORTING_TIME / ACTIVE_TIME |
| group_by | string[] | 聚合参数 | 数组 1-10 个。每个 level 只支持特定的 group_by 值，见下方 **level 数据维度与 group_by 对应表** |
| page | integer | 页码 | 1-99999，默认 1 |
| page_size | integer | 每页条数 | 1-99999999，默认 10 |
| report_only | boolean | 仅查报表数据模式（true=只返回报表指标，不返回实体属性数据） | 默认 false |
| is_total | boolean | 是否为汇总数据（全账户级汇总） | 默认 false |
| fields | string[] | 指定返回的字段列表 | 数组 1-1024 个，最大长度 64 字符/项 |
| operating_scene_type | enum | 操作平台场景类型 | 枚举 OperatingSceneType |
| organization_id | integer | 业务单元 ID | 0-9999999999 |
| request_source | enum | 请求来源 | 枚举 RequestSourceType |
**level 数据维度与 group_by 对应表**：
每个 `level` 只支持特定的 `group_by` 值，不传时脚本自动使用默认值。自定义 `group_by` 时必须从该 level 的合法值中选取，**禁止使用不在此表中的值**。
| level | 说明 | 适用场景 | 合法 group_by 值 | 默认值 | group_by 说明 |
|-------|------|---------|-----------------|--------|-------------|
| ADVERTISER | 账户级别 | 当用户要求"账户级别报表"、"账户维度数据"时使用。不返回具体广告/创意明细，只返回账户粒度汇总数据 | `date`, `hour` | `["date"]` | 只支持时间维度，**不支持** `account_id`、`site_set`；按小时查用 `["date", "hour"]` |
| ADGROUP | 广告级别 | **最常用**。当用户要求"广告数据"、"广告列表"、"投放数据"时使用（未明确指定其他 level 时默认使用） | `adgroup_id`, `date`, `hour`, `site_set` | `["adgroup_id"]` | 按天趋势用 `["adgroup_id", "date"]`；按小时趋势用 `["adgroup_id", "date", "hour"]`；按版位用 `["adgroup_id", "site_set"]` |
| DYNAMIC_CREATIVE | 动态创意级别 | 当用户要求查看"创意效果"、"创意对比"、"创意列表"时使用（指普通广告的动态创意，非智投项目创意）。注意与 `PROJECT_CREATIVE` 区分 | `dynamic_creative_id`, `adgroup_id`, `date`, `hour`, `site_set` | `["dynamic_creative_id", "adgroup_id"]` | 必须包含 `dynamic_creative_id`；按小时趋势用 `["dynamic_creative_id", "date", "hour"]` |
| COMPONENT | 组件级别 | 当用户提到"素材组件"、"组件ID"、"组件效果"、"组件报表"时使用。`filtering` 可按 `component_id`、`component_sub_type` 等筛选。注意：用户说"视频素材组件"或"图片素材组件"时也应使用此 level，而非 VIDEO/IMAGE | `component_id`, `date`, `hour` | `["component_id"]` | |
| CREATIVE_ASSET | 创意资产级别 | 当用户要查询文案类素材（标题/描述）的投放效果时使用。`filtering` 使用 `report.*` 字段（非 `adgroup.*`） | `creative_asset_id`, `adgroup_id`, `dynamic_creative_id`, `date`, `product_catalog_id`, `product_series_id`, `product_outer_id` | `["creative_asset_id", "adgroup_id", "dynamic_creative_id"]` | 支持商品维度 |
| CHANNEL | 渠道级别 | 渠道包报表 | `channel_id` | `["channel_id"]` | 不支持时间维度 |
| BIDWORD | 竞价词级别 | 搜索分析-关键词报表。当用户提到"竞价词"、"关键词出价"时使用 | `bidword_id`, `date` | `["bidword_id"]` | |
| QUERYWORD | 搜索词级别 | 搜索分析-搜索词报表。当用户提到"搜索词"时使用 | `queryword_id`, `queryword`, `date` | `["queryword_id"]` | |
| IMAGE | 图片素材级别 | 当用户要求按图片 ID 查看图片素材效果时使用（素材分析-图片素材报表）。注意：若用户说的是"图片组件"或"图片素材组件"，应使用 `COMPONENT` level | `image_id`, `date` | `["image_id"]` | |
| VIDEO | 视频素材级别 | 当用户要求按视频 ID 查看视频素材效果时使用（素材分析-视频素材报表）。注意：若用户说的是"视频组件"或"视频素材组件"，应使用 `COMPONENT` level | `video_id`, `date` | `["video_id"]` | |
| MEDIA | 素材级别 | 素材报表 | `media_id`, `date` | `["media_id"]` | |
| VIDEO_AGGREGATION | 视频聚合级别 | 当用户要求按视频 MD5 聚合查看素材效果时使用 | `md5` | `["md5"]` | |
| VIDEO_HIGHLIGHT | 视频高光帧级别 | 视频高光帧分析报表 | `md5`, `play_index` | `["md5"]` | `play_index` 需要后端开关 |
| MARKETING_ASSET | 产品资产级别 | 当用户提到"推广产品"、"产品资产"、"营销资产"时使用。查看推广产品维度的投放效果 | `marketing_asset_id`, `date`, `product_catalog_id`, `product_series_id`, `product_outer_id` | `["marketing_asset_id"]` | 支持商品维度 |
| LANDING_PAGE | 落地页级别 | 当用户提到"落地页"时使用 | `landing_page_id`, `vangogh_landing_page_id`, `date` | `["landing_page_id"]` | `group_by` 用 `landing_page_id` 而非 `landing_page_url` |
| PRODUCT_CATALOG | 商品级别 | 当用户提到"商品目录"、"商品系列"、"商品ID"、"多商品广告"、"商品维度"时使用。查看商品目录/系列/单品维度的投放效果。注意与 `MARKETING_ASSET`（推广产品）区分 | `product_catalog_id`, `product_series_id`, `product_outer_id`, `date` | `["product_catalog_id"]` | 支持商品层级维度 |
| WECHAT_SHOP_PRODUCT | 微信小店商品级别 | 当用户提到"微信小店商品"、"视频号商品"、"小店商品"时使用 | `wechat_channels_product_id`, `wechat_channels_shop_id`, `date` | `["date"]` | |
| JOINT_BUDGET_RULE | 联合预算规则级别 | 联合广告预算规则 | `joint_budget_rule_id`, `date` | `["joint_budget_rule_id"]` | |
| PROJECT_CREATIVE | 智投项目创意级别 | 当用户提到"智投项目创意"、"项目创意"、"指定项目下的创意"时使用。注意与 `DYNAMIC_CREATIVE` 区分：用户提到"项目 ID + 创意"时用此 level，而非 `DYNAMIC_CREATIVE` | `dynamic_creative_id`, `adgroup_id`, `date`, `hour` | `["dynamic_creative_id", "adgroup_id"]` | |
| REGION | 省份/地域级别 | 分地域投放数据。当用户要求"分地域"、"按地域"、"各地区"、"省份分布"、"地域报表"时使用。可配合 `adgroup_ids` 查看指定广告的地域分布 | `area_id`, `adgroup_id`, `date` | `["area_id"]` | `adgroup_id` 可选 |
| CITY | 城市级别 | 分城市投放数据。当用户要求"分城市"、"按城市"、"城市报表"时使用 | `city_id`, `adgroup_id`, `date` | `["city_id"]` | `adgroup_id` 可选 |
| AGE | 年龄级别 | 分年龄投放数据。当用户要求"分年龄"、"按年龄"、"年龄报表"时使用 | `age`, `adgroup_id`, `date` | `["age"]` | `adgroup_id` 可选 |
| GENDER | 性别级别 | 分性别投放数据。当用户要求"分性别"、"按性别"、"性别报表"时使用 | `gender`, `adgroup_id`, `date` | `["gender"]` | `adgroup_id` 可选 |
| AOI | AOI 级别 | AOI 报表 | `aoi_id`, `adgroup_id`, `date` | `["aoi_id"]` | `adgroup_id` 可选 |
| AUDIENCE | 人群包级别 | 受众分析-人群包报表。当用户提到"人群包"、"受众分析"、"人群定向"时使用 | `audience_id`, `account_id`, `adgroup_id`, `dynamic_creative_id`, `date`, `hour` | `["audience_id", "account_id"]` | 支持多维度组合 |
> **关键参数组合规则（必须遵守，否则 report 会返回空对象）**:
>
> 0. **`order_by` 排序规则**：
> - **脚本已自动处理默认排序**：未传 `order_by` 时，脚本自动使用 `[{"sort_field": "report.default_order_by", "sort_type": "ASCENDING"}]`。**通常不需要手动传 `order_by`**。
> - **仅当用户明确要求排序时才传**：当用户描述中包含排序意图（如"按 XX 从高到低"、"按 XX 排序"等），按用户意图构造：
> - 格式：`[{"sort_field": "report.xxx", "sort_type": "DESCENDING"}]`
> - `sort_type` 枚举值：`DESCENDING`（降序，从高到低）、`ASCENDING`（升序，从低到高）
> - 示例：用户说"按曝光量从高到低排序" → `[{"sort_field": "report.view_count", "sort_type": "DESCENDING"}]`
> - 示例：用户说"按消耗升序" → `[{"sort_field": "report.cost", "sort_type": "ASCENDING"}]`
> - **最多支持 2 个排序条件**
>
> 1. **`group_by` 事实上必填**：虽然协议定义为可选，但不传 `group_by` 时接口几乎不会返回有效 report 数据。每个 level 的合法值和默认值见上方 **level 数据维度与 group_by 对应表**。
> - **`hour` 必须配 `date`**：使用 `hour` 时必须同时带 `date`（如 `["date", "hour"]` 或 `["adgroup_id", "date", "hour"]`），单独传 `hour` 不带 `date` 不会报错但数据不完整（不同天的同一小时会被合并）。
> - **分时/按天趋势查询**：查看指定广告的分时趋势 → `group_by: ["date", "hour"]`；查看指定广告的按天趋势 → `group_by: ["date"]`；查看广告列表的每日汇总 → `group_by: ["adgroup_id", "date"]`。
>
> 2. **`filtering` 强烈推荐**：不传过滤条件时，接口可能返回空结果或无法匹配到有效数据。
>
> **场景一：查询广告列表（无指定 adgroup_id）**— 需要完整的标准过滤（基础 3 条 + 智投/非智投条件），详见下方。
>
> **场景二：查询指定广告 ID 的数据（如分时趋势、按天趋势）**— **只需传 `adgroup.adgroup_id` 过滤即可**，不需要加基础 3 条和智投/非智投条件，因为已经精确定位到具体广告。
> ```json
> [{"field": "adgroup.adgroup_id", "operator": "EQUALS", "values": ["72536365535"]}]
> ```
>
> **场景一的标准过滤分为基础 3 条 + 第 4 条智投/非智投区分条件**：
>
⚠️ **重要：`filtering` 中的过滤字段层级必须与 `level` 匹配，不同 level 使用不同的过滤字段前缀：**
- `level` 为 `ADGROUP`、`COMPONENT` 等 → 使用 `adgroup.*` 层级过滤字段
- `level` 为 `DYNAMIC_CREATIVE` → **混合使用**：`operation_status` 和 `brand_ad_type` 使用 `dynamic_creative.*`，`campaign_type` 使用 `adgroup.*`（见下方详细说明）
- `level` 为 `CREATIVE_ASSET`（创意资产级别）→ 使用 `report.*` 层级过滤字段（如 `report.brand_ad_type`、`report.campaign_type`、`report.creative_asset_sub_type`），**不使用** `adgroup.*` 层级过滤
- `level` 为 `ADVERTISER`（账户级别报表）→ 不需要也不应该传任何实体层级的过滤条件
**基础过滤条件（仅适用于 `level` 为 `ADGROUP`/`DYNAMIC_CREATIVE`/`COMPONENT` 等实体级别时）**：
广告层级（`level=ADGROUP`）：
> ```json
> {"field": "adgroup.brand_ad_type", "operator": "EQUALS", "values": ["BRAND_AD_TYPE_NONE"]},
> {"field": "adgroup.campaign_type", "operator": "EQUALS", "values": ["CAMPAIGN_TYPE_NORMAL"]}
> ```
创意层级（`level=DYNAMIC_CREATIVE`，注意 `brand_ad_type` 前缀变为 `dynamic_creative.*`）：
> ```json
> {"field": "dynamic_creative.operation_status", "operator": "EQUALS", "values": ["CALCULATE_STATUS_EXCLUDE_DEL"]},
> {"field": "dynamic_creative.brand_ad_type", "operator": "EQUALS", "values": ["BRAND_AD_TYPE_NONE"]},
> {"field": "adgroup.campaign_type", "operator": "EQUALS", "values": ["CAMPAIGN_TYPE_NORMAL"]}
> ```
>
>
> > ⚠️ **`operation_status` 仅在查询广告列表或创意列表时添加，查询报表数据（如汇总统计、效果分析等纯报表场景）时不添加此条件。**
> > 使用 `query-report.mjs` 脚本时，以上基础过滤条件**由脚本自动构建**，无需手动传入。
>
> **`CREATIVE_ASSET` 级别的过滤条件（使用 `report.*` 字段，不使用 `adgroup.*`）**：
> ```json
> {"field": "report.brand_ad_type", "operator": "EQUALS", "values": ["BRAND_AD_TYPE_NONE"]},
> {"field": "report.campaign_type", "operator": "EQUALS", "values": ["CAMPAIGN_TYPE_NORMAL"]}
> ```
> 如需按素材子类型过滤（如只看文案描述和标题）：
> ```json
> {"field": "report.creative_asset_sub_type", "operator": "IN", "values": ["DESCRIPTION", "TITLE"]}
> ```
> > ⚠️ 注意：`CREATIVE_ASSET` 级别**不需要**也**不应该**加 `adgroup.operation_status`、`adgroup.smart_delivery_platform` 等 `adgroup.*` 过滤条件。
>
> **第 4 条：`smart_delivery_platform`（必须根据查询意图选择，同样仅适用于实体级别）**：
>
> > ⚠️ **广告层级（ADGROUP）与创意层级（DYNAMIC_CREATIVE）使用不同的字段**：
> > - `level=ADGROUP` → 使用 `adgroup.smart_delivery_platform`
> > - `level=DYNAMIC_CREATIVE` → 使用 `dynamic_creative.smart_delivery_platform`
> > - 使用 `query-report.mjs` 脚本时，脚本会根据 `level` **自动选择正确的字段**，无需手动指定。
>
> - **查智投广告/创意**（默认，当前大部分广告都是智投广告）：
> ```json
> {"field": "adgroup.smart_delivery_platform", "operator": "GREATER_EQUALS", "values": ["SMART_DELIVERY_PLATFORM_EDITION_SCENE"]}
> ```
> 或（创意层级）：
> ```json
> {"field": "dynamic_creative.smart_delivery_platform", "operator": "GREATER_EQUALS", "values": ["SMART_DELIVERY_PLATFORM_EDITION_SCENE"]}
> ```
> - **查非智投广告/创意**（用户明确要求查非智投/竞价广告时）：
> ```json
> {"field": "adgroup.smart_delivery_platform", "operator": "LESS", "values": ["SMART_DELIVERY_PLATFORM_EDITION_SCENE"]}
> ```
> 或（创意层级）：
> ```json
> {"field": "dynamic_creative.smart_delivery_platform", "operator": "LESS", "values": ["SMART_DELIVERY_PLATFORM_EDITION_SCENE"]}
> ```
> **⚠️ 智投和非智投不能在同一次请求中混合查询，每次请求只能查其中一种。**
>
> **意图判断规则**：
> - 用户说"查非智投广告"、"查常规广告"、"查老广告"、"不含智投"、"排除智投"、"竞价广告"、"只看竞价"、"不含智投项目" → 查**常规广告（非智投）**（`LESS`），只需一次请求
> - 用户说"查智投广告"、"智投项目"、"智投报表" → 查**智投广告**（`GREATER_EQUALS`），只需一次请求
> - 用户说"两种都看"、"智投和非智投都要" → 先查**智投广告**（`GREATER_EQUALS`），再查**常规广告（非智投）**（`LESS`），共两次请求（顺序发，不要并行）
> - **⚠️ 如果意图不确定（用户未明确指定智投或非智投），应发两次请求：先智投 `GREATER_EQUALS`，再非智投 `LESS`，以保证最终数据的准确性和完整性**
>
> 3. **`fields` 必须包含所需字段**：
> - **查询广告列表时**：`fields` 必须同时包含属性字段（如 `adgroup.adgroup_id`、`adgroup.adgroup_name`）和报表字段（如 `report.cost`），否则 report 会返回空对象。
> - **查询指定广告的分时/按天趋势时**：`fields` **只需包含用户关心的报表指标即可**（如 `["report.view_count", "report.view_user_count"]`），不需要额外加 `adgroup.*` 属性字段和 `account_id`，因为已经通过 filtering 精确定位到了具体广告。
> - **实体级别查询**（`level` 为 `ADGROUP`、`DYNAMIC_CREATIVE`、`COMPONENT` 等）：必须**同时包含属性字段和报表字段**，仅请求 `report.*` 字段而不请求对应的属性字段（如 `adgroup.adgroup_id`）会导致 report 返回空。应**同时请求** `adgroup.*` 和 `report.*` 字段。
> - **账户级别查询**（`level` 为 `ADVERTISER`）：查询的是账户维度汇总报表，**只需传用户关心的 `report.*` 报表字段即可，不需要也不应该传 `account_id`、`adgroup.*` 等属性字段**，否则会导致参数冗余。
> - ✅ 正确：`"fields": ["report.view_count", "report.cost"]`
> - ❌ 错误：`"fields": ["account_id", "report.view_count", "report.cost"]`
>
> 4. **`is_total` 的正确用法**：
> - `is_total: false`（默认）= 返回**逐条明细数据**（每个广告/创意一行），**这是最常用的模式**
> - `is_total: true` = 返回**全账户汇总**（所有广告合并为一条），此时仍需传 `group_by`、`filtering` 和 `fields`（包含属性+报表字段）
> - **查询广告列表时请使用 `is_total: false`**
>
> 5. **`date_range` vs `adgroup.created_time`：两套独立系统，含义完全不同**
>
> 本接口底层由两个独立系统协同工作：
> - **报表系统**：负责 `report.*` 字段的统计数据，由 `date_range` 控制统计区间
> - **adindex（广告实体索引）**：负责返回哪些广告/创意实体，由 `filtering` 中的 `adgroup.created_time` 等条件控制
>
> | 用途 | 参数 | 示例 |
> |------|------|------|
> | 控制报表指标的统计时间窗口 | `date_range` | `{"start_date":"2026-03-01","end_date":"2026-03-27"}` |
> | 筛选某段时间内**创建**的广告/项目 | `filtering` 中 `adgroup.created_time` | `{"field":"adgroup.created_time","operator":"GREATER_EQUALS","values":["2026-03-20 00:00:00"]}` |
>
> **⚠️ 关键区别**：
> - `date_range` **不是**广告的创建时间，也不是投放时间，是**报表统计窗口**
> - 如果某广告在 `date_range` 范围内没有消耗/曝光，`report.*` 字段会返回空，但广告实体本身仍然存在
> - 只查广告/项目实体信息（不关心消耗数据）时，`date_range` 设为任意有效时间段即可（通常用近期时间）
>
> **意图判断规则（模型必须遵守）**：
>
> | 用户说的 | 正确做法 |
> |---------|---------|
> | "最近一周的消耗数据" / "最近7天的报表" | `date_range` = 最近7天，不加 `created_time` 过滤 |
> | "最近一周内创建的广告/项目" | `date_range` = 当天（或近期），`filtering` 加 `adgroup.created_time` >= 7天前的时间戳 |
> | **"最近一周的广告/项目/创意"（无效果指标词）** | **同"创建"处理：`date_range` = 当天，`filtering` 加 `adgroup.created_time` 范围，走路径 B** |
> | "最近一周内创建且有投放数据的广告" | `date_range` = 最近7天，`filtering` 同时加 `adgroup.created_time` 范围 |
> | "查看某个项目的历史数据" | `date_range` = 目标历史时间段，`filtering` 加 `adgroup.adgroup_id` |
>
> **`created_time` 时间格式**：值为 `YYYY-MM-DD HH:mm:ss` 格式字符串（如 `"2026-03-21 00:00:00"`），脚本内部自动转为 API 所需的 Unix 时间戳。
> ```json
> // 示例：筛选 2026-03-21 00:00:00 ~ 2026-03-27 23:59:59 创建的项目
> {"field": "adgroup.created_time", "operator": "GREATER_EQUALS", "values": ["2026-03-21 00:00:00"]},
> {"field": "adgroup.created_time", "operator": "LESS_EQUALS", "values": ["2026-03-27 23:59:59"]}
> ```
>
> 6. **`report_only` 默认不要传**：`report_only: true` 表示仅查报表指标数据、不返回实体属性（广告名称、状态等）。只有在用户明确只需要效果数据（如"今天总消耗多少"）而不关心广告属性时才设为 `true`。**大多数查询都需要同时看到广告属性和报表数据，因此默认不传或设为 `false`。**
### time_line 时间口径枚举值
| 值 | 说明 |
|----|------|
| REQUEST_TIME | 广告播放口径（默认） |
| REPORTING_TIME | 转化回传口径 |
| ACTIVE_TIME | 激活时间口径 |
## 过滤条件（filtering）
### filtering 结构
```json
{
"field": "过滤字段",
"operator": "操作符",
"values": ["值1", "值2"]
}
```
### 常用过滤字段
#### 广告层级（adgroup.*）
| 字段 | 说明 | 支持的操作符 |
|------|------|-------------|
| adgroup.adgroup_id | 广告 ID | EQUALS, IN |
| adgroup.fuzzy_name | 广告名称模糊搜索 | EQUALS |
| adgroup.operation_status | 运营状态 | EQUALS, IN |
| adgroup.system_status | 系统状态 | EQUALS, IN |
| adgroup.configured_status | 配置状态 | EQUALS, IN |
| adgroup.site_set | 版位 | EQUALS, IN, HAS_ANY |
| adgroup.created_time | 创建时间 | LESS, LESS_EQUALS, GREATER, GREATER_EQUALS |
| adgroup.campaign_type | 推广类型 | EQUALS |
| adgroup.brand_ad_type | 品牌广告类型 | EQUALS |
| adgroup.smart_delivery_platform | 智投平台版本 | EQUALS, IN, LESS, GREATER_EQUALS |
| adgroup.begin_date | 开始日期 | 时间戳操作符 |
| adgroup.end_date | 结束日期 | 时间戳操作符 |
| adgroup.optimization_goal | 优化目标 | - |
| adgroup.deep_optimization_goal | 深度优化目标 | - |
#### 动态创意层级（dynamic_creative.*）
| 字段 | 说明 | 支持的操作符 |
|------|------|-------------|
| dynamic_creative.dynamic_creative_id | 创意 ID | EQUALS, IN |
| dynamic_creative.fuzzy_name | 创意名称模糊搜索 | EQUALS |
| dynamic_creative.adgroup_id | 所属广告 ID | EQUALS, IN |
| dynamic_creative.operation_status | 运营状态（用于创意列表过滤，值同 adgroup.operation_status） | EQUALS, IN |
| dynamic_creative.system_status | 系统状态（见下方枚举值说明） | EQUALS, IN |
| dynamic_creative.delivery_mode | 投放模式：`DELIVERY_MODE_COMPONENT`（组件化创意）/`DELIVERY_MODE_CUSTOM`（自定义创意） | EQUALS, IN |
| dynamic_creative.source | 创意类型来源：`AD_CREATIVE_SOURCE_NORMAL`（客户自建创意）/`AD_CREATIVE_SOURCE_AUTO`（妙思自动生成） | EQUALS, IN |
| dynamic_creative.smart_delivery_platform | 智投平台版本（创意层级的智投/非智投区分，值同 adgroup.smart_delivery_platform） | EQUALS, IN, LESS, GREATER_EQUALS |
| dynamic_creative.created_time | 创建时间（Unix 时间戳） | LESS, LESS_EQUALS, GREATER, GREATER_EQUALS |
| dynamic_creative.brand_ad_type | 品牌广告类型 | EQUALS |
**`dynamic_creative.system_status` 枚举值说明**：
> 竞价广告（非智投）下的创意与智投项目下的创意，system_status 枚举值不同：
| 枚举值 | 适用场景 | 说明 |
|--------|---------|------|
| `DYNAMIC_CREATIVE_STATUS_PENDING` | 竞价广告创意 | 审核中 |
| `DYNAMIC_CREATIVE_STATUS_ACTIVE` | 竞价广告创意 | 投放中 |
| `DYNAMIC_CREATIVE_STATUS_SUSPEND` | 竞价广告创意 | 暂停 |
| `DYNAMIC_CREATIVE_STATUS_AUDIT_FAILED` | 竞价广告创意 | 审核不通过 |
| `DYNAMIC_CREATIVE_STATUS_DELETED` | 竞价广告创意 | 已删除 |
| `SMART_DYNAMIC_CREATIVE_STATUS_USING` | 智投项目创意 | 启用中 |
| `SMART_DYNAMIC_CREATIVE_STATUS_SUSPEND` | 智投项目创意 | 已暂停 |
| `SMART_DYNAMIC_CREATIVE_STATUS_DELETED` | 智投项目创意 | 已删除 |
#### 组件层级（component.*）
| 字段 | 说明 | 支持的操作符 |
|------|------|-------------|
| component.component_id | 组件 ID | EQUALS, IN, NOT_IN |
| component.component_type | 组件类型 | EQUALS, IN |
| component.fuzzy_name | 组件名称模糊搜索 | EQUALS |
| component.component_sub_type | 组件子类型 | EQUALS, IN |
| component.approval_status | 审核状态 | EQUALS, IN |
| component.operation_status | 运营状态 | EQUALS, IN |
| component.created_time | 创建时间（`YYYY-MM-DD HH:mm:ss` 格式，脚本自动转时间戳） | 时间操作符 |
| component.generation_type | 生成类型 | EQUALS, IN |
| component.quality_status | 质量状态 | EQUALS, IN |
| component.potential_status | 潜力状态 | EQUALS, IN |
| component.shared_account_id | 共享账户 ID | EQUALS, IN |
| component.scene | 场景 | EQUALS, IN |
#### 报表层级（report.*）
| 字段 | 说明 | 支持的操作符 |
|------|------|-------------|
| report.adgroup_id | 广告 ID | EQUALS, IN |
| report.dynamic_creative_id | 创意 ID | EQUALS, IN |
| report.component_id | 组件 ID | EQUALS, IN |
| report.component_type | 组件类型 | EQUALS, IN |
| report.image_id | 图片 ID | EQUALS, IN |
| report.video_id | 视频 ID | EQUALS, IN |
| report.marketing_asset_id | 产品 ID | EQUALS, IN |
| report.marketing_target_type | 营销目标类型 | EQUALS, IN |
| report.audience_id | 人群 ID | EQUALS, IN |
| report.landing_page_id | 落地页 ID | EQUALS, IN |
| report.brand_ad_type | 品牌广告类型 | EQUALS |
| report.campaign_type | 推广类型 | - |
| report.smart_delivery_platform | 智投平台版本 | EQUALS, IN, LESS, GREATER_EQUALS |
| report.creative_asset_id | 创意资产 ID | EQUALS, IN |
#### 素材层级
| 字段 | 说明 | 支持的操作符 |
|------|------|-------------|
| image.image_id | 图片 ID | EQUALS, IN |
| image.label_name | 图片标签 | EQUALS |
| video.video_id | 视频 ID | EQUALS, IN |
| video.label_name | 视频标签 | EQUALS |
#### 产品层级（marketing_asset.*）
| 字段 | 说明 | 支持的操作符 |
|------|------|-------------|
| marketing_asset.marketing_asset_id | 产品 ID | EQUALS, IN |
| marketing_asset.marketing_target_type | 营销目标类型 | EQUALS, IN |
| marketing_asset.fuzzy_name | 产品名称模糊搜索 | EQUALS |
### 后置过滤条件（post_filtering）
用于基于报表指标数值进行筛选，在数据返回后过滤。
支持的过滤字段：
- `report.cost` - 消耗
- `report.view_count` - 展示量
- `report.valid_click_count` - 有效点击量
- `report.conversions_count` - 转化数
- `report.conversions_cost` - 转化成本
- `report.conversions_rate` - 转化率
### 操作符说明
| 操作符 | 说明 |
|--------|------|
| EQUALS | 等于（单值匹配） |
| IN | 在列表中（多值匹配） |
| NOT_IN | 不在列表中 |
| LESS | 小于 |
| LESS_EQUALS | 小于等于 |
| GREATER | 大于 |
| GREATER_EQUALS | 大于等于 |
| CONTAINS | 包含 |
| HAS_ANY | 数组包含任意值 |
## 响应结构
```json
{
"data": {
"list": [
{
"account_id": 39412855,
"account": { ... },
"adgroup": {
"adgroup_id": 123456,
"adgroup_name": "广告名称",
"configured_status": "AD_STATUS_NORMAL",
"system_status": "ADGROUP_STATUS_NORMAL",
...
},
"dynamic_creative": { ... },
"component": { ... },
"bidword": { ... },
"report": {
"cost": 10000,
"view_count": 50000,
"valid_click_count": 1200,
"ctr": "2.40",
"conversions_count": 100,
"conversions_cost": 10000,
...
},
"image": { ... },
"media": { ... },
"video": { ... },
"marketing_asset": { ... },
"joint_budget_rule": { ... },
"product_catalog": { ... },
"project_creative": { ... },
"video_aggregation": { ... },
"creative_asset": { ... },
"jump_info": { ... }
}
],
"page_info": {
"page": 1,
"page_size": 20,
"total_number": 150,
"total_page": 8
},
"update_time": "2025-11-29 10:30:00"
}
}
```
### list 每项返回结构
| 字段 | 类型 | 说明 |
|------|------|------|
| account_id | integer | 广告主帐号 ID |
| account | struct | 账户信息 |
| adgroup | struct | 广告属性（google_struct 动态字段） |
| dynamic_creative | struct | 动态创意属性 |
| component | struct | 组件属性 |
| bidword | struct | 竞价词属性 |
| report | struct | **报表指标数据**（google_struct 动态字段） |
| image | struct | 图片素材信息 |
| media | struct | 媒体信息 |
| video | struct | 视频素材信息 |
| marketing_asset | struct | 产品资产信息 |
| joint_budget_rule | struct | 联合预算规则信息 |
| product_catalog | struct | 商品信息 |
| project_creative | struct | 项目创意信息 |
| video_aggregation | struct | 视频聚合信息 |
| creative_asset | struct | 创意资产信息 |
| jump_info | struct | 跳转信息 |
## 常用 fields 字段
### 广告属性字段（adgroup.*）
| 字段 | 说明 |
|------|------|
| adgroup.adgroup_id | 广告 ID |
| adgroup.adgroup_name | 广告名称 |
| adgroup.is_deleted | 是否已删除 |
| adgroup.status | 广告状态 |
| adgroup.status_cn | 广告状态中文 |
| adgroup.configured_status | 配置状态（开/关） |
| adgroup.adgroup_status | 广告投放状态 |
| adgroup.system_status | 系统状态 |
| adgroup.system_status_cn | 系统状态中文 |
| adgroup.system_status_tips | 系统状态提示 |
| adgroup.optimization_goal | 优化目标 |
| adgroup.optimization_goal_cn | 优化目标中文 |
| adgroup.marketing_goal | 营销目的 |
| adgroup.marketing_goal_cn | 营销目的中文 |
| adgroup.marketing_target_type | 营销目标类型 |
| adgroup.marketing_target_type_cn | 营销目标类型中文 |
| adgroup.marketing_carrier_type | 营销载体类型 |
| adgroup.marketing_carrier_type_cn | 营销载体类型中文 |
| adgroup.promoted_object_type | 推广目标类型 |
| adgroup.promoted_object_type_cn | 推广目标类型中文 |
| adgroup.total_budget | 总预算 |
| adgroup.daily_budget | 日预算 |
| adgroup.bid_amount | 出价金额 |
| adgroup.bid_mode | 竞价模式 |
| adgroup.bid_scene | 竞价场景 |
| adgroup.billing_event | 计费事件 |
| adgroup.buying_type | 购买类型 |
| adgroup.begin_date | 开始日期 |
| adgroup.end_date | 结束日期 |
| adgroup.site_set | 版位 |
| adgroup.site_set_cn | 版位中文 |
| adgroup.smart_delivery_platform | 智投平台版本 |
| adgroup.smart_delivery_scene | 智投场景 |
| adgroup.smart_bid_type | 出价方式 |
| adgroup.smart_bid_type_cn | 出价方式中文 |
| adgroup.targeting_translation | 定向翻译 |
| adgroup.time_series | 投放时段 |
| adgroup.deep_conversion_spec | 深度转化规格 |
| adgroup.joint_budget_rule_id | 联合预算规则 ID |
| adgroup.marketing_asset_id | 营销资产 ID |
| adgroup.flow_lock_status | 锁量状态 |
| adgroup.exploration_strategy | 自动版位探索策略 |
| adgroup.automatic_site_enabled | 自动版位是否开启 |
| adgroup.dynamic_creative_id | 动态创意 ID |
| adgroup.placement_group_id | 版位组 ID |
| adgroup.display_id | 展示 ID |
| adgroup.adgroup_operation | 广告操作信息 |
| adgroup.ad_count | 广告数量 |
| adgroup.date_set | 日期设置 |
| adgroup.negative_word_cnt | 否定词数量 |
| adgroup.dynamic_ad_type | 动态广告类型 |
| adgroup.dynamic_ad_type_text | 动态广告类型文本 |
| adgroup.dynamic_creative_status_info | 动态创意状态信息 |
| adgroup.adcreative_preview_list | 创意预览列表 |
| adgroup.created_by_industry_platform | 行业平台创建标识 |
| adgroup.ad_created_source | 广告创建来源 |
| adgroup.search_intelligent_extension | 搜索智能拓展 |
| adgroup.live_video_mode | 直播视频模式 |
| adgroup.live_video_sub_mode | 直播视频子模式 |
### 报表指标字段（report.*）
> **完整字段列表见下方「字段字典参考 → 报表指标字典」**，此处仅列举最常用的字段：
**基础效果指标：**
| 字段 | 说明 |
|------|------|
| report.cost | 消耗（分） |
| report.view_count | 曝光量/展示量 |
| report.valid_click_count | 点击量/有效点击量 |
| report.ctr | 点击率（%） |
### 其他常用字段
| 字段 | 说明 |
|------|------|
| account_id | 广告主帐号 ID |
## 通用参数说明
以下公共约定由构建阶段自动内联：
以下内容为腾讯广告营销 API（`api.e.qq.com`）各 skill 共享的公共约定，会在构建阶段自动内联到目标 skill 文档中。各 skill 不需要重复这些内容。
## 基础信息
- **Base URL**: `https://api.e.qq.com`
- **认证方式**: API Key 鉴权（api.e.qq.com），授权请使用 `tencentads auth login`，状态查看使用 `tencentads auth status`
- **权限要求**: 需登录api.e.qq.com 并具有对应账户操作权限
- **时区**: GMT+8（北京时间）
- **金额单位**: 分（不是元），示例：`10000` 分 = `100` 元人民币
- **时间戳**: API 底层为秒级 Unix timestamp，但脚本统一使用 `YYYY-MM-DD HH:mm:ss` 格式（如 `"2026-03-18 00:00:00"`），脚本内部自动完成格式转换
## 调用方式
所有接口均通过 `tencent-ads` CLI 工具调用（agent 通过 bash 执行）。API Key 鉴权由 CLI 自动处理（通过 X-MKT-API-Key header），无需手动传入。
### GET 请求
```bash
tencentads-cli api '{
"method": "GET",
"path": "/v3.0/xxx/get",
"account_id": "YOUR_ACCOUNT_ID",
"params": {"page": 1, "page_size": 10}
}'
```
### POST 请求
```bash
tencentads-cli api '{
"method": "POST",
"path": "/v3.0/xxx/add",
"account_id": "YOUR_ACCOUNT_ID",
"body": {"account_id": 12345, "field1": "value1"}
}'
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| method | string | 否 | GET 或 POST（默认 GET） |
| path | string | **是** | API 路径 |
| account_id | string | **是** | 广告账户 ID |
| params | object | 否 | GET 查询参数（JSON 对象） |
| body | object | 否 | POST 请求体（JSON 对象） |
> **严格规则**：调用任何接口时，**必须严格使用该接口文档中声明的 HTTP 方法（GET / POST）**，不得擅自更改。使用错误的请求方法会导致服务端返回 `405 Method Not Allowed`。
## 通用响应格式
所有接口返回的 JSON 响应都遵循以下格式：
```json
{
"code": 0,
"message": "",
"message_cn": "",
"data": {
// 接口特定的响应数据
}
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| code | integer | 响应码，0 表示成功，非 0 表示错误 |
| message | string | 英文错误消息（成功时为空） |
| message_cn | string | 中文错误消息（成功时为空） |
| data | object | 响应数据对象 |
## 错误处理
`tencentads-cli api` 返回的 JSON 响应中包含 `code` 字段：
- `code` 为 0 表示成功
- `code` 非 0 时，检查 `message_cn` 获取中文错误说明
### 常见错误码
| 错误码 | 说明 | 处理方式 |
|--------|------|----------|
| 0 | 成功 | - |
| 3 | 参数错误 | 检查请求参数格式和必填项 |
| 5 | 权限不足 | 确认 API Key 有效且具有相应权限 |
| 6 | 系统错误 | 重试或联系技术支持 |
| 1001 | `timestamp` 超时 | 确保请求时间戳在当前时间 ±300 秒内 |
| 1002 | `nonce` 重复 | 使用新的随机字符串 |
## 数值单位说明
### 金额单位
- 所有涉及金额的字段（出价、预算等）单位均为**分**（不是元）
- 示例：`10000` 分 = `100` 元人民币
- 日预算范围：5000-400000000 分（50 元-400 万元）
### 时间单位
- 时间字段（`created_time`、`last_modified_time`、`completed_time`）：统一使用 `YYYY-MM-DD HH:mm:ss` 格式（如 `"2026-03-18 00:00:00"`），脚本内部自动与 API 的 Unix 时间戳互转
- 日期格式：`YYYY-MM-DD`
- 时间格式：`HH:ii:ss`
- 时区：`GMT+8`（北京时间）
## 分页参数
大多数列表查询接口支持以下分页参数：
### 标准分页
| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| page | integer | 1 | 页码（1-100） |
| page_size | integer | 10 | 每页数量（1-100） |
### 游标分页
| 参数名 | 类型 | 说明 |
|--------|------|------|
| pagination_mode | enum | 分页方式：`PAGINATION_MODE_NORMAL`（标准）/ `PAGINATION_MODE_CURSOR`（游标） |
| cursor | string | 游标值，有效期 24 小时 |
### 分页响应
```json
{
"page_info": {
"page": 1,
"page_size": 10,
"total_number": 100,
"total_page": 10
}
}
```
## 过滤参数
大多数查询接口支持 `filtering` 参数进行条件过滤：
### filtering 结构
```json
{
"filtering": [
{
"field": "字段名",
"operator": "操作符",
"values": ["值1", "值2"]
}
]
}
```
### 操作符说明
| 操作符 | 说明 | 示例 |
|--------|------|------|
| EQUALS | 等于 | `{"field": "status", "operator": "EQUALS", "values": ["NORMAL"]}` |
| CONTAINS | 模糊匹配 | `{"field": "name", "operator": "CONTAINS", "values": ["测试"]}` |
| LESS | 小于 | `{"field": "created_time", "operator": "LESS", "values": ["2026-04-01 00:00:00"]}` |
| LESS_EQUALS | 小于等于 | `{"field": "created_time", "operator": "LESS_EQUALS", "values": ["2026-04-01 23:59:59"]}` |
| GREATER | 大于 | `{"field": "created_time", "operator": "GREATER", "values": ["2026-03-01 00:00:00"]}` |
| GREATER_EQUALS | 大于等于 | `{"field": "created_time", "operator": "GREATER_EQUALS", "values": ["2026-03-01 00:00:00"]}` |
| IN | IN 操作符 | `{"field": "id", "operator": "IN", "values": ["1", "2", "3"]}` |
## 最佳实践
1. **请求方法**：严格按照各接口文档声明的 HTTP 方法（GET/POST）发起请求，不得混用
2. **错误处理**：始终检查响应中的 `code` 字段
3. **重试机制**：对于系统错误（`code = 6`），可以实施指数退避重试
4. **API Key 如失效需重新配置
5. **分页处理**：对于大数据量查询，使用游标分页性能更好
6. **字段筛选**：使用 `fields` 参数只请求需要的字段，减少数据传输
## 字段字典参考
以下字典由构建阶段自动内联，包含所有可用字段的完整定义。
> **🚫 强制规则：遇到不在常用映射表中的字段名时，必须先查字典，禁止猜测！**
>
> 用户描述中提到的字段名称往往与 API 实际字段名差异很大，例如：
> - "AIGC 创意" → `smart_delivery_aigc_option`（而非 `aigc_creative`）
> - "锁量" → `flow_lock_status`（而非 `lock_status`）
> - "关注数" → `scan_follow_user_count`（而非 `wechat_official_account_follower_count`）
> - "5秒播放数" → 需查字典确认（而非 `video_play_5s_count`）
>
> 本文档不可能穷举所有字段，但 `adgroup-fields.json`（236 个字段）和 `report-fields.json`（854 个字段）中有完整的字段定义。
>
> **强制做法**：当用户提到的字段**不在上方「常用报表字段映射」或「常用 fields 字段」表中**时，**必须先用 `--query-fields` 查询字段字典**，确认正确字段名后再构造请求。**绝对禁止根据英文命名规律自行拼凑字段名。**
>
> 示例：用户说"帮我查询最近一周开启 AIGC 的广告"
> 1. 先查字典：`node scripts/query-adgroups.mjs --query-fields "aigc"`
> 2. 得到匹配字段（如 `smart_delivery_aigc_option`、`smart_delivery_aigc_creative` 等）
> 3. 再用正确的字段名构造查询请求的 `fields` 或 `filtering` 参数
>
> 示例：用户说"查看5秒播放数、关注数、关注成本"
> 1. 这些指标不在常用映射表中 → **必须查字典**
> 2. 执行：`node scripts/query-report.mjs --query-fields "5秒播放,关注"`
> 3. 从返回结果中确认准确字段名，再构造 `fields` 参数
### 广告字段字典（adgroup.*）
广告字段定义存储在 `resources/adgroup-fields.json` 中（共 236 个字段，按分类组织：定向设置、广告基本信息、营销配置、投放时间与预算、出价与优化、深度优化、一键起量、版位与场景定向、创意相关、转化与数据源、搜索定向、动态广告、其他、智投项目专有、报表广告维度属性、分页）。
**查询方式**：通过 `query-adgroups.mjs --query-fields [关键词]` 获取字段定义。
| 用法 | 说明 |
|------|------|
| `query-adgroups.mjs --query-fields` | 返回全部广告字段（字段名、类型、中文名、分类、说明） |
| `query-adgroups.mjs --query-fields "定向"` | 按分类/中文名过滤，返回定向相关字段 |
| `query-adgroups.mjs --query-fields "bid"` | 按字段名过滤，返回包含 bid 的字段 |
| `query-adgroups.mjs --query-fields "出价,预算,定向"` | 多关键词批量查询，逗号分隔，匹配任意一个即返回 |
**自动中文名附加**：`query-adgroups.mjs` 查询广告数据时，返回的每个字段自动附加中文名（如 `adgroup_name: "xxx"` 旁会有 `广告名称: "xxx"`），无需手动翻译。
### 报表指标字典（report.*）
报表指标字段定义存储在 `resources/report-fields.json` 中（共 854 个字段，按分类组织）。
**查询方式**：通过 `query-report.mjs --query-fields [关键词]` 获取字段定义。
| 用法 | 说明 |
|------|------|
| `query-report.mjs --query-fields` | 返回全部报表指标字段（字段名、类型、中文名、分类、说明） |
| `query-report.mjs --query-fields "视频"` | 按分类/中文名过滤，返回视频相关字段 |
| `query-report.mjs --query-fields "cost"` | 按字段名过滤，返回包含 cost 的字段 |
| `query-report.mjs --query-fields "cost,click,impression"` | 多关键词批量查询，逗号分隔，匹配任意一个即返回 |
> **⚠️ 强制使用场景**：只要用户提到的报表指标**不在「常用报表字段映射」表中**，就**必须**先用 `--query-fields` 查询字段字典，确认正确的 `report.*` 字段名后再构造查询请求。这是强制步骤，不可跳过。
## 分页信息
| 字段名 | 类型 | 中文名称 | 说明 |
|--------|------|----------|------|
| page_info | struct | 分页配置信息 | |
| page | integer | 搜索页码 | 默认值：1 |
| page_size | integer | 一页显示的数据条数 | 默认值：10 |
| total_number | integer | 总条数 | |
| total_page | integer | 总页数 | |
## 注意事项
1. **请求方式**: 该接口使用 **POST** 方法，参数放在请求体中（非 URL 参数）。
2. **fields 字段格式**: fields 中的字段使用 `对象.属性` 的格式，如 `adgroup.adgroup_id`、`report.cost`。顶层的 `account_id` 不带前缀。
- **查询广告列表时**：fields 必须同时包含属性字段（如 `adgroup.*`）和报表字段（`report.*`），否则 report 会返回空对象。
- **查询指定广告的分时/按天趋势时**：fields 只需包含用户关心的 `report.*` 指标即可。
3. **金额单位**: 所有金额字段单位为**分**。
- 示例：`report.cost = 10000` 表示消耗 100 元
- `adgroup.total_budget = 100000` 表示预算 1000 元
4. **日期范围**: 最早支持查询近 365 天的数据。`start_date` ≤ `end_date`，格式 `YYYY-MM-DD`。当天和昨天的日期均可使用。
5. **分页**: 支持大页面（page_size 最大 99999999），但建议按需设置合理的分页大小。数据量大时注意响应时间。
6. **report_only（慎用）**: 设为 `true` 时表示**仅查报表指标数据，不返回实体属性数据**（广告名称、状态、预算、出价等业务字段都不会返回）。适用场景：用户只需要效果数据（消耗、点击、转化等）而不关心广告属性信息，如纯数据汇总统计。**查询广告列表时应使用默认值 `false`（或不传此参数）**，以同时获取广告属性和报表数据。
> 7. **`group_by`（关键）**: 聚合参数决定了数据的汇总维度。**不传 group_by 会导致 report 返回空对象**。每个 level 的合法值和默认值见 **level 数据维度与 group_by 对应表**。
8. **二维过滤（or_filtering）**: 支持 OR 逻辑组合过滤。外层数组为 OR 关系，内层 `and_filtering` 数组为 AND 关系。
9. **常见的返回空数据原因排查**:
- **`list` 返回空数组（`total_number: 0`）**：
- **缺少 `smart_delivery_platform` 过滤或方向错误**（最常见原因）→ 智投和非智投必须分开查。**默认应用 `LESS`（查常规广告/非智投）。** 若用户明确要求查智投，用 `GREATER_EQUALS`。
- 使用了 `report_only: true` 导致不返回实体属性数据 → **去掉 `report_only` 或设为 `false`**
- `filtering` 其他条件过于严格 → 先用基础 3 条 + 智投/非智投过滤查询
- **`report` 返回空对象（`report: {}`）**：
- 缺少 `group_by` 参数 → 加上 `"group_by": ["adgroup_id"]`（列表查询）或 `["date", "hour"]`（分时查询）
- 查询广告列表时缺少 `filtering` 参数 → 至少加上基础 3 条过滤 + 智投/非智投条件
- 查询广告列表时 `fields` 只有 `report.*` 没有 `adgroup.*` → 补充属性字段
- **以上各项需同时正确才能返回有效数据**
10. **🚫 禁止重复调用（极其重要）**：
- **脚本调用成功返回了 `list` 数据（即使所有指标值为 0），说明参数正确、接口正常，应直接使用返回数据向用户展示，绝不要因为数据值全为 0 而反复修改参数重试。**
- 数据值为 0 是正常的业务情况（如该日期没有投放、没有消耗等），不代表参数有误。
- **区分"接口报错"和"数据为零"**：
- 接口报错（返回 `error` 字段、HTTP 错误等）→ 检查参数后可重试 **1 次**
- `list` 返回空数组（`total_number: 0`）→ 可按第 9 条排查后重试 **1 次**
- `list` 有数据但 `report` 中的值为 0 → **这是正常结果，直接使用，禁止重试**
- **严禁以下行为**：反复调整 `group_by`、`level`、`fields`、`is_total` 等参数尝试"修复"数据；绕过脚本直接调用底层 API；查看脚本源码试图排查问题。这些行为浪费大量步骤且不会改变结果。
---
## 脚本：query-adgroups.mjs
> **广告详情查询脚本**，用于获取广告的完整配置信息。
### 适用场景
- 需要查看广告的**详细配置**（定向、出价、转化规格、版位、投放时段等），而不仅是基本属性和报表数据
- 需要查看**已删除的广告**信息
- 需要根据**广告名称、状态、创建时间**等条件筛选广告
- 需要获取广告的**定向设置详情**（地域、年龄、性别、设备等）
- 需要查看广告的**深度转化规格**、**用户行为数据源**等高级配置
### 与 query-report.mjs 的区别
| 对比项 | query-report.mjs | query-adgroups.mjs |
|--------|-----------------|-------------------|
| 返回报表数据 | ✅ 返回消耗、曝光、点击等报表指标 | ❌ 不返回报表数据 |
| 返回配置详情 | ⚠️ 仅返回基本属性 | ✅ 返回完整配置（定向、出价、转化、版位等） |
| 需要日期范围 | ✅ 必填 | ❌ 不需要 |
| 支持跨账户 | ✅ 支持 | ❌ 单账户 |
| 查看已删除广告 | ❌ 不支持 | ✅ 支持 |
| 支持游标分页 | ❌ | ✅ 支持 |
### 调用方式
```bash
node scripts/query-adgroups.mjs '<JSON 参数>'
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `account_id` | string | **是** | 广告主账号 ID |
| `tencent_ads_type` | enum | 否 | 广告实体类型，**枚举值只允许 `"smart"` / `"standard"` / `"all"` 三者之一**，默认 `"all"`。详见步骤 1.5 |
| `adgroup_ids` | string[] | 否 | 指定广告 ID 列表（按 ID 精确查询） |
| `fields` | string[] | 否 | 自定义返回字段（不传则使用默认字段集） |
| `filtering` | struct[] | 否 | 过滤条件数组 |
| `page` | integer | 否 | 页码，默认 1（最大 100） |
| `page_size` | integer | 否 | 每页条数，默认 10（最大 100） |
| `is_deleted` | boolean | 否 | 是否查询已删除广告，默认 false |
| `pagination_mode` | enum | 否 | 分页方式：`PAGINATION_MODE_NORMAL`（默认）/ `PAGINATION_MODE_CURSOR` |
| `cursor` | string | 否 | 游标值（配合游标分页模式使用） |
### 过滤条件（filtering）
| 字段 | 说明 | 支持的操作符 |
|------|------|-------------|
| `adgroup_id` | 广告 ID | EQUALS, IN（IN 时最多 100 个） |
| `adgroup_name` | 广告名称 | CONTAINS |
| `created_time` | 创建时间（`YYYY-MM-DD HH:mm:ss` 格式，脚本自动转时间戳） | GREATER, LESS, GREATER_EQUALS, LESS_EQUALS |
| `last_modified_time` | 最后修改时间（`YYYY-MM-DD HH:mm:ss` 格式，脚本自动转时间戳） | GREATER, LESS, GREATER_EQUALS, LESS_EQUALS |
| `configured_status` | 客户设置的状态 | EQUALS, IN |
| `material_package_id` | 素材包 ID | EQUALS |
| `joint_budget_rule_id` | 联合预算规则 ID | EQUALS |
| `auto_derived_creative_enabled` | 创意增强 MAX 开关 | EQUALS |
| `rta_target_id` | RTA 目标 ID | EQUALS |
### 使用示例
#### 1. 查询指定广告 ID 的详情（最常用）
```bash
node scripts/query-adgroups.mjs '{"account_id":"39412855","adgroup_ids":["72536365535"]}'
```
#### 2. 查询账户下所有广告列表
```bash
node scripts/query-adgroups.mjs '{"account_id":"39412855"}'
```
#### 3. 查询指定返回字段
```bash
node scripts/query-adgroups.mjs '{"account_id":"39412855","fields":["adgroup_id","adgroup_name","configured_status","targeting","bid_amount","daily_budget"]}'
```
#### 4. 根据广告名称模糊搜索
```bash
node scripts/query-adgroups.mjs '{"account_id":"39412855","filtering":[{"field":"adgroup_name","operator":"CONTAINS","values":["品牌推广"]}]}'
```
#### 5. 按状态筛选广告
```bash
node scripts/query-adgroups.mjs '{"account_id":"39412855","filtering":[{"field":"configured_status","operator":"EQUALS","values":["AD_STATUS_NORMAL"]}]}'
```
#### 6. 查询已删除的广告
```bash
node scripts/query-adgroups.mjs '{"account_id":"39412855","is_deleted":true}'
```
#### 7. 使用游标分页获取全量数据
```bash
# 第一次请求
node scripts/query-adgroups.mjs '{"account_id":"39412855","pagination_mode":"PAGINATION_MODE_CURSOR","page_size":100}'
# 后续请求（使用上一次返回的 cursor）
node scripts/query-adgroups.mjs '{"account_id":"39412855","pagination_mode":"PAGINATION_MODE_CURSOR","page_size":100,"cursor":"xxx"}'
```
#### 8. 按创建时间筛选（查最近 7 天创建的广告）
```bash
node scripts/query-adgroups.mjs '{"account_id":"39412855","filtering":[{"field":"created_time","operator":"GREATER_EQUALS","values":["2026-04-03 00:00:00"]}]}'
```
> `created_time` 支持 `YYYY-MM-DD HH:mm:ss` 格式，脚本自动转为 Unix 时间戳。也支持直接传时间戳。
### 返回结构
```json
{
"list": [
{
"adgroup_id": 72536365535,
"adgroup_name": "广告名称",
"campaign_id": 12345,
"configured_status": "AD_STATUS_NORMAL",
"system_status": "ADGROUP_STATUS_NORMAL",
"marketing_goal": "MARKETING_GOAL_PRODUCT_SALES",
"bid_amount": 5000,
"optimization_goal": "OPTIMIZATIONGOAL_ECOMMERCE_ORDER",
"begin_date": "2026-03-20",
"end_date": "2026-04-20",
"daily_budget": 100000,
"targeting": {
"geo_location": { "regions": [110000, 310000] },
"age": [{ "min": 18, "max": 45 }],
"gender": ["MALE", "FEMALE"]
},
"site_set": ["SITE_SET_WECHAT"],
"bid_mode": "BID_MODE_OCPM",
"smart_bid_type": "SMART_BID_TYPE_CUSTOM",
...
}
],
"page_info": {
"page": 1,
"page_size": 10,
"total_number": 50,
"total_page": 5
}
}
```
### 注意事项
1. **请求方式**: 该脚本使用 **GET** 方法。
2. **金额单位**: 所有金额字段单位为**分**（如 `bid_amount = 5000` 表示出价 50 元）。
3. **分页限制**: 普通分页模式下 `page` 最大 100，`page_size` 最大 100。需获取全量数据时推荐使用**游标分页模式**。
4. **字段选择**: 未指定 `fields` 时脚本自动使用默认字段集，覆盖基础信息、定向、出价、转化、智投项目配置（含周期达成、成本保障、直播加热等）等全量字段。如需查看特定字段，建议显式传入 `fields` 参数。
5. **与 query-report.mjs 配合**: 先用 `query-report.mjs` 获取广告列表和报表数据，找到感兴趣的广告后，再用 `query-adgroups.mjs` 查看其详细配置。
---
### 智能投放项目详情查询
> **智能投放项目复用了 adgroup（广告）的接口**，因此接口中的字段名与项目概念的对应关系如下：
>
> | 项目概念 | 接口字段 | 说明 |
> |---------|---------|------|
> | 项目 ID | `adgroup_id` | 智投项目 ID 对应接口中的广告 ID |
> | 项目名称 | `adgroup_name` | 智投项目名称对应接口中的广告名称 |
> | 项目状态 | `configured_status` / `system_status` | 项目的配置状态与系统状态 |
> | 项目预算 | `daily_budget` / `total_budget` | 项目日预算与总预算 |
> | 项目出价 | `bid_amount` | 项目出价对应接口中的广告出价 |
> | 项目创建时间 | `created_time` | 项目创建时间（返回 `YYYY-MM-DD HH:mm:ss` 格式） |
> | 项目修改时间 | `last_modified_time` | 项目最后修改时间（返回 `YYYY-MM-DD HH:mm:ss` 格式） |
>
> 其他字段也类同，接口层面项目与广告共用同一套数据结构，调用方式完全一致。
智能投放项目详情的获取使用 `query-adgroups.mjs` 脚本。脚本支持按需指定 `fields` 参数来获取所需字段；如果不指定 `fields`，脚本内置了覆盖智投项目全量配置的默认字段集（包括周期达成、成本保障、直播加热等），无需手动传入。
#### 使用示例
##### 1. 获取智能投放项目详情（使用默认字段，最常用）
```bash
node scripts/query-adgroups.mjs '{"account_id":"39412855","adgroup_ids":["72536365535"]}'
```
> 不指定 `fields` 时，脚本自动返回上述所有默认字段。
##### 2. 按需获取指定字段
```bash
node scripts/query-adgroups.mjs '{"account_id":"39412855","adgroup_ids":["72536365535"],"fields":["adgroup_id","adgroup_name","smart_delivery_platform","smart_delivery_scene","project_ability_list","smart_delivery_aigc_option","smart_targeting_status"]}'
```
> 只需要查看智投相关配置时，可以通过 `fields` 按需获取，减少返回数据量。
##### 3. 查询账户下所有智投项目详情
```bash
node scripts/query-adgroups.mjs '{"account_id":"39412855","page_size":100}'
```
##### 4. 按项目名称搜索智投项目详情
```bash
node scripts/query-adgroups.mjs '{"account_id":"39412855","filtering":[{"field":"adgroup_name","operator":"CONTAINS","values":["智投项目关键词"]}]}'
```
#### 智投项目专有字段说明
| 字段 | 类型 | 说明 |
|------|------|------|
| smart_delivery_platform | enum | 行业智投平台类型 |
| smart_delivery_scene | enum | 智投投放场景 |
| smart_delivery_scene_spec | struct | 场景化投放信息（含投放目标、转化 ID 列表等） |
| smart_delivery_aigc_option | enum | 智投 AIGC 选项 |
| smart_delivery_auto_creative | struct | 智投自动创意信息（含是否开启、供给策略、组件等） |
| smart_delivery_history_comp_reused_creative | struct | 智投历史组件复用创意 |
| smart_delivery_aigc_creative | struct | 智投 AIGC 创意配置 |
| smart_delivery_live_boost | enum | 直播加热 |
| smart_targeting_status | enum | 广告智能定向状态 |
| project_ability_list | array | 场景化投放原子能力列表 |
| project_ability_spec | struct | 场景化投放原子能力（含营销表达、优化出价） |
| boost_source_project_id | int64 | 加热源项目 ID |
| exploration_strategy | enum | 自动版位探索策略（自动版位开启时生效） |
| flow_lock_status | enum | 锁量状态 |
| aoi_optimization_strategy | struct | 高价值范围探索 |
| cost_guarantee_status | enum | 成本保障状态 |
| cost_guarantee_money | int64 | 成本保障赔付金额（单位：分） |
| expected_roi_mix_factor | float64 | 混变系数（0.0001~9999.9999） |
| smart_coupon_mode | enum | 小店智券开关 |
| auto_derived_creative_preference | struct | 创意增强 MAX 偏好设置 |
| enable_breakthrough_siteset | boolean | 是否支持版位突破 |
| live_recommend_strategy_enabled | boolean | 直播种草人群探索 |
| audience_model_bid_adjustment | struct | 后效建模优化功能 |
| additional_product_spec | struct | 附加商品属性 |
| incubation_optimization_goal | enum | 孵化优化目标 |
| conversion_name | string | 转化名称 |
| completed_time | integer | 广告总限额到达时间戳（unix 秒级） |
| smart_delivery_period_switch | enum | 周期达成 |
| smart_delivery_period_budget | integer | 周期预算（单位：分，0 表示不限） |
| smart_delivery_period_days | enum | 周期天数 |
| smart_delivery_period_continue | enum | 周期续投 |
| smart_delivery_period_begin_date | string | 周期开始日期 |
| smart_delivery_period_end_date | string | 周期结束日期 |
---
## 脚本：query-creatives.mjs
> **创意列表查询脚本**，用于获取创意的完整信息。
### 适用场景
- 需要查看广告下的**创意列表**及其组成结构（创意组件引用）
- 需要了解创意的**投放模式、创意类型、创意状态**等配置信息
- 需要查看创意中**组件的具体内容**（标题文案、描述文案、图片、视频等）
- 需要查看**已删除的创意**信息
- 需要根据**创意名称、广告 ID、创建时间**等条件筛选创意
### 与其他脚本的区别
| 对比项 | query-report.mjs | query-creatives.mjs |
|--------|-----------------|---------------------|
| 返回报表数据 | ✅ 返回消耗、曝光、点击等报表指标 | ❌ 不返回报表数据 |
| 返回创意组件详情 | ⚠️ 仅返回创意级别基本属性 | ✅ 返回完整的 creative_components 结构 |
| 自动解析组件内容 | ❌ | ✅ 自动拉取组件详情并内联 |
| 需要日期范围 | ✅ 必填 | ❌ 不需要 |
| 支持跨账户 | ✅ 支持 | ❌ 单账户 |
| 查看已删除创意 | ❌ 不支持 | ✅ 支持 |
| 支持游标分页 | ❌ | ✅ 支持 |
### 调用方式
```bash
node scripts/query-creatives.mjs '<JSON 参数>'
```
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `account_id` | string | **是** | 广告主账号 ID |
| `tencent_ads_type` | enum | 否 | 广告实体类型，**枚举值只允许 `"smart"` / `"standard"` / `"all"` 三者之一**，默认 `"all"`。详见步骤 1.5 |
| `creative_ids` | string[] | 否 | 指定创意 ID 列表（按 ID 精确查询） |
| `adgroup_ids` | string[] | 否 | 按广告 ID 过滤创意 |
| `fields` | string[] | 否 | 自定义返回字段（不传则使用默认字段集） |
| `filtering` | struct[] | 否 | 过滤条件数组 |
| `page` | integer | 否 | 页码，默认 1（最大 100） |
| `page_size` | integer | 否 | 每页条数，默认 10（最大 100） |
| `is_deleted` | boolean | 否 | 是否查询已删除创意，默认 false |
| `pagination_mode` | enum | 否 | 分页方式：`PAGINATION_MODE_NORMAL`（默认）/ `PAGINATION_MODE_CURSOR` |
| `cursor` | string | 否 | 游标值（配合游标分页模式使用） |
### 过滤条件（filtering）
| 字段 | 说明 | 支持的操作符 |
|------|------|-------------|
| `dynamic_creative_id` | 创意 ID | EQUALS, IN（IN 时最多 100 个） |
| `dynamic_creative_name` | 创意名称 | CONTAINS |
| `adgroup_id` | 所属广告 ID | EQUALS, IN（IN 时最多 100 个） |
| `created_time` | 创建时间（`YYYY-MM-DD HH:mm:ss` 格式，脚本自动转时间戳） | GREATER, LESS, GREATER_EQUALS, LESS_EQUALS |
| `last_modified_time` | 最后修改时间（`YYYY-MM-DD HH:mm:ss` 格式，脚本自动转时间戳） | GREATER, LESS, GREATER_EQUALS, LESS_EQUALS |
| `configured_status` | 客户设置的状态 | EQUALS, IN |
| `source` | 创意来源 | EQUALS, IN |
| `component_id` | 组件 ID | EQUALS |
| `data_model_version` | 数据模型版本 | EQUALS |
| `smart_delivery_template_dc_id` | 智投模板创意 ID | EQUALS, IN |
### 返回的创意详情字段
#### 创意基础信息
| 字段 | 类型 | 说明 |
|------|------|------|
| dynamic_creative_id | integer | 创意 ID |
| dynamic_creative_name | string | 创意名称 |
| adgroup_id | int64 | 所属广告 ID（若 `smart_delivery_platform >= SMART_DELIVERY_PLATFORM_EDITION_SCENE` 则为**智能投放项目 ID**，展示时应标注"项目ID"；否则为**竞价广告 ID**，展示时标注"广告ID"） |
| smart_delivery_platform | enum | 智投平台版本，用于区分是否为智投广告。枚举值含义见下方说明 |
| creative_template_id | integer | 创意形式 ID |
| delivery_mode | enum | 投放模式 |
| dynamic_creative_type | enum | 动态创意类型 |
| configured_status | enum | 客户设置的状态（`AD_STATUS_NORMAL` / `AD_STATUS_SUSPEND`） |
| created_time | integer | 创建时间（时间戳） |
| last_modified_time | integer | 最后修改时间（时间戳） |
| is_deleted | boolean | 是否已删除 |
#### smart_delivery_platform 枚举值说明
| 艾米类型 | 场景 | 枚举值 | 是否智投 |
|----------|------|--------|---------|
| 默认 | 常规3.0广告（非智投） | `SMART_DELIVERY_PLATFORM_EDITION_STANDARD` | ❌ 否 |
| 小店艾米 | 短直双开智投 | `SMART_DELIVERY_PLATFORM_EDITION_WECHAT_STORE_SINGLE_PRODUCT` | ✅ 是 |
| 小店艾米 | 小店单链路智投 | `SMART_DELIVERY_PLATFORM_EDITION_WECHAT_STORE_PRODUCT_OR_LIVE` | ✅ 是 |
| 小店艾米 | 全店托管 | `SMART_DELIVERY_PLATFORM_EDITION_WECHAT_STORE_MANAGEMENT` | ✅ 是 |
| 小店艾米 | 推直播间 | `SMART_DELIVERY_PLATFORM_EDITION_WECHAT_STORE_LIVE` | ✅ 是 |
| 小店艾米 | 推商品 | `SMART_DELIVERY_PLATFORM_EDITION_WECHAT_STORE_PRODUCT` | ✅ 是 |
| 商品艾米 | 商品智投 | `SMART_DELIVERY_PLATFORM_EDITION_DRUG_PRODUCT` | ✅ 是 |
| 线索艾米 | 线索跑量 | `SMART_DELIVERY_PLATFORM_EDITION_ECOLOGY_LEADS` | ✅ 是 |
| 内容艾米 | 爆剧跑量 | `SMART_DELIVERY_PLATFORM_EDITION_ECOLOGY_PLAYLET` | ✅ 是 |
| 内容艾米 | 小说智投 | `SMART_DELIVERY_PLATFORM_EDITION_FICTION` | ✅ 是 |
| 内容艾米 | 小游戏跑量 | `SMART_DELIVERY_PLATFORM_EDITION_MINI_GAME_PROMOTION` | ✅ 是 |
| APP艾米 | 游戏应用智投 | `SMART_DELIVERY_PLATFORM_EDITION_GAME_APP` | ✅ 是 |
| APP艾米 | 阅读应用智投 | `SMART_DELIVERY_PLATFORM_EDITION_READING_APP` | ✅ 是 |
| APP艾米 | AI应用智投 | `SMART_DELIVERY_PLATFORM_EDITION_AI_APP` | ✅ 是 |
| APP艾米 | 游戏大推（即将下线） | `SMART_DELIVERY_PLATFORM_EDITION_BIG_GAME_PROMOTION` | ✅ 是 |
| - | 全域通-直播场景 | `SMART_DELIVERY_PLATFORM_EDITION_QYT_LIVE` | ✅ 是 |
| - | 全域通-直购场景 | `SMART_DELIVERY_PLATFORM_EDITION_QYT_WECHAT_STORE` | ✅ 是 |
> **判断规则**：`smart_delivery_platform` 为 `SMART_DELIVERY_PLATFORM_EDITION_STANDARD` 时为竞价广告（非智投），其余枚举值均为智投项目。
>
> **展示规则**：智投项目的 `adgroup_id` 展示为"项目ID"；竞价广告的 `adgroup_id` 展示为"广告ID"。
#### 创意组件（creative_components）
> **核心字段**：包含创意使用的所有组件引用信息。
`creative_components` 是一个 map 结构，key 为组件类型标识，value 为该类型的组件配置。常见的组件类型包括：
| 组件类型 | 说明 |
|---------|------|
| title | 标题 |
| description | 描述/文案 |
| image | 图片 |
| image_list | 图片列表（多图） |
| video | 视频 |
| brand | 品牌信息 |
| jump_info | 跳转链接/落地页 |
| action_button | 行动按钮 |
| consult | 咨询组件 |
| phone | 电话组件 |
| form | 表单组件 |
| label | 标签 |
| show_data | 数据展示 |
| marketing_pendant | 营销挂件 |
| floating_zone | 悬浮区域 |
| end_page | 结束页 |
| wechat_channels | 视频号组件 |
| short_video | 短视频组件 |
| element_story | 故事元素 |
每个组件通常包含 `component_id`（引用的组件 ID）。当查询结果只有 1 条创意时，脚本会自动拉取组件详情，并以 `_component_detail` 字段内联到各组件中，包含组件的实际内容（文案文本、图片 URL、视频 URL 等）。此外还会自动获取图片/视频的预览 URL，以 `_preview` 字段内联到对应素材中。
#### 其他字段
| 字段 | 类型 | 说明 |
|------|------|------|
| impression_tracking_url | string | 曝光监控地址 |
| click_tracking_url | string | 点击监控链接 |
| program_creative_info | struct | 程序化创意信息 |
| auto_derived_program_creative_switch | boolean | 自动生成更多素材开关 |
| marketing_asset_verification | struct | 资产验真信息 |
| creative_set_approval_status | enum | 创意审核状态 |
| asset_inconsistent_status | enum | 资产落地页一致性状态 |
| source_dynamic_creative_id | integer | 来源创意 ID |
### 使用示例
#### 1. 查询指定广告下的所有创意（最常用）
```bash
node scripts/query-creatives.mjs '{"account_id":"39412855","adgroup_ids":["72536365535"]}'
```
> 自动解析组件详情，返回创意完整信息 + 组件内容。
#### 2. 查询指定创意 ID 的详情
```bash
node scripts/query-creatives.mjs '{"account_id":"39412855","creative_ids":["98765432"]}'
```
#### 3. 查询账户下所有创意列表
```bash
node scripts/query-creatives.mjs '{"account_id":"39412855","page_size":20}'
```
#### 4. 按创意名称模糊搜索
```bash
node scripts/query-creatives.mjs '{"account_id":"39412855","filtering":[{"field":"dynamic_creative_name","operator":"CONTAINS","values":["品牌推广"]}]}'
```
#### 5. 查询已删除的创意
```bash
node scripts/query-creatives.mjs '{"account_id":"39412855","is_deleted":true}'
```
#### 7. 使用游标分页获取全量创意
```bash
# 第一次请求
node scripts/query-creatives.mjs '{"account_id":"39412855","pagination_mode":"PAGINATION_MODE_CURSOR","page_size":100}'
# 后续请求（使用上一次返回的 cursor）
node scripts/query-creatives.mjs '{"account_id":"39412855","pagination_mode":"PAGINATION_MODE_CURSOR","page_size":100,"cursor":"xxx"}'
```
#### 8. 指定返回字段
```bash
node scripts/query-creatives.mjs '{"account_id":"39412855","fields":["dynamic_creative_id","dynamic_creative_name","adgroup_id","creative_components","configured_status"]}'
```
### 返回结构
```json
{
"list": [
{
"dynamic_creative_id": 98765432,
"dynamic_creative_name": "创意名称-横版视频",
"adgroup_id": 72536365535,
"creative_template_id": 1708,
"delivery_mode": "DELIVERY_MODE_DEFAULT",
"dynamic_creative_type": "DYNAMIC_CREATIVE_TYPE_NORMAL",
"creative_components": {
"title": [{
"component_id": 11111,
"_component_detail": {
"component_id": 11111,
"component_value": {
"title": { "content": "这是标题文案" }
},
"component_sub_type": "TITLE",
"component_custom_name": "品牌标题"
}
}],
"description": [{
"component_id": 22222,
"_component_detail": {
"component_id": 22222,
"component_value": {
"description": { "content": "这是描述文案" }
},
"component_sub_type": "DESCRIPTION"
}
}],
"video": [{
"component_id": 33333,
"_component_detail": {
"component_id": 33333,
"component_value": {
"video": {
"video_id": "abc123",
"_preview": {
"video_id": "abc123",
"preview_url": "https://example.com/video_preview.mp4",
"key_frame_image_url": "https://example.com/keyframe.jpg",
"width": 1280,
"height": 720
}
}
},
"component_sub_type": "VIDEO"
}
}],
"image": [{
"component_id": 44444,
"_component_detail": {
"component_id": 44444,
"component_value": {
"image": {
"image_id": "def456",
"_preview": {
"image_id": "def456",
"preview_url": "https://example.com/image_preview.jpg",
"width": 800,
"height": 600
}
}
},
"component_sub_type": "IMAGE"
}
}]
},
"configured_status": "AD_STATUS_NORMAL",
"created_time": 1742860800,
"last_modified_time": 1742947200,
"is_deleted": false
}
],
"page_info": {
"page": 1,
"page_size": 10,
"total_number": 1,
"total_page": 1
}
}
```
> **`_component_detail` 字段**：当查询结果只有 1 条创意时，脚本自动为每个包含 `component_id` 的组件引用附加 `_component_detail` 字段，其中包含完整组件信息。
>
> **`_preview` 字段**：对于组件中包含 `image_id` 或 `video_id` 的素材，脚本自动获取预览信息（`preview_url`、尺寸等），以 `_preview` 字段内联到对应素材对象中。
### 注意事项
1. **请求方式**: 该脚本使用 **GET** 方法。
2. **组件自动解析**: 当查询结果只有 1 条创意时，脚本自动解析组件详情并获取图片/视频预览 URL，无需额外配置。多条创意时不解析组件，避免大量 API 请求影响性能。
3. **分页限制**: 普通分页模式下 `page` 最大 100，`page_size` 最大 100。需获取全量数据时推荐使用**游标分页模式**。
4. **与 query-report.mjs 配合**: 先用 `query-report.mjs` 获取创意级别的报表数据（level: DYNAMIC_CREATIVE），找到需要查看详情的创意后，再用 `query-creatives.mjs` 传入 `creative_ids` 查看其完整组件内容。
5. **与 query-adgroups.mjs 配合**: 先用 `query-adgroups.mjs` 获取广告详情，再用 `query-creatives.mjs` 按 `adgroup_id` 查询该广告下的所有创意。
6. **展示 adgroup_id 时区分广告/项目**：返回数据中的 `adgroup_id` 根据 `smart_delivery_platform` 字段决定展示名称：
- `EDITION_SCENE` 或 `EDITION_SCENE_PRO` → 展示为**项目ID**（智能投放项目）
- `EDITION_STANDARD` 或 `EDITION_NONE`（或字段缺失）→ 展示为**广告ID**（竞价广告）
7. **⚠️ 预览 URL 必须展示（强制）**：脚本返回的 `_preview.preview_url`（视频/图片预览链接）和 `_cover_preview.preview_url`（封面预览链接）**必须在回复中以可点击链接的形式呈现给用户**，不得省略或忽略。具体规则：
- 视频组件：展示视频 `preview_url`（🎥 视频预览链接）和封面 `preview_url`（🖼️ 封面链接）
- 图片组件：展示图片 `preview_url`（🖼️ 图片预览链接）
- 每个素材组件单独列出，用 Markdown 链接格式 `[描述](URL)` 呈现
- **绝对禁止**因内容过长、信息繁杂等原因而省略预览 URL
---
## 脚本：关键词管理（bidword）
管理广告的关键词（竞价词）。关键词用于搜索扩量场景，当广告开启搜索扩量（`search_expansion_switch = SEARCH_EXPANSION_SWITCH_OPEN`）后，可为广告设置搜索关键词。
> 详细参数、示例和返回值见 [references/bidword.md](references/bidword.md)
| 脚本 | 功能 | 必填参数 |
|------|------|---------|
| `scripts/bidword/add.mjs` | 创建关键词 | account_id, list[{adgroup_id, bidword, match_type}] |
| `scripts/bidword/update.mjs` | 更新关键词 | account_id, list[{bidword_id, ...}] |
| `scripts/bidword/delete.mjs` | 删除关键词 | account_id, list (bidword_id 数组) |
| `scripts/bidword/get.mjs` | 查询关键词 | account_id |
---
## 脚本：否定词管理（adgroup_negativewords）
管理广告组级别的否定关键词。否定词用于排除不相关的搜索词，避免广告在不相关的搜索结果中展示。
> 详细参数、示例和返回值见 [references/negativewords.md](references/negativewords.md)
| 脚本 | 功能 | 必填参数 |
|------|------|---------|
| `scripts/negativewords/add.mjs` | 新增否定词 | account_id, adgroup_id, phrase_negative_words, exact_negative_words |
| `scripts/negativewords/update.mjs` | 更新否定词（全量替换） | account_id, adgroup_id, phrase_negative_words, exact_negative_words |
| `scripts/negativewords/get.mjs` | 查询否定词 | account_id, adgroup_ids |
---
## 推广内容资产管理
创建和查询推广内容资产（marketing_asset）。**执行前必须先读取** [references/marketing-asset/overview.md](references/marketing-asset/overview.md)。
> 详细流程说明（CPV/SPU/电商分类、创建步骤、参数说明、约束等）见 [references/marketing-asset/overview.md](references/marketing-asset/overview.md)
---
## 相关技能
- **tencentads-adgroups** - 管理广告（创建/更新/删除广告）
- **tencentads-delivery-smart** - 智投选参指南（智投报表需与非智投分开查询）
- **tencentads-delivery-standard** - 常规投放选参指南
- **tencentads-creatives** - 管理动态创意
- **tencentads-components** - 管理创意组件
- **tencentads-batch** - 批量调整广告
- **tencentads-materials** - 管理素材
Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.
No comments yet. Be the first to comment!
