Comment on page
API
易观方舟提供一系列的开放API, 方便方舟用户及生态合作伙伴利用API开展基于方舟分析模型的应用程序开发、细粒度的数据应用、自定义的分析模型与OLAP分析,多系统数据源融合治理等。
方舟API目前有四个大类:
API 章节涉及较多的技术细节,适用于有相关开发经验的开发者参考。
如果对文档内容有疑惑,可以咨询您的项目经理获取相应的技术协助。
API 采用标准的 HTTP 方式,调用的 URL 为:
http://{$WEB_URL}/{$API_URL}
$WEB_URL :和访问方舟产品的 URL一致。
$API_URL :具体的 API 地址。
如果私有化部署的过程中修改了Nginx的默认配置,或通过CDN等访问方舟,则请咨询相关人员获取配置信息。
所有接口调用时都需要在header中带上认证信息,接口认证分为平台接口认证和项目接口认证两种。
用于指定项目的相关查询和操作,每个项目的AccessKey只能访问当前项目API,和项目标识appKey一起使用。参数名称使用 token,非平台管理API 的接口都使用项目认证。示例如下:
Request Headers
Content-Type: application/json
token: {$API_ACCESSKEY}
appKey: {$APP_KEY}
$APP_KEY为项目标识,对应方舟系统中的AppKey。
$API_ACCESSKEY 为项目API调用的验证标识。可在方舟中【管理】 - 【项目概览】模块中获取,截图如下:

项目概览
Request Headers
Content-Type: application/json
xtoken: {$SUPER_TOKEN}
$SUPER_TOKEN 为企业级接口授权码。在【4.5.3版本】此之前版本联系运维获取,4.5.3版本可在方舟中【企业平台管理】 - 【企业概览】模块中获取,截图如下:

企业概览
获取到 $WEB_URL 地址和token后,就可以使用任意HTTP Client进行 API 调用,非特殊说明都使用RequestBody方式传参,例如使用 curl工具访问事件分析,例子如下:
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
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连接异常,数据库连接异常 |
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调用结果示例:

API调用状态示例
管理类API涉及到新增/修改/删除,为了区分谁 操作,在接口传参中都需要带当前操作人对应的邮箱,如果不用区分谁操作,默认为一个方舟中存在的邮箱即可。参数名为loginUser,通过Path方式传参。示例如下:
?loginUser=操作用户的邮箱地址
最近更新 3yr ago