分析API
分析模型数据获取
API中使用的指标、过滤条件、维度等都会使用表达式,所以几乎所有API都会使用表达式。表达式分为事件表达式和属性表达式两种,对应的参数名称都为expression。
事件表达式格式为 event.事件ID 的方式,如 注册事件 的事件表达式为:
"expression": event.signup
任意事件由系统预置,事件ID为 $Anything,任意事件 表达式为:event.$Anything
属性包括事件属性和用户属性,在5.2版本开始支持自定义表达式、标签属性和维度表属性。
- 事件属性
事件属性使用 event.事件ID.属性ID 的方式,例如表示 注册事件的注册方式 这个事件属性的表达式为
"expression": event.signup.signuptype
- 用户属性
用户属性使用 user.用户属性ID 的方式,例如表示 用户注册时间 这个用户属性的表达式如下:
"expression": user.$signup_time
- 自定义表达式
自定义表达式使用 formula.表达式ID 的方式,配合页面获取参数使用
- 用户标签属性
用户标签使用 tag.标签CODE.标签版本 的方式,标签版本可不指定,为空时取最新版本,表达式如下:
不指定版本号:
"expression": tag.tag_code1
指定版本号:
"expression": tag.tag_code1.2020-11-01
- 事件维度表属性
事件属性维度表使用 dim.事件ID.维度表.维度属性 的方式
如基于 SDK类型 $lib 创建了一个维度表,维度表名为:dim_lib_info
维度属性包含:
$lib (关联字段) | name | type |
JS | WEB | 客户端 |
iOS | 苹果 | 客户端 |
Android | 安卓 | 客户端 |
java | JAVA | 服务端 |
如果是根据维度表的关联属性 type进行分析,表达式如下:
"expression": dim.$Anything.dim_lib_info.type
如果是根据维度表的关联属性 name 进行分析,表达式如下:
"expression": dim.$Anything.dim_lib_info.name
过滤条件主要用来筛选符合期望的某些事件结果或者用户结果,根据条件使用的场景不同,能选择到的过滤内容也不同:
- 如果过滤条件应用在某个事件下,可以使用通用事件属性、用户属性和这个事件独有的事件属性。
- 如果过滤条件是全局的,针对于所有事件生效,可以使用通用事件属性、用户属性和所有事件都有(根据属性ID判断)的事件属性。
过滤条件使用参数名称为flter,参数格式为JSON,如下:
"filter":{
//过滤条件列表,可以输入多个
"conditions": [
{
//条件,如任意事件平台等于JS或iOS
"expression": "event.$Anything.$platform",
//条件操作符号
"function": "EQ",
// 条件的参数,根据不同的操作符可以有一个或者多个,数组格式
"params": ["JS","iOS"]
},
{
// SDK版本等于4.0.4.001
"expression": "event.$Anything.$lib_version",
"function": "EQ",
"params": ["4.0.4.001"]
}
],
//条件之间的关系,只能是 且(AND)/ 或(OR)
"relation": "AND"
}
各个条件之间的关系只支持AND/OR。
- AND:条件之间都是且的关系,查询的数据需要满足所有条件。
- OR:条件之间都是或的关系,查询的数据只要满足其中一个条件即可。
条件操作符主要用在过滤条件中,不同属性数值类型,支持不同操作运算符。
字符串
数值
布尔
日期
集合
- EQ等于,当params一个值时,表示等于这个值的才满足;当params有多个值时,表示满足其中一项即可, 相当于in。
- NOT_EQ不等于,当params一个值时,表示不等于这个值的都满足;当params有多个值时,表示不能是其中任意一项,相当于not in。
- CONTAIN包含 ,属性值包含指定字符串,相当于 like %params[0]%。
- NOT_CONTAIN不包含,属性 值不包含指定字符串,相当于not like %params[0]%。
- NOT_NULL有值,属性值有值 ,相当于 is not null。
- NULL无值,属性值无值,相当于 is null。
- EQ等于,当params一个值时,表示等于这个值的才满足;当params有多个值时,表示满足其中一项即可,相当于in。
- NOT_EQ不等于,当params一个值时,表示不等于这个值的都满足;当params有多个值时,表示不能是其中任意一项,相当于not in。
- GT大于。
- GTE大于等于。
- LT小于。
- LTE小于等于。
- RANGE区间,在某个数据区间内的数值,相当于 >= params[0] and <= params[1] 或者 between params[0] and params[1]。
- NOT_NULL有值,属性值有值,相当于 is not null。
- NULL无值,属性值无值,相当于 is null。
- TRUE为真。
- FALSE为假。
- NOT_NULL有值,属性值有值,相当于 is not null。
- NULL无值,属性值无值,相当于 is null。
- ABSOLUTE_TIME绝对时间,在某个具体的时间范围,相当于 >= params[0] and <= params[1] 或者 between params[0] and params[1]。{"expression": "user.$signup_time","function": "ABSOLUTE_TIME","params": ["2019/05/01 00:00","2019/05/31 00:00"]}
- RELATIVE_TIME_OF_CUURENT在相对当前时间点。四天之内{"expression": "user.$signup_time","function": "RELATIVE_TIME_OF_CUURENT","params": ["4", "day", "within"]}四天之前{"expression": "user.$signup_time","function": "RELATIVE_TIME_OF_CUURENT","params": ["4", "day", "before"]}
- RELATIVE_TIME_RANGE_CUURENT在相对当前的时间区间。在过去3天到过去1天之内{"expression": "user.$signup_time","function": "RELATIVE_TIME_RANGE_CUURENT","params": ["3","1","day"]}
- RELATIVE_TIME_OF_EVENT相对于事件发生时间。 如注册时间在事件发生时间之后(after)/之前(before)3天(day)/小时(hour)/分(minute)/秒(second){"expression": "user.$signup_time","function": "RELATIVE_TIME_OF_EVENT","params": ["after","3","day"]}注册时间在事件发生时间当天(day)/当周(week)/当月(month){"expression": "user.$signup_time","function": "RELATIVE_TIME_OF_EVENT","params": ["day"]}
- NOT_NULL有值,属性值有值,相当于 is not null。
- NULL无值,属性值无值,相当于 is null。
- EQ等于,集合只取第一个值进行完整匹配。
- CONTAIN包含,集合里面包含某个值。
- NOT_CONTAIN不包含,集合里面不包含某个值。
- NOT_NULL有值,属性值有值,相当于 is not null。
- NULL无值,属性值无值,相当于 is null。
查询某个分群的数据,对应分群code。如:
"crowds":["$ALL"]
2、当前所有API不支持多分群对比。
格式固定为 yyyy-MM-dd,查询都是 大于等于 开始时间,小于等于 结束时间
//开始时间
"fromDate": "2019-06-18"
//结束时间
"toDate": "2019-06-24"
抽样因子,范围为1-64, 1表示全量数据,64 表示1/64 ,如抽样二分之一:
"samplingFactor":2
查询结果按照事件属性/用户属性分组进行查看,不传为不分组。事件分析支持多维度查看,其余图表分析只支持单维度。
"byFields":[
{
//按照屏幕高度分组
"expression":"event.$Anything.$screen_width",
//是否使用分桶条件查看结果,只有属性为数值类型时才能使用
//【数值类型时必填】这里表示按照 -∞ ~ 600,600 ~ 800,800 ~ +∞ 三个区间查看
"buckets":[
600,
800
],
// 【日期类型时必填】这里表示不汇总按照按日统计
"byTimeType":"DAY"
}
]
特殊说明:
1、分桶(buckets)只适用于数值类型属性,当前只支持自定义区间。
3、多维度使用 byFields:[],单维度使用 byField:{},内部参数结构和示例一致。
查询结果可以选择按日(DAY)/周(WEEK)/月(MONTH)/小时(HOUR)/分钟(MINUTE)查看,如按日查看:
"unit":"DAY"
在按小时/分钟时间粒度查看时,查询时间范围必须是单天
是否使用缓存,true/false
- true:使用缓存,取上一次结果,如果缓存失效或者结果不存在,会重新查询。
- false:不取缓存,直接查询。
"useCache": true
在API中,很多地方(如留存周期、漏斗转化周期、事件分析时间粒度)都有涉及到分时间粒度查看,关于时间粒度的参数值统一如下:
- SECOND:秒
- MINUTE:分钟
- HOUR:小时
- DAY:天
- WEEK:周
- MONTH:月
- QUARTER:季度
- YEAR:年
因为大部分查询API的输入参数结构都比较复杂,在前期使用或者参数较复杂时不好拼装参数。所以在方舟产品中,对应图表分析中提供了根据页面选择的条件生成API输入参数的入口,点击即可获取需要的参数。
步骤:在分析导航中选择对应分析模块进入,选择需要查询的内容,点击右侧区域 获取API接口参数的图标获取参数。以事件范围为例:

API在4.3.4之后的版本(含4.3.4)中开放,API AccessKey和参数快捷获取入口也在方舟产品中同步添加。
分类 | 接口 | 新增版本 | 修改版本 |
分析模型 | 事件分析 | 4.3.4 | 5.1 |
分析模型 | 转化漏斗 | 4.3.4 | 5.1 |
分析模型 | 留存分析 | 4.3.4 | 5.1 |
分析模型 | 属性分析 | 4.5.1 | |
分析模型 | Session分析 | 5.1 | |
分析模型 | 渠道分析 | 5.1.0184 | |
分析模型 | 分布分析 | 5.2 | |
分析模型 | 自定义查询 | 5.0 | |
最近更新 2yr ago