# API
## 1\. API介绍
易观方舟提供一系列的开放API, 方便方舟用户及生态合作伙伴利用API开展基于方舟分析模型的应用程序开发、细粒度的数据应用、自定义的分析模型与OLAP分析,多系统数据源融合治理等。
方舟API目前有四个大类:
* [分析类API](api-analytics/README.md):用于获取各种分析模型结果,主要包事件分析、留存分析、转化漏斗、属性分析等常用分析模型,主要用于在其他渠道查看方舟统计分析或者对统计指标做二次开发的场景,例如客户自己的BI系统、展示大屏等。
* [用户类API](api-cohort/README.md):主要包括用户分群的创建、删除,以及获取单个分群的用户明细,获取单个用户的用户属性等,适用于对接客户自己的消息推送系统或者对人群数据进行二次分析等场景。
* [项目类API](api-manage-project/README.md):主要包括在项目级别下的一些常用功能类API,例如获取项目元事件、属性等基础信息,以及给项目成员分配权限等,常用于对接客户自己的用户权限体系,以便能够简化对成员进行方舟项目授权等手工操作。
* [平台类API](api-manage-enterprise/README.md):主要包括项目创建、项目数据流的启停、企业成员管理等,主要用于对接客户自己的业务系统,可以通过API 实现对方舟项目和用户的管理和维护。
>[info] API 章节涉及较多的技术细节,适用于有相关开发经验的开发者参考。
> 如果对文档内容有疑惑,可以咨询您的项目经理获取相应的技术协助。
## 2.调用方法
API 采用标准的 HTTP 方式,调用的 URL 为:
```
http://{$WEB_URL}/{$API_URL}
```
**$WEB\_URL** :和访问方舟产品的 URL一致。
**$API\_URL** :具体的 API 地址。
>[info] 如果私有化部署的过程中修改了Nginx的默认配置,或通过CDN等访问方舟,则请咨询相关人员获取配置信息。
## 3.接口认证
所有接口调用时都需要在header中带上认证信息,接口认证分为平台接口认证和项目接口认证两种。
### 2.1 项目接口认证
用于指定项目的相关查询和操作,每个项目的AccessKey只能访问当前项目API,和项目标识appKey一起使用。参数名称使用 token,**非**平台管理API\*\* \*\*的接口都使用项目认证。示例如下:
```
Request Headers
Content-Type: application/json
token: {$API_ACCESSKEY}
appKey: {$APP_KEY}
```
**$APP\_KEY**为项目标识,对应方舟系统中的AppKey。
**$API\_ACCESSKEY** 为项目API调用的验证标识。可在方舟中【管理】 - 【项目概览】模块中获取,截图如下:

### 2.2 平台接口认证
主要用于项目权限之上的相关查询和操作,参数名称使用 **xtoken**,在 [平台管理API](https://docs.analysysdata.com/uba-docs/2495000) 的接口中有使用。示例如下:
```
Request Headers
Content-Type: application/json
xtoken: {$SUPER_TOKEN}
```
**$SUPER\_TOKEN** 为企业级接口授权码。在【4.5.3版本】此之前版本联系运维获取,4.5.3版本可在方舟中【企业平台管理】 - 【企业概览】模块中获取,截图如下:

## 4.调用示例
获取到 $WEB\_URL 地址和token后,就可以使用任意HTTP Client进行 API 调用,非特殊说明都使用RequestBody方式传参,例如使用 curl工具访问事件分析,例子如下:
```java
curl -H "Content-Type:application/json" -H "token:4113c9cad1c301113783f433e254888c" -H "appKey:31abd9593e9983ec" -X POST --data '{
"measures":[
{
"filter":{
"conditions":[
{
"expression":"event.$Anything.$platform",
"function":"EQ",
"params":[
"JS"
]
}
],
"relation":"and"
},
"expression":"event.$Anything",
"aggregator":"TRIGGER_USER_COUNT"
}
],
"filter":{
"conditions":[
{
"expression":"event.$Anything.$platform",
"function":"EQ",
"params":[
"JS",
"iOS",
"Android"
]
}
],
"relation":"AND"
},
"byFields":[
{
"expression":"event.$Anything.$screen_width",
"buckets":[
600,
800
]
}
],
"crowds":[
"$ALL"
],
"fromDate":"2019-06-18",
"toDate":"2019-06-20",
"samplingFactor":1,
"useCache":true,
"unit":"DAY"
}' http://127.0.0.1:4005/uba/api/events/analyze
```
## 5\. 接口状态码说明
API调用是否成功都是通过HTTP状态码来识别,接口直接返回结果结构体,以下是系统对应的状态码。
| HttpStatus | HttpMessage | 描述 |
| --- | --- | --- |
| 200 | OK | 接口调用成功 |
| 400 | Bad Request | 请求失败,如参数为空 |
| 401 | Unauthorized | 认证失败,如token/appKey错误 |
| 404 | Not Found | 接口不存在 |
| 415 | Unsupported Media Type | HTTP协议的错误,如Content-Type |
| ~~498~~ | ~~Request method not supported~~ | ~~HTTP请求方法不支持【在4.5.1版本取消,用 400代替】~~ |
| ~~499~~ | ~~The maximum limit has been reached~~ | ~~超出限制,如项目个数超出限额,分群个数超出限额【在4.5.1版本取消,用 501代替】~~ |
| 500 | Internal Server Error | 接口处理异常 |
| 501 | Not Implemented | 接口未完成操作,如项目个数超出限额,分群个数超出限额,对象已存在【在4.5.1版本中新增】 |
| 503 | Service Unavailable | 连接服务不可用,如presto连接异常,数据库连接异常 |
>[info] * HttpStatus 不等于 *200* 时,会返回 json 格式的结果,结果中包含code、msg、data三部分。
> * HttpStatus=400时,会返回详细的错误内容(data),data中会罗列具体的错误参数。
> * 在HttpStatus=501时,可根据接口返回的code区分具体的错误信息,如下:
| HttpStatus | code | 描述 |
| --- | --- | --- |
| 501 | 501 | 资源超出业务限制,如项目个数超出限额,分群个数超出限额 |
| 501 | 50101 | 对象已存在,如注册用户邮箱重复、分群名称重复 |
| 501 | 50102 | 对象已存在,但是已被禁用 |
| 501 | 50103 | PRESTO 资源不足,调用接口前可以通过接口获取当前presto使用情况 |
| 501 | 50104 | 查询并发数达到上限 |
以下是Postman调用结果示例:

## 6\. 指定操作用户
管理类API涉及到新增/修改/删除,为了区分谁操作,在接口传参中都需要带当前操作人对应的邮箱,如果不用区分谁操作,默认为一个方舟中存在的邮箱即可。参数名为loginUser,通过Path方式传参。示例如下:
```java
?loginUser=操作用户的邮箱地址
```
>[info] 以上内容没有解答我的问题?[点击我来反馈](https://support.qq.com/products/118522/) 🚀
- 产品简介
- 快速上手
- Step 1 安装部署
- Step 2 激活系统创建项目
- Step 3 开启您的分析旅程
- 1. 集成 SDK
- 2. 可视化埋点
- 3. 创建分析模型
- 附:埋点方案设计
- 附:数据分析思路
- 产品更新日志
- V5.5 新增LTV分析功能等
- V5.3 UI 升级、分布分析重构、维度表动态更新、细节优化等
- V5.2 新增归因分析、消息中心、重构埋点方案、优化看数据体验……
- V5.1.0317 体验优化& Bug修复
- V5.1 升级可视化埋点、增强权限控制……
- Part I 产品功能说明
- 名词解释
- 指标说明
- 看板
- 5.3.3 看板 UI 重构
- 分析
- 事件分析
- 渠道分析
- 渠道相关名词解释
- 来源识别规则
- 搜索引擎
- 社交媒体
- 小程序场景值
- Session 分析
- Session 规则
- 实时分析
- 留存分析
- 转化漏斗
- 智能路径
- 归因分析
- 热图分析
- Web/H5 热图
- APP 热图
- 分布分析
- 间隔分析
- 属性分析
- LTV 分析
- 多主体分析
- 自定义查询
- 用户
- 用户分群
- 用户探查
- 用户标签
- 标签体系应用概览
- 标签体系
- 标签生命周期管理
- 标签加工
- 如何自定义SQL创建标签
- 单用户档案
- 运营
- 广告跟踪
- 微信小程序渠道追踪
- 预置广告媒介和渠道
- App 推广监测(Beta版本)
- 电子邮件(即将下线)
- 短信(即将下线)
- 消息通知(即将下线)
- 项目管理
- 项目概览
- 项目角色管理
- 项目成员管理
- 数据接入管理
- 埋点方案
- 可视化埋点
- 集成SDK接入数据
- 数据验证
- 用户数据导入
- 微信小程序全埋点事件定义
- 元数据管理
- 元事件
- 虚拟事件
- 事件属性
- 用户属性
- Session 管理
- 页面组管理
- 维度表
- 服务集成配置
- 监控告警
- 智能监控
- 自定义监控
- 平台管理
- 企业概览
- 项目管理
- 成员管理
- 安全设置
- 企业设置
- 日志管理
- 帐号设置
- Part II 技术文档
- 技术接入准备工作
- 部署环境检测工具
- 数据模型
- 数据格式
- 预置事件和属性
- App预置事件/属性
- JS 预置事件/属性
- 如何准确识别用户
- 如何设计埋点方案
- 分平台上报数据 vs 跨平台打通
- SDK 指南
- Android SDK
- 快速集成
- 全埋点模块
- 消息推送模块
- Android Hybrid模式
- SDK Gradle集成方式
- 多渠道打包
- 易观小工具
- 合规相关
- iOS SDK
- 快速集成
- 全埋点介绍
- iOS Hybrid模式
- 消息推送模块
- JS SDK
- 快速集成
- JS SDK基础版
- JS SDK插件
- uni-app SDK
- 快速集成
- 打包原生APP
- 开启移动端全埋点
- uni-app SDK标准版
- 微信小程序 SDK
- 快速集成
- 微信小程序标准版
- 微信小程序插件版
- 微信小程序通用框架版
- 支付宝小程序 SDK
- 支付宝小程序标准版
- 支付宝小程序通用框架版
- 字节跳动小程序 SDK
- 字节跳动小程序标准版
- 字节跳动小程序通用框架版
- 百度小程序 SDK
- 百度小程序标准版
- 百度小程序通用框架版
- 钉钉小程序 SDK
- 钉钉小程序标准版
- 钉钉小程序通用框架版
- QQ小程序 SDK
- QQ小程序标准版
- QQ小程序通用框架版
- 快应用 SDK
- 华为WeCode小程序
- WeCode SDK 标准版
- WeCode SDK插件
- PhoneGap SDK
- mPaaS SDK
- ReactNative SDK
- Flutter SDK
- Java SDK
- Python SDK
- PHP SDK
- C++ SDK
- C# SDK
- Node JS SDK
- Lua SDK
- Golang SDK
- SDK FAQ
- identify与alias的区别
- 爬虫数据如何识别?
- 页面停留如何获取时间?
- 如果获取SDK及更新日志
- 代码埋点和无埋点有什么区别
- Web页面中发现丢失某一个事件
- 自研 SDK 注意事项
- 页面时长统计功能
- 飞书小程序 SDK
- 飞书小程序标准版
- 飞书小程序通用框架版
- Unreal Engine SDK
- 数据验证
- 客户端埋点验证
- Debug 数据验证
- 数据入库验证
- 数据导入
- 接口导入
- JAVA工具包
- 标准json文件导入
- csv格式导入
- 数据导入FAQ
- 数据导出
- JAVA工具包
- 事件数据导出
- 用户数据导出
- 直接从Kafka中消费数据
- 使用程序访问数据库
- 脚本工具
- API
- 分析API
- 事件分析
- 留存分析
- 自定义查询
- 转化漏斗
- 属性分析
- Session分析
- 渠道分析
- 分布分析
- 用户API
- 分群查询
- 用户档案
- 分群管理
- 管理API
- 权限管理
- 元数据管理
- 埋点方案管理
- 维度表管理
- 运营API
- 广告跟踪
- APP推广监测
- 平台管理API
- 项目管理
- 成员管理
- 第三方登录
- OAuth2.0登录
- LDAP登录
- GDPR 合规
- Part III 常见问题
- License 许可
- 产品试用及采购
- 参与贡献