gdt-api-gateway

腾讯广点通API网关服务

基于FastAPI和MCP的GDT API集成服务，提供安全的API访问和参数处理。

特性

• ✅ 安全认证 - 支持通过环境变量和HTTP Header传递access token
• ✅ 参数修复 - 修复了数组参数序列化和level映射问题
• ✅ 完整接口 - 支持日报表、小时报表、实时消耗、定向标签等核心接口
• ✅ MCP集成 - 原生支持MCP工具调用
• ✅ 结构化日志 - 内置请求追踪和错误处理

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 环境配置

创建 .env 文件：

# GDT API配置 (可选 - 推荐通过MCP环境变量传递)
GDT_ACCESS_TOKEN=your_access_token_here
GDT_CLIENT_ID=your_client_id_here  
GDT_CLIENT_SECRET=your_client_secret_here
GDT_API_BASE_URL=https://api.e.qq.com/v3.0

# FastAPI配置
FASTAPI_HOST=0.0.0.0
FASTAPI_PORT=8000
LOG_LEVEL=INFO
DEBUG=false

3. 启动服务

# 开发模式
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 生产模式
uvicorn app.main:app --host 0.0.0.0 --port 8000

MCP工具配置

安全配置方式 (推荐)

通过MCP环境变量传递认证信息，避免在代码中硬编码敏感信息：

{
  "mcpServers": {
    "gdt-api": {
      "command": "uvicorn",
      "args": ["app.main:app", "--host", "0.0.0.0", "--port", "8000"],
      "env": {
        "GDT_ACCESS_TOKEN": "your_actual_access_token",
        "GDT_CLIENT_ID": "your_client_id",
        "GDT_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

HTTP Header方式

也可以通过HTTP Header传递认证信息：

curl -X GET "http://localhost:8000/reports/daily" \\
  -H "X-GDT-Access-Token: your_access_token" \\
  -H "X-GDT-Client-ID: your_client_id" \\
  -H "X-GDT-Client-Secret: your_client_secret" \\
  -G -d "account_id=123456789" \\
  -d "start_date=2025-01-01" \\
  -d "end_date=2025-01-31"

API接口

报表接口

• GET /reports/daily - 获取日报表
• GET /reports/hourly - 获取小时报表
• GET /reports/realtime_cost - 获取实时消耗
• GET /reports/targeting_tag - 获取定向标签报表
• GET /reports/summary - 获取账户概览

管理接口

• GET /accounts/funds - 获取账户资金
• GET /adgroups/ - 获取广告组列表
• GET /ads/ - 获取广告列表
• GET /adcreatives/ - 获取创意列表

工具接口

• GET /health - 健康检查
• GET /docs - API文档

安全特性

1. 环境变量优先级

HTTP Header > 环境变量 > 配置文件

2. 认证验证

# 自动验证access_token是否存在
if not self.access_token:
    raise ValidationError("GDT access token is required")

3. 敏感信息保护

• ❌ 不在代码中硬编码access token
• ✅ 通过环境变量安全传递
• ✅ 支持动态token更新
• ✅ 请求日志中隐藏敏感信息

参数修复

1. 数组参数序列化

# 修复前：["date", "cost"] -> "['date', 'cost']" (错误格式)
# 修复后：["date", "cost"] -> '["date","cost"]' (正确的紧凑JSON)

2. Level参数映射

# 日报表/小时报表
"ADGROUP" -> "REPORT_LEVEL_ADGROUP"

# 定向标签报表  
"ADGROUP" -> "ADGROUP" (保持原值)

3. 必需参数补充

# 实时消耗接口
params["filtering"] = []  # 必需参数

# 定向标签报表
params["type"] = "GENDER"  # 必需参数，默认值

开发

项目结构

app/
├── main.py              # FastAPI应用入口
├── config.py            # 配置管理
├── dependencies.py      # 共享依赖项
├── routes/              # API路由
│   ├── reports.py       # 报表接口
│   ├── accounts.py      # 账户接口
│   └── ...
├── services/            # 业务服务
│   └── gdt_client.py    # GDT API客户端
└── utils/               # 工具模块
    ├── exceptions.py    # 异常定义
    └── logger.py        # 日志配置

添加新接口

1. 在对应的路由文件中添加接口
2. 使用 get_gdt_client 依赖注入
3. 参考现有接口的参数处理方式

测试

# 测试参数序列化
python test_fixes.py

# 测试接口
curl "http://localhost:8000/reports/daily?account_id=123&start_date=2025-01-01&end_date=2025-01-31"

版本历史

• v1.0.0 - 初始版本，支持核心报表接口
• v1.1.0 - 修复参数序列化和level映射问题
• v1.2.0 - 增加安全认证和MCP集成支持

许可证

MIT License