分析API

分析模型数据获取

1. 调用方法

采用标准的 HTTP 方式，调用的URL为访问网站的URL+API地址，详情见 API。

2. 通用参数

2.1 表达式

API中使用的指标、过滤条件、维度等都会使用表达式，所以几乎所有API都会使用表达式。表达式分为事件表达式和属性表达式两种，对应的参数名称都为expression。

2.1.1 事件表达式

事件表达式格式为 event.事件ID 的方式，如 注册事件 的事件表达式为：

"expression": event.signup

任意事件由系统预置，事件ID为 $Anything，任意事件 表达式为：event.$Anything

2.1.2 属性表达式

属性包括事件属性和用户属性，在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

2.2 过滤条件

过滤条件主要用来筛选符合期望的某些事件结果或者用户结果，根据条件使用的场景不同，能选择到的过滤内容也不同：

• 如果过滤条件应用在某个事件下，可以使用通用事件属性、用户属性和这个事件独有的事件属性。

• 如果过滤条件是全局的，针对于所有事件生效，可以使用通用事件属性、用户属性和所有事件都有（根据属性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"
}                         

2.2.1 条件之间的关系

各个条件之间的关系只支持AND/OR。

• AND：条件之间都是且的关系，查询的数据需要满足所有条件。

• OR：条件之间都是或的关系，查询的数据只要满足其中一个条件即可。

2.2.2 条件操作符号

条件操作符主要用在过滤条件中，不同属性数值类型，支持不同操作运算符。

字符串

• 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。

2.3 选择用户分群

查询某个分群的数据，对应分群code。如：

"crowds":["$ALL"]

1、默认为全部用户，全部用户 为 $ALL。自定义分群code 获取参见 获取所有用户分群。

2、当前所有API不支持多分群对比。

2.4 查询时间范围

格式固定为 yyyy-MM-dd，查询都是 大于等于 开始时间，小于等于 结束时间

//开始时间
"fromDate": "2019-06-18"
//结束时间
"toDate": "2019-06-24"

2.5 选择抽样

抽样因子，范围为1-64， 1表示全量数据，64 表示1/64 ，如抽样二分之一：

"samplingFactor":2

2.6 细分维度查看

查询结果按照事件属性/用户属性分组进行查看，不传为不分组。事件分析支持多维度查看，其余图表分析只支持单维度。

"byFields":[
    {
        //按照屏幕高度分组
        "expression":"event.$Anything.$screen_width",
        //是否使用分桶条件查看结果，只有属性为数值类型时才能使用
        //【数值类型时必填】这里表示按照 -∞ ~ 600，600 ~ 800，800 ~ +∞ 三个区间查看
        "buckets":[
            600,
            800
        ],
        // 【日期类型时必填】这里表示不汇总按照按日统计
        "byTimeType":"DAY"
    }
]

特殊说明：

1、分桶（buckets）只适用于数值类型属性，当前只支持自定义区间。

2、日期类型属性，只支持默认统计，默认为不分组，支持按照不同 时间粒度枚举 查看。

3、多维度使用 byFields:[]，单维度使用 byField:{}，内部参数结构和示例一致。

2.7 时间粒度

查询结果可以选择按日（DAY）/周（WEEK）/月（MONTH）/小时（HOUR）/分钟（MINUTE）查看，如按日查看：

"unit":"DAY"

在按小时/分钟时间粒度查看时，查询时间范围必须是单天

2.8 使用缓存

是否使用缓存，true/false

• true：使用缓存，取上一次结果，如果缓存失效或者结果不存在，会重新查询。

• false：不取缓存，直接查询。

"useCache": true

2.9 时间枚举

在API中，很多地方（如留存周期、漏斗转化周期、事件分析时间粒度）都有涉及到分时间粒度查看，关于时间粒度的参数值统一如下：

• SECOND：秒

• MINUTE：分钟

• HOUR：小时

• DAY：天

• WEEK：周

• MONTH：月

• QUARTER：季度

• YEAR：年

3. 接口请求参数快捷获取

因为大部分查询API的输入参数结构都比较复杂，在前期使用或者参数较复杂时不好拼装参数。所以在方舟产品中，对应图表分析中提供了根据页面选择的条件生成API输入参数的入口，点击即可获取需要的参数。

步骤：在分析导航中选择对应分析模块进入，选择需要查询的内容，点击右侧区域 获取API接口参数的图标获取参数。以事件范围为例：

API在4.3.4之后的版本（含4.3.4）中开放，API AccessKey和参数快捷获取入口也在方舟产品中同步添加。

4. 接口列表

分类	接口	新增版本	修改版本
分析模型	事件分析	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