媒体广告流量分析

查询广告投放流量分布与趋势的数据分析技能。支持按行业、地域、媒体（OTT/移动端）、目标受众等多维度分析广告曝光数据，适用于媒体策略评估、竞品投放监测、行业广告趋势研究等场景。

MediaInsight 广告流量通用技能

快速体验

从 skill 根目录 执行以下命令可直接体验。 整个 skill 目录可单独打包分享，不依赖仓库其他 Python 模块。

脚本内置了一个公开演示 Token。 这个 Token 权限受限，只能看到有限的行业、广告主、品牌、媒体、地域与数据集。

新建任务默认值：

• 行业默认：美妆个护类
• 广告主默认：明略集团
• 品牌默认：明略科技
• 媒体默认：当前 Token 可见的全部媒体大类（即 type=1 顶层媒体类目），不是全部具体媒体

默认输出可以理解为：

• 美妆个护类 行业
• 在当前默认 Token 可见的全部媒介类型 / 媒体大类上
• 查看广告流量分布

如果用户希望：

• 查看其他行业
• 细化到具体媒体而不是媒体大类
• 使用更完整的权限范围

则需要使用自己的账号 Token，或单独申请具备对应权限的账号。

python3 ./scripts/submit_ad_task.py \
  --task-name '演示：近1月广告流量分布' \
  --region-name 北京市 \
  --region-name 上海市 \
  --region-name 广州市 \
  --region-name 深圳市 \
  --months-back 1

如需使用自己的权限视图，可显式传入 --jwt 或 --jwt-file 覆盖默认演示 Token。

适用场景

当用户需要分析广告流量分布或趋势，并提供以下信息时，使用此技能：

• MediaInsight JWT Token：用于身份验证，从中提取用户凭据。
• 业务约束条件：包括行业、广告主、品牌、目标受众（TA）、地域范围、媒体范围等。
• 如果用户没有指定行业，默认使用 美妆个护类。该行业在当前默认 Token 下的实际 ID 为 000000130000000000001960。
• 如果用户没有指定媒体，默认选择当前 Token 可见的全部媒体大类。这不是单个固定 ID，而是当前 Token 可见的 type=1 顶层媒体类目集合；当前默认 Token 下共 25 个。
• 因此默认 Token 的典型输出，不是“全行业、全媒体明细”，而是“美妆个护行业在所有可见媒介类型上的广告流量”。

核心入口

调用本目录下的脚本：

./scripts/submit_ad_task.py

下载已完成任务结果时，调用：

./scripts/download_ad_task_report.py --biz-id 104433 --extract-dir ./downloads/task-104433

注意： 任务创建成功后，报告文件生成通常还需要额外时间。 实际测试中，文件生成过程可能耗时约 10 分钟，建议至少等待 10 分钟后再执行下载。 如果过早下载，脚本会返回 report file is not ready for download。

执行流程

1. 解码 JWT Payload，从 sub 字段提取 username 和 password。
2. 使用提取的凭据登录 MediaInsight。
3. 读取该用户权限范围内的实时字典：
   • 数据集、行业、广告主、品牌、地域、目标受众（TA）、媒体、投放类型、广告点位类型。
4. 仅在该 Token 可见的选项范围内解析用户输入的名称为 ID。
5. 将"全部媒体"展开为该 Token 可见的全量媒体 ID 集合（而非部分子集）。 如果用户未指定媒体，也未要求 all media，则默认使用当前 Token 可见的全部媒体大类（type=1）。
6. 计算本次任务消耗的积分数。
7. 提交任务。
8. 任务完成后，如需取回结果文件，按 bizId 或内部 taskId 下载报告 ZIP，并可解压得到 CSV。 报告文件生成可能耗时约 10 分钟，下载前应先等待文件生成完成。

操作规则

1. 禁止硬编码：不得跨用户硬编码广告主、品牌、媒体、地域或行业 ID，所有 ID 必须从当前 Token 的字典中动态解析。
2. 权限边界：若请求的名称在当前 Token 的字典中不存在，立即停止，向用户说明该项超出当前账号权限范围。
3. 媒体展开规则："全部媒体"必须展开为该 Token 可见的完整具体媒体列表，不得只取少量精选子集。
4. 名称匹配策略：优先精确匹配；仅当精确匹配无结果且存在唯一部分匹配时，才使用模糊匹配。
5. 可审计性：如需保留审计记录或保证任务可复现，将解析后的 Payload 写入文件（使用 --payload-out 参数）。

标准调用示例

python3 ./scripts/submit_ad_task.py \
  --task-name '近2月美妆个护媒体大类流量分布' \
  --industry-name '美妆个护类' \
  --gender female \
  --age-range 20-49 \
  --region-name 北京市 \
  --region-name 上海市 \
  --region-name 广州市 \
  --region-name 深圳市 \
  --months-back 2 \
  --payload-out /tmp/mediainsight-task.json

常用参数变体

场景	参数
使用默认行业	可省略 --industry-name，默认 美妆个护类
使用默认媒体大类	可省略 --media-name 和 --all-media，脚本会自动选择当前 Token 可见的全部 type=1 媒体大类
仅查询单月数据	--months-back 1
指定特定数据集	--dataset 202603
指定具体媒体（替代全媒体）	--media-name 爱奇艺 --media-name 腾讯新闻
指定开放年龄段	--age-range 20+ 或 --age-range 20岁及以上
查询全部人群	--gender all --age-range all
仅解析不提交（调试模式）	--dry-run

年龄参数规则

--age-range 不要使用 20-99 这类近似写法。 请直接使用产品语义对应的年龄表达，脚本会自动映射到真实 TA 年龄桶。

• 20-49：表示 20-24、25-29、30-34、35-39、40-44、45-49
• 20+：表示 20 岁及以上，会覆盖到 60岁及以上
• 20岁及以上：等价于 20+
• all：表示全部年龄段

如果用户说“男 20+”，应使用：

--gender male --age-range 20+

不要改写成：

--gender male --age-range 20-99

预期输出

脚本输出一个 JSON 对象，包含以下字段：

字段	说明
login	登录状态
session_file	会话文件路径
resolvedPayload	解析后的完整任务参数
coin	本次任务消耗的积分数
create	任务创建结果（--dry-run 模式下不包含此字段）

注意： resolvedPayload.reportArgsAd.mediaList 在三种情况下含义不同：

• 省略媒体参数：默认写入当前 Token 可见的全部媒体大类 ID（type=1）
• --all-media：写入当前 Token 可见的全部具体媒体 ID（type=3）
• --media-name ...：写入用户指定名称解析出的媒体/媒体类目 ID

结果下载提醒：

• 任务创建成功不等于结果文件立刻可下载
• 报告文件生成过程可能耗时约 10 分钟
• 建议等待约 10 分钟后，再调用 download_ad_task_report.py

异常处理

异常现象	原因判断
登录失败	JWT 无效或已过期
名称解析失败	该名称超出当前账号的权限范围
积分计算成功但任务提交失败	提交链路本身有效，失败原因在任务侧，非技能问题