明日DMP鉴权技能

概述

本技能是明日DMP技能体系的核心基础设施，提供两大核心功能：

1. 凭证管理：配置、验证和管理明日DMP的Access Key和Secret Key
2. 统一API调用：为所有明日DMP业务技能提供统一的API签名生成和HTTP请求封装

架构说明

集中式API调用架构

┌─────────────────────────────────────────────────────────────┐
│                     明日DMP技能体系                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │ 人群圈选技能  │  │ 人群洞察技能  │  │ 人群投放技能  │    │
│  │              │  │              │  │              │    │
│  │ 业务脚本      │  │ 业务脚本      │  │ 业务脚本      │    │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘    │
│         │                 │                 │            │
│         └─────────────────┼─────────────────┘            │
│                           │                              │
│                           ▼                              │
│              ┌────────────────────────┐                  │
│              │   mingdata-dmp-auth    │                  │
│              │   (鉴权技能)            │                  │
│              ├────────────────────────┤                  │
│              │ • 凭证管理              │                  │
│              │ • 签名生成              │                  │
│              │ • HTTP请求封装          │                  │
│              │ • 错误处理              │                  │
│              └────────┬───────────────┘                  │
│                       │                                  │
│                       ▼                                  │
│              ┌────────────────────────┐                  │
│              │  明日DMP开放平台API     │                  │
│              └────────────────────────┘                  │
└─────────────────────────────────────────────────────────────┘

调用流程

1. 业务技能调用本技能的scripts/minri_dmp_api.py脚本
2. 鉴权技能加载凭证、生成签名、发送HTTP请求
3. 返回结果给业务技能，并设置相应的退出码

核心脚本

1. setup_credentials.py - 凭证配置脚本

功能：引导用户配置Access Key和Secret Key

使用方式：

python setup_credentials.py

交互流程：

1. 展示凭证申请指引（包含申请入口、申请步骤、凭证格式说明）
2. 提示用户输入Access Key
3. 提示用户输入Secret Key
4. 验证凭证格式（非空检查）
5. 保存凭证到~/.mingdata_dmp_credentials
6. 设置文件权限为600（仅所有者可读写）

退出码：

• 0：配置成功
• 1：配置失败（用户取消或输入错误）

2. scripts/minri_dmp_api.py - 统一API调用模块

功能：提供统一的API签名生成和HTTP请求封装

使用方式：

python minri_dmp_api.py \x3Cendpoint> \x3Crequest_body_json>

参数说明：

• endpoint：API路径（如/audience/manage/list）
• request_body_json：请求体JSON字符串

示例：

# 查询人群列表
python minri_dmp_api.py /audience/manage/list '{"current":1,"pageSize":10}'

# 创建组合人群
python minri_dmp_api.py /audience/manage/combine/create '{"name":"测试人群","trackType":"MOBILE","idTypes":["MD5_IDFA"],"data":[...]}'

核心功能：

1. 凭证加载：

   • 从~/.mingdata_dmp_credentials读取AK/SK
   • 验证凭证文件存在性和完整性
   • 凭证缺失时返回特定退出码（2），触发业务技能引导用户配置

2. 签名生成：

   • 生成10位秒级时间戳
   • 生成4位随机数
   • 计算32位大写MD5签名：MD5(timestamp + randStr + secret_key)

3. HTTP请求：

   • 构建完整URL：BASE_URL + endpoint + ?ts=\x3C>&randStr=\x3C>&accessKey=\x3C>&sign=\x3C>
   • 设置请求头：Content-Type: application/json; charset=UTF-8
   • 发送POST请求
   • 解析响应结果

4. 错误处理：

   • 凭证错误：退出码2，提示调用鉴权技能配置
   • HTTP错误：退出码5，输出HTTP状态码和错误信息
   • 网络错误：退出码6，输出网络异常信息
   • API业务错误：退出码4，输出API返回的错误信息
   • 成功：退出码0，输出API返回的完整结果

退出码说明：

• 0：API调用成功
• 1：参数错误（缺少必需参数或JSON格式错误）
• 2：凭证不存在或无效（需要调用setup_credentials.py配置）
• 3：鉴权技能未安装（业务技能找不到本技能）
• 4：API返回业务错误（如参数校验失败、人群不存在等）
• 5：HTTP错误（如404、500等）
• 6：网络错误或未知错误

技能依赖关系

本技能是以下技能的必需依赖

• 明日dmp人群圈选：所有人群圈选功能都需要通过本技能调用API
• 明日dmp人群洞察：所有人群洞察功能都需要通过本技能调用API
• 明日dmp人群投放：所有人群投放功能都需要通过本技能调用API

依赖检查机制

业务技能在调用API前会检查本技能是否已安装：

auth_skill_path = Path.home() / ".skills" / "mingdata-dmp-auth" / "scripts" / "minri_dmp_api.py"

if not auth_skill_path.exists():
    print("未找到鉴权技能，请先安装mingdata-dmp-auth技能")
    sys.exit(3)

凭证配置说明

🌟 推荐方式：环境变量注入（最安全）

优势：

• ✅ 不在文件中硬编码明文，安全性最高
• ✅ 跨对话共享，一次配置永久使用
• ✅ 全局生效，所有明日DMP技能自动使用

配置方法：

# 设置环境变量（推荐使用 DMP_AK 和 DMP_SK）
export DMP_AK="your_access_key_here"
export DMP_SK="your_secret_key_here"

代码中使用：

import os

# AK 和 SK 通过环境变量注入，不会在此文件中硬写明文
AK = os.environ["DMP_AK"]
SK = os.environ["DMP_SK"]

永久配置（可选）：

将环境变量添加到 ~/.bashrc 或 ~/.zshrc：

echo 'export DMP_AK="your_access_key_here"' >> ~/.bashrc
echo 'export DMP_SK="your_secret_key_here"' >> ~/.bashrc
source ~/.bashrc

备选方式：文件存储

凭证文件位置：~/.mingdata_credentials 或 workspace/.mingdata_credentials

凭证文件格式：

{
  "access_key": "your_access_key_here",
  "secret_key": "your_secret_key_here"
}

配置方法：

python scripts/minri_dmp_api.py save-credentials \x3Caccess_key> \x3Csecret_key>

凭证加载优先级

系统按以下优先级加载凭证：

安全措施

1. 环境变量注入：推荐使用环境变量，避免明文存储
2. 文件权限：凭证文件权限设置为600（仅所有者可读写）
3. 隐藏文件：使用.开头的隐藏文件，避免误操作
4. 本地存储：凭证仅存储在本地，不会上传到云端
5. 集中管理：所有明日DMP技能共享同一份凭证，避免重复配置

凭证申请指引

申请入口：

• 登录明日DMP平台：https://open.mingdata.com
• 进入"开放平台" → "API凭证管理"

申请步骤：

1. 点击"创建凭证"按钮
2. 填写凭证用途说明
3. 提交申请，等待审核
4. 审核通过后，复制Access Key和Secret Key

安全提示：

• 请妥善保管您的凭证，不要泄露给他人
• 如发现凭证泄露，请立即在平台上重置凭证
• 定期更换凭证，提高安全性

使用示例

场景1：首次使用明日DMP技能

用户：帮我圈选一个人群
  ↓
业务技能检测到凭证不存在
  ↓
业务技能：检测到您尚未配置明日DMP凭证，正在调用鉴权技能...
  ↓
鉴权技能：展示凭证申请指引，引导用户输入AK/SK
  ↓
用户：输入Access Key和Secret Key
  ↓
鉴权技能：凭证配置成功
  ↓
业务技能：继续执行人群圈选任务

场景2：凭证已配置，正常调用API

用户：查询人群列表
  ↓
业务技能调用鉴权技能的minri_dmp_api.py
  ↓
鉴权技能：加载凭证 → 生成签名 → 发送HTTP请求
  ↓
明日DMP API：返回人群列表数据
  ↓
鉴权技能：输出结果，退出码0
  ↓
业务技能：展示人群列表给用户

场景3：凭证失效，需要重新配置

用户：创建人群
  ↓
业务技能调用鉴权技能的minri_dmp_api.py
  ↓
鉴权技能：加载凭证 → 生成签名 → 发送HTTP请求
  ↓
明日DMP API：返回401认证失败
  ↓
鉴权技能：输出错误信息，退出码4
  ↓
业务技能：检测到认证失败，引导用户重新配置凭证
  ↓
用户：重新输入Access Key和Secret Key
  ↓
业务技能：重试创建人群任务

技术说明

API基础配置

• BASE_URL：https://open.mingdata.com/api/open-api
• 请求方法：POST
• 请求头：Content-Type: application/json; charset=UTF-8
• 超时时间：30秒

签名算法

def generate_signature(timestamp, rand_str, secret_key):
    """
    签名算法：32位大写MD5(timestamp + randStr + secret_key)
    
    Args:
        timestamp: 10位秒级时间戳
        rand_str: 4位随机数
        secret_key: SK密钥
    
    Returns:
        str: 32位大写MD5签名
    """
    sign_str = f"{timestamp}{rand_str}{secret_key}"
    return hashlib.md5(sign_str.encode()).hexdigest().upper()

URL构建

完整URL格式：
https://open.mingdata.com/api/open-api{endpoint}?ts={timestamp}&randStr={rand_str}&accessKey={access_key}&sign={sign}

示例：
https://open.mingdata.com/api/open-api/audience/manage/list?ts=1234567890&randStr=5678&accessKey=a1b2c3d4...&sign=A1B2C3D4...

常见问题

Q1：如何重新配置凭证？

A：直接运行python setup_credentials.py，输入新的Access Key和Secret Key即可覆盖旧凭证。

Q2：凭证文件丢失怎么办？

A：业务技能会自动检测凭证缺失，并引导您重新配置。您也可以手动运行python setup_credentials.py。

Q3：多个明日DMP技能需要分别配置凭证吗？

A：不需要。所有明日DMP技能共享同一份凭证（~/.mingdata_dmp_credentials），只需配置一次。

Q4：如何验证凭证是否有效？

A：运行任意明日DMP业务技能（如查询人群列表），如果返回认证失败，说明凭证无效，需要重新配置。

Q5：本技能可以单独使用吗？

A：可以。您可以直接调用scripts/minri_dmp_api.py脚本测试API调用，但通常建议通过业务技能（人群圈选、人群洞察等）使用。

后续规划

• 支持凭证有效期检查和自动刷新
• 提供凭证加密存储选项
• 支持多账号凭证管理
• 提供API调用日志记录功能
• 支持API调用频率限制和重试机制