百度 SEM 营销管理技能

Python 工具集，通过百度营销 API 实现搜索推广和信息流广告的全链路管理。支持广告计划管理、关键词操作、数据报告、自动竞价优化等核心场景，面向 SEM 运营提效和自动化部署。

官方文档

• 开发者中心: https://dev2.baidu.com
• 搜索推广 API: https://dev2.baidu.com/content?sceneType=0&pageId=100138
• 信息流 API: https://dev2.baidu.com/content?sceneType=0&pageId=102330
• 报告 API: https://dev2.baidu.com/content?sceneType=0&pageId=102476
• OAuth 认证: https://dev2.baidu.com/content?sceneType=0&pageId=100141

功能概览

广告管理

• 计划管理 — 推广计划的创建、查询、更新、暂停/启用
• 推广单元管理 — 广告组的 CRUD 操作，支持按计划批量筛选
• 创意管理 — 创意的创建与修改，支持标题、描述、落地页等字段
• 信息流管理 — 信息流广告的独立管理，包括 feed 推广计划与创意

关键词操作

• 关键词报告 — 查询账户全部关键词数据，输出含13个维度的完整报告（上方位平均排名、预估搜索量、竞争度、建议出价等）
• 关键词落地页修改 — 按推广计划批量修改 PC/移动端落地页链接，支持 URL 模板变量替换（{keyword} 自动编码为关键词名），支持 dry-run 预览
• 关键词自动调价 — 基于实时排名和搜索量数据，按策略自动调整出价（排名第一降价10%、无排名且高搜索量涨价20%、设有上下限保护）

数据与报告

• 报告下载 — 异步下载账户/计划/单元/创意/关键词维度的投放报告
• 数据分析 — 通用数据分析工具，支持多维度交叉分析
• 批量操作 — 批量增删改查，每次最多处理 5000 条，自动分批执行

基础设施

• 连接测试 — 一键检测配置完整性、Token 有效性和 API 网络连通性
• OAuth 2.0 认证 — 完整的授权流程脚本，支持授权码获取和 Token 刷新
• 操作日志 — 每次操作自动记录到 logs/ 目录，生成日期-操作总结.md 格式的详细日志
• API 客户端 — 通用 API 调用模板，内置自动 Token 刷新和多账户支持

项目结构

baidu-marketing-api/
├── config/
│   └── config.json              # 凭据和账户配置（需自行创建）
├── scripts/
│   ├── oauth_auth.py            # OAuth 2.0 认证（授权/刷新/状态查询）
│   ├── oauth_server.py          # OAuth 回调服务器
│   ├── test_connection.py       # 连接测试
│   ├── api_client_template.py   # 通用 API 客户端
│   ├── campaign_manager.py      # 推广计划管理
│   ├── adgroup_manager.py       # 推广单元管理
│   ├── creative_manager.py      # 创意管理
│   ├── keyword_reporter.py      # 关键词数据报告
│   ├── keyword_url_updater.py   # 关键词落地页批量修改
│   ├── keyword_bid_adjuster.py  # AI 关键词自动调价
│   ├── batch_operations.py      # 批量操作
│   ├── report_downloader.py     # 报告下载
│   ├── data_analyzer.py         # 数据分析
│   ├── feed_manager.py          # 信息流广告管理
│   ├── search_promotion_manager.py  # 搜索推广管理
│   ├── auto_optimizer.py        # 自动优化工具
│   ├── operation_logger.py      # 操作日志记录
│   └── run_keyword_report.py    # 快速生成关键词报告
├── references/
│   ├── credential_management.md # 凭证管理详细指南
│   ├── authentication.md        # 认证方式详解（OAuth/BCE/Token）
│   ├── api_services_full.md     # API 服务完整清单
│   ├── bid_adjustment_strategy.md  # AI 调价策略文档
│   ├── error_codes.md           # 错误码速查
│   ├── reporting.md             # 报告接口文档
│   ├── search_ads.md            # 搜索广告接口
│   └── feed_ads.md              # 信息流广告接口
├── assets/
│   ├── config.json.template     # 配置文件模板
│   └── config.example.json      # 配置文件示例
├── logs/                        # 操作日志（自动生成）
└── cache/                       # 数据缓存（自动生成）

部署方式

方式一：本地直接使用

适用场景：个人使用、脚本调试、单机运行

# 1. 克隆项目
git clone 
cd baidu-marketing-api

# 2. 安装依赖
pip3 install requests

# 3. 创建配置文件
cp assets/config.json.template config/config.json
# 编辑 config.json，填入 app_id、secret_key 等凭据

# 4. OAuth 授权获取 Token
python3 scripts/oauth_auth.py auth-url
# 浏览器打开授权 URL，完成登录后获取 authCode
python3 scripts/oauth_auth.py --auth-code YOUR_AUTH_CODE

# 5. 测试连接
python3 scripts/test_connection.py

# 6. 开始使用
python3 scripts/keyword_reporter.py              # 生成关键词报告
python3 scripts/keyword_url_updater.py --list-campaigns  # 查看推广计划

方式二：集成到 AI Agent

适用场景：作为 AstrBot / 其他 Agent 的技能插件运行

# 1. 将技能目录放置到 Agent 的 skills 目录
cp -r baidu-marketing-api /path/to/agent/skills/

# 2. 确保 SKILL.md 存在且路径正确
ls skills/baidu-marketing-api/SKILL.md

# 3. 创建配置文件
cp skills/baidu-marketing-api/assets/config.json.template \
   skills/baidu-marketing-api/config/config.json
# 填入真实凭据

# 4. Agent 读取 SKILL.md 后即可调用各脚本

方式三：服务器后台运行

适用场景：定期报告生成、自动调价等定时任务

# 1. 部署项目到服务器（同方式一的步骤 1-4）

# 2. 后台运行关键词报告（约3-5分钟）
nohup python3 scripts/keyword_reporter.py \
  --output logs/关键词报告.csv --days 7 \
  > logs/report.log 2>&1 &

# 3. 查看进度
tail -f logs/report.log

# 4. 后台运行自动调价
nohup python3 scripts/keyword_bid_adjuster.py --apply \
  > logs/bid_adjust.log 2>&1 &

# 5. 搭配 crontab 定时执行
# 每天早上9点生成关键词报告
0 9 * * * cd /path/to/baidu-marketing-api && python3 scripts/keyword_reporter.py >> logs/cron.log 2>&1
# 每天早上10点执行自动调价
0 10 * * * cd /path/to/baidu-marketing-api && python3 scripts/keyword_bid_adjuster.py --apply >> logs/cron.log 2>&1

鉴权机制

本技能采用 OAuth 2.0 鉴权方式，需要以下凭据：

应用级凭据 (App Credentials)

在百度营销开发者中心创建应用后获得：

账户级凭据 (Account Credentials)

通过 OAuth 授权流程获取，存储在 config/config.json 中：

API 端点

搜索推广 API:  https://api.baidu.com/json/sms/service
信息流 API:    https://api.baidu.com/json/feed/v1
OAuth Token:   https://u.baidu.com/oauth/accessToken
OAuth Refresh: https://u.baidu.com/oauth/refreshToken

快速开始

第一步：获取应用凭据

1. 访问 https://dev2.baidu.com 注册开发者账号
2. 完成实名认证
3. 创建应用，填写：
   • 应用名称、描述
   • 回调地址: http://localhost:8080/oauth/callback
4. 获取 App ID 和 Secret Key

第二步：配置应用凭据

cd baidu-marketing-api
cp assets/config.json.template config/config.json
# 编辑 config.json，填入 app_id 和 secret_key

第三步：OAuth 授权获取 Token

# 生成授权 URL
python3 scripts/oauth_auth.py auth-url

# 在浏览器中打开 URL，完成授权后获取 authCode
# 使用授权码换取 Token
python3 scripts/oauth_auth.py --auth-code YOUR_AUTH_CODE

第四步：测试连接

python3 scripts/test_connection.py

配置文件示例

{
  "app": {
    "app_id": "YOUR_APP_ID",
    "secret_key": "YOUR_SECRET_KEY",
    "callback_url": "http://localhost:8080/oauth/callback",
    "scope": "1007690",
    "state": "random_state_string"
  },
  "accounts": [
    {
      "account_name": "推广账户名称",
      "user_name": "推广用户名",
      "user_id": 12345678,
      "access_token": "eyJhbGciOi...",
      "refresh_token": "eyJhbGciOi...",
      "token_expires_at": "2026-04-11T14:31:03",
      "refresh_expires_at": "2026-05-10T14:31:03",
      "enabled": true
    }
  ],
  "api_settings": {
    "base_url_search": "https://api.baidu.com/json/sms/service",
    "base_url_feed": "https://api.baidu.com/json/feed/v1",
    "oauth_token_url": "https://u.baidu.com/oauth/accessToken",
    "oauth_refresh_url": "https://u.baidu.com/oauth/refreshToken",
    "timeout": 30,
    "auto_refresh_token": true
  }
}

OAuth 授权流程

┌─────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────┐
│  用户    │ →  │ 授权页面     │ →  │  回调地址    │ →  │ 获取Token│
│ 浏览器   │    │ u.baidu.com │    │ localhost   │    │ API调用 │
└─────────┘    └─────────────┘    └─────────────┘    └─────────┘

1. 构建授权 URL: https://u.baidu.com/oauth/authorize?appid={APP_ID}&...
2. 用户授权: 用户在浏览器中登录并同意授权
3. 获取授权码: 从回调 URL 中提取 authCode 参数
4. 换取 Token: 调用 https://u.baidu.com/oauth/accessToken 获取 access_token 和 refresh_token

Token 刷新

当 access_token 过期时（约24小时），使用 refresh_token 刷新：

python3 scripts/oauth_auth.py refresh

注意：refresh_token 有效期约30天，过期后需要重新进行 OAuth 授权流程。

常见问题

Q: 授权码过期怎么办？

授权码有效期约10分钟，过期后需重新获取授权 URL。

Q: refresh_token 失效怎么办？

运行 python3 scripts/oauth_auth.py auth-url 重新授权。

Q: 支持多账户吗？

支持，在 config.json 的 accounts 数组中添加多个账户即可。

Q: 批量操作的并发限制？

每次最多 5000 条，脚本自动分批执行，批次间有延迟以避免触发限流。

参考文档

• 详细凭据管理: references/credential_management.md
• API 服务清单: references/api_services_full.md
• 认证详解: references/authentication.md
• AI 调价策略: references/bid_adjustment_strategy.md
• 错误码速查: references/error_codes.md