友盟 API 技能
功能概述
此技能提供友盟开放 API 的完整 Python SDK 封装，用于查询应用的统计数据，包括：
- 新增用户数
- 活跃用户数
- 异常点检测（异动归因报告）
- 其他友盟 UApp API 支持的指标
前置条件
- 友盟账号：需要有效的友盟开发者账号
- 应用 APPKEY：目标应用的友盟 APPKEY
- API 认证：需要 apiKey 和 apiSecurity（从友盟开发者平台获取）
安装依赖
技能已包含完整的友盟 AOP SDK，无需额外安装。
使用方法
1. 配置认证信息
认证信息获取优先级（从高到低）：
- 代码中直接传入的参数
umeng-config.json 配置文件（推荐）- 环境变量
方式一：使用配置文件（推荐）
创建 umeng-config.json 文件，可以放在以下任一位置：
- 当前工作目录
- 用户主目录 (
~/umeng-config.json)
- 技能目录
{
"apiKey": "your_api_key",
"apiSecurity": "your_api_security",
"note": "友盟 API 配置文件 - 请妥善保管，不要提交到版本控制系统"
}
⚠️ 安全提示：建议将配置文件权限设置为仅所有者可读写（chmod 600 umeng-config.json）
方式二：使用环境变量
export UMENG_API_KEY="your_api_key"
export UMENG_API_SECURITY="your_api_security"
方式三：代码中直接设置
import aop
aop.set_default_appinfo(your_api_key, your_api_security)
2. 查询新增用户数
import aop
import aop.api
# 设置友盟 API 服务器
aop.set_default_server('gateway.open.umeng.com')
# 认证信息会自动从 umeng-config.json 或环境变量加载
# 也可以手动设置：aop.set_default_appinfo(apiKey, apiSecurity)
# 查询新增用户
req = aop.api.UmengUappGetNewUsersRequest()
resp = req.get_response(None, appkey="your_appkey", startDate="2026-03-25", endDate="2026-03-25", periodType="daily")
print(f"新增用户数：{resp['newUserInfo'][0]['value']}")
3. 查询活跃用户数
# 查询活跃用户
req = aop.api.UmengUappGetActiveUsersRequest()
resp = req.get_response(None, appkey="your_appkey", startDate="2026-03-25", endDate="2026-03-25", periodType="daily")
print(f"活跃用户数：{resp['activeUserInfo'][0]['value']}")
完整示例
1. 查询基础统计数据
import os
import aop
import aop.api
def query_umeng_stats(appkey, date_str=None):
"""查询友盟应用统计数据"""
if date_str is None:
from datetime import date
date_str = date.today().strftime("%Y-%m-%d")
# 设置友盟 API 服务器
aop.set_default_server('gateway.open.umeng.com')
# 认证信息会自动从 umeng-config.json 或环境变量加载
# 检查是否成功加载
appinfo = aop.get_default_appinfo()
if not appinfo:
raise ValueError("未找到友盟认证信息，请配置 umeng-config.json 或环境变量")
# 查询新增用户
new_users_req = aop.api.UmengUappGetNewUsersRequest()
new_users_resp = new_users_req.get_response(None, appkey=appkey, startDate=date_str, endDate=date_str, periodType="daily")
new_users = new_users_resp['newUserInfo'][0]['value']
# 查询活跃用户
active_users_req = aop.api.UmengUappGetActiveUsersRequest()
active_users_resp = active_users_req.get_response(None, appkey=appkey, startDate=date_str, endDate=date_str, periodType="daily")
active_users = active_users_resp['activeUserInfo'][0]['value']
return {
"date": date_str,
"appkey": appkey,
"new_users": new_users,
"active_users": active_users
}
# 使用示例
if __name__ == "__main__":
result = query_umeng_stats("64abc640a1a164591b48bb0c")
print(f"日期：{result['date']}")
print(f"新增用户：{result['new_users']}")
print(f"活跃用户：{result['active_users']}")
2. 查询异常点检测数据
import os
from umeng_get_outlier_points import get_umeng_outlier_points, format_outlier_report
def query_umeng_outlier(appkey, ds):
"""查询友盟应用异常点数据"""
# 认证信息会自动从 umeng-config.json 或环境变量加载
# 也可以直接传入：get_umeng_outlier_points(appkey, ds, api_key, api_security)
# 查询异常点
outlier_data = get_umeng_outlier_points(appkey, ds)
return outlier_data
# 使用示例
if __name__ == "__main__":
try:
appkey = "59892f08310c9307b60023d0"
ds = "20260322" # YYYYMMDD 格式
outlier_data = query_umeng_outlier(appkey, ds)
print(format_outlier_report(outlier_data))
except Exception as e:
print(f"Error: {e}")
支持的其他 API 接口
SDK 还支持以下接口（位于 aop/api/biz/ 目录）：
UmengUappGetLaunchesRequest - 启动次数UmengUappGetDurationsRequest - 使用时长UmengUappGetRetentionsRequest - 留存率UmengUappGetChannelDataRequest - 渠道数据UmengUappGetVersionDataRequest - 版本数据- 以及更多...
错误处理
常见的异常类型：
aop.ApiError - API 网关返回的错误aop.AopError - 客户端请求前的错误ValueError - 认证信息未找到（检查 umeng-config.json 或环境变量）Exception - 其他未知异常
安全注意事项
- 不要硬编码认证信息：优先使用
umeng-config.json 配置文件或环境变量
- 保护配置文件：将
umeng-config.json 添加到 .gitignore，避免提交到版本控制
- 文件权限：建议设置
chmod 600 umeng-config.json 限制访问
- API 调用频率：友盟 API 有调用频率限制，请合理控制请求频次
技能目录结构
umeng-api/
├── SKILL.md
├── umeng_config.py # 配置管理模块（新增）
├── umeng_get_outlier_points.py # 异常点检测封装
├── aop/ # 友盟 AOP SDK
│ ├── __init__.py # 已更新，支持配置文件加载
│ └── api/
│ ├── __init__.py
│ ├── base.py
│ ├── common/
│ └── biz/ # 所有友盟 API 接口
└── scripts/
使用示例场景
当用户说：
- "查询 APPKEY 为 xxx 的应用今天新增用户数"
- "友盟统计中 xxx 应用的活跃用户是多少"
- "获取 umeng 应用 xxx 的昨日数据"
- "查询 APPKEY 为 xxx 在 YYYY-MM-DD 的异常点报告"
- "获取友盟异动归因报告链接"
技能会自动：
- 从
umeng-config.json 加载认证信息（如果存在）
- 否则从环境变量加载
- 提取 APPKEY，使用当前日期（或指定日期）
- 调用相应 API 并返回结果
配置文件示例
umeng-config.json:
{
"apiKey": "12345678",
"apiSecurity": "your_api_security_here"
}
位置优先级：
./umeng-config.json (当前工作目录)~/umeng-config.json (用户主目录)<skill-dir>/umeng-config.json (技能目录)
