分析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

维度属性包含：

如果是根据维度表的关联属性 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。

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。

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. 接口列表

最后更新于3年前