文档中心

查询API

最近更新时间：2024.02.27 11:47:20

首次发布时间：2024.02.27 11:47:20

1. 概述

为了更好的跟企业数据产品打通，更好的发挥数据价值，我们通过开放openapi的方式，提供基于本产品进行二次开发的能力，您可以通过调用openapi获取指标数据，以便集成在其他数据产品中。

2. 查询分析 OpenAPI 说明（SaaS）

2.1 API 定义

Context-Path: /datafinder
Path：/openapi/v1/analysis
Method: POST
Content-type: application/json
Body:
- 请求参数均采用查询 DSL 进行描述
- 数据编码为 UTF-8

Response:
结构说明：

{
    "code": 200, # 返回码，200代表查询返回正确，非200请参考返回消息中的message
    "data": [
        {
            "error_message": null, # 错误消息
            "region_info_map": {}, # 区域查询时区域id映射
            "trace_id": "6bcbc580ab144afd8b8a792349ed9a5a", # 链路追踪标识
            "query_id": "a00:p00:c00:q00", # 子查询标识
            "result_status": "SUCCESS", # 子查询状态
            "execute_time": 0, # 子查询执行时间
            "data_item_list": [ # 子查询返回数据
                {
                    "filter_label": null, # 过滤标签
                    "group_by_key": "__all", # 分组key
                    "data": [ # 指标数据
                        142099,
                        145940,
                        139035,
                        148457,
                        154313
                    ],
                    "sum_value_square": 106673323444, # 指标平方和
                    "composed_item_key": null,
                    "item_key": "a00:p00:c00:q00:f00_0",
                    "show_name": "活跃用户数",
                    "sum": 729844, # 指标求和值
                    "event_params": {},
                    "filter_value": null,
                    "event_name_alias": "",
                    "prefix_key": "active_user",
                    "avg": 145968.8, # 指标平均值
                    "result_type_unit": null,
                    "event_show_name": "应用启动",
                    "event_indicator_params": {},
                    "composed_label": null,
                    "show_label": "active_user",
                    "suffix_key": "__all",
                    "origin_profile_params": {},
                    "result_type": "event_users",
                    "attr_value_name": "",
                    "result_type_label": "活跃用户数",
                    "is_disabled": null,
                    "profile_params": {},
                    "event_label": "active_user",
                    "origin_key": "__all",
                    "event_id": null,
                    "is_compute": null,
                    "name": "active_user, __all",
                    "event_name": "app_launch",
                    "group_by_type": "user_attr"
                }
            ],
            "error_code": null,
            "date_index_list": [ # 数据时间索引值，与数据一一对应
                "20200606",
                "20200607",
                "20200608",
                "20200609",
                "20200610"
            ]
        }
    ],
    "message": "success" # 错误消息
}

2.2 OpenAPI SDK使用样例

bc 为创建的 RangersClient, 其初始化请参考 “OpenAPI SDK 使用说明”，各语言的 SDK 都提供了类似的接口。
调用（Python）：

dsl = {
    "version": 3,
    "app_ids": [164***],
    "use_app_cloud_id": True,
    "periods": [
        {
            "granularity": "day",
            "type": "last",
            "last": {
                "amount": 5,
                "unit": "day"
            },
            "timezone": "Asia/Shanghai"
        }
    ],
    "content": {
            "query_type": "event",
            "profile_groups_v2": [],
            "profile_filters": [],
            "queries": [
                [
                    {
                        "event_type": "origin",
                        "show_name": "活跃用户数",
                        "event_name": "app_launch",
                        "groups_v2": [],
                        "filters": [],
                        "show_label": "active_user",
                        "event_indicator": "event_users"
                    }
                ]
            ],
            "option": {
                "skip_cache": False
            }
        }
}

# SaaS 逻辑
resp = bc.data_finder("/openapi/v1/analysis", body=dsl)
print(resp.content)

3. 查询分析 OpenAPI 说明（私有化）

注意

私有化和SaaS有所不同，需要分为两个接口来获取查询结果。

3.1 使用 DSL 查询 API 定义

Context-Path: /datafinder
Path：/openapi/v1/analysis
Method: POST
Content-type: application/json
Body:
- 请求参数均采用查询 DSL 进行描述
- 数据编码为 UTF-8

Response:

{
        "code": 200,
        "message": "success"
        "data":  {
            "result_id": xxx
        }
}

字段含义说明：

Field	Type	Description
result_id	int	查询结果ID

3.2 获取 result_id 查询结果 API 定义

Context-Path: /datafinder
Path：/openapi/v1/analysis/{result_id}/result
Method: GET
Content-type: application/json
Path-parameters:
Parameter
Type
Description
Required
result_id
int
查询结果ID
true
Response:
返回结构同SaaS的查询返回结构

Parameter	Type	Description	Required
result_id	int	查询结果ID	true

3.3 OpenAPI SDK 使用样例

bc 为创建的 RangersClient, 其初始化请参考 “OpenAPI SDK 使用说明”，各语言的 SDK 都提供了类似的接口。
调用（Python）：

dsl = {
    "version": 3,
    "app_ids": [164***],
    "use_app_cloud_id": True,
    "periods": [
        {
            "granularity": "day",
            "type": "last",
            "last": {
                "amount": 5,
                "unit": "day"
            },
            "timezone": "Asia/Shanghai"
        }
    ],
    "content": {
            "query_type": "event",
            "profile_groups_v2": [],
            "profile_filters": [],
            "queries": [
                [
                    {
                        "event_type": "origin",
                        "show_name": "活跃用户数",
                        "event_name": "app_launch",
                        "groups_v2": [],
                        "filters": [],
                        "show_label": "active_user",
                        "event_indicator": "event_users"
                    }
                ]
            ],
            "option": {
                "skip_cache": False
            }
        }
}

# 私有化逻辑
resp = bc.data_finder("/openapi/v1/analysis", body=dsl)
result_id = resp.json()["data"]["result_id"]
resp2 = bc.data_finder(f"/openapi/v1/analysis/{result_id}/result")
print(resp2.content)

4. 如何快速构建 DSL

4.1 获取页面查询的 DSL（推荐）

先打开浏览器的开发者工具（快捷键F12），然后配置好查询条件，查看页面的 datafinder/api/v1/analysis 请求，该请求的body即为该查询的DSL，可以直接拷贝使用。

4.2 使用 OpenAPI 提供的 DSLBuilder

具体参考各语言版本的 OpenAPI SDK。

5. DSL 结构说明

5.1 整体结构

{
    "version": 3, # 版本号
    "app_ids": [164***], # 查询应用唯一标识
    "use_app_cloud_id": True, # 使用应用云唯一标识
    "periods": [ # 查询时间范围定义
        {
            "granularity": "day", # 时间粒度，分钟/小时/天/周/月
            "type": "last", # 时间规则 最近x天或者范围
            "last": { # 最近x天定义
                "amount": 5, # 查询数量
                "unit": "day" # 查询单位
            },
            "timezone": "Asia/Shanghai" # 时区
        }
    ],
    "content": {
            "query_type": "event", # 查询类型
            "profile_groups_v2": [], # 公共属性分组
            "profile_filters": [], # 公共属性过滤
            "queries": [ # 查询定义
                [
                    {
                        "event_type": "origin", # 事件类型，原始事件，虚拟事件，圈选事件
                        "show_name": "活跃用户数", # 查询名称
                        "event_name": "app_launch", # 事件名称
                        "groups_v2": [], # 事件分组
                        "filters": [], # 事件过滤
                        "show_label": "active_user", # 结果标识
                        "event_indicator": "event_users" # 指标名称
                    }
                ]
            ],
            "option": { # 查询可选参数
                "skip_cache": False # 不跳过缓存
            }
        }
}

5.2 字段详细说明

DSL(Domain Specific Language) 简单来讲就是一个json格式的文本，来灵活的定义复杂的查询需求。

5.2.1 顶层结构

{
  "version": 3,             # DSL的版本，本文档中全部为3
  "app_ids": [],            # 目标app，支持多个    
  "use_app_cloud_id": true, # app_ids参数中是否为app_cloud_id。请设置为true，false仅供内部使用
  "periods": [{}],          # 查询时间段，支持多个
  "content": {},            # 具体的查询内容字段,与contents传一个,结构相同
  "contents": [{},{}], 
  "option": {},             # json格式数据，请求相关的选项参数，不同的查询各不相同
  "show_option": {}         # json格式数据，在结果中原样返回
}

字段	类型	取值与含义	是否必须
version	int	DSL的版本，本文档中全部为3。	是
app_ids	int数组	目标app，支持多个。	是
use_app_cloud_id	boolean	指定app_ids参数中是否为app_cloud_id。请设置为true，false仅供内部使用。	否
periods	json的数组	表示查询的时间区间，是一个数组，支持多个时间区间查询。periods的取值字段及格式要求请参见下文的5.2.2 periods字段部分内容。	是
content	json	具体的查询内容字段，仅一个查询内容json时，使用content；有多个查询内容json时，使用contents。格式要求及字段说明详情请参见下文的5.2.3 contene字段部分内容。	是
contents	json数组		是
option	json	请求相关的选项参数，不同的查询各不相同。	否
show_option	json	在结果中原样返回，前端展示使用，不影响查询结果。	是

5.2.2 periods字段

period是字段表示查询的时间区间，是一个数组，并支持多个时间区间查询，以事件分析查询为例，periods字段对应在产品控制台的操作界面如下。

periods字段格式和字段说明、取值示例如下。

字段格式

[{
  "type": "",
  "last": {
    "unit":"",
    "amount":int
  },
  "range": [int,int]
  "granularity": "",
  "timezone": "Asia/Shanghai",
  "interval": int,
  "real_time": boolean,
  "week_start": int
}]

字段说明

时间范围相关参数

字段	取值与含义	是否必须	例子
type	时间范围类型。枚举值为： range：范围查询 last：最近 today：今天 past_range：过去多少天	否	默认range
range	type为range时有效。表示时间范围为具体的某一段时间，是一个绝对时间范围。长度为2的整形数组，数组取值分别表示开始与截止时间，取值为距离1970年1月1日0点0分的时间差值，单位为秒。	type为range时为必填参数	`{range: [1586102400, 1588780799]}`
last	type为last时有效。表示时间范围为最近几天，是一个相对时间的时间范围。取值为json格式，包含以下字段： amount：表示数量 unit：表示单位，支持day/week/month/year。	type为last时为必填参数	`last:{"unit":"day","amount":7}`
spans	type为past_range时有效，表示时间范围为过去的几天。取值是一个list类型数值，list中包含2个list值，第一个代表开始时间，第二个代表结束时间。每一个list的结构为： `"spans":[ { "type": "", "timestamp/past": "", "offset": }, { "type": "", "timestamp/past": "", "offset": } ]` 取值说明如下： type：表示过去几天时间范围的时间数据类型，枚举值包括： timestamp：表示具体的时间点，当起始/结束时间为固定时间时，可使用timestamp。 past：过去什么时间，当起始/结束时间为动态时间时，可使用past。 timestamp：当type取值为timestamp时生效，表示时间范围的起始时间或结束时间的具体时间点，格式为时间戳类型。 past：当type取值为past时生效，表示时间范围的起始时间或结束时间为过去多长时间。 amount：表示数量，单位为天时，0代表今天；1代表昨天，以此类推。 unit：表示单位，支持 day,week,month,year。 offset：表示时间的偏移量，单位为秒。例如时间范围是昨天01点~今天01点时，起始时间的offset为3600，结束时间的offset为7199，与以下产品控制台界面的配置效果类似。	type为past_range时为必填参数	`"spans":[ { "type": "past", "past": { "amount": 1, "unit": "day" }, "offset":3600 }, { "type": "past", "past": { "amount": 0, "unit": "day" }, "offset":7199 } ]`

时间切分粒度相关参数，表示以什么时间粒度汇总展示查询结果，与产品控制台界面分析图表的X轴效果类似。

字段	取值与含义	是否必须	例子
granularity	时间粒度。对指定的时间范围按照时间粒度进行拆分。枚举值： all(不进行拆分，汇总值) second minute five_minute ten_minute fifteen_minute thirty_minute hour day week month quarter year	否	默认all
week_start	granularity为周时，可以指定周的起始日期，比如5表示周五~周四。	否	默认1，周一到周日。
interval	时间粒度。以自定义的时间粒度进行拆分，时间单位秒，比如130秒。	否
align_unit	对齐单元（时间范围校准单元），缺省时与granularity的取值一致，枚举值： second minute five_minute ten_minute fifteen_minute thirty_minute hour day week month quarter year	否

其他参数

字段	取值与含义	是否必须	例子
timezone	时间范围的时区	否	默认Asia/Shanghai
real_time	是否是实时查询，如果为true，只会查询实时的库。此参数已废弃使用无需关注。	否

取值示例

示例1

{
    "granularity":"day",
    "type":"range",
    "range":[1586102400, 1588780799],
    "timezone": "Asia/Shanghai"
    }

示例2

{
    "granularity":"day",
    "type":"last",
    "last":{"amount":7,"unit":'day'},
    "timezone": "Asia/Shanghai"
    }

示例3

{
    "granularity":"day",
    "type":"today",
    "timezone": "Asia/Shanghai"
    }

示例4

{
        "granularity": "all",
        "align_unit":"day",
        "type": "past_range",
        "spans":[
            {
              "type": "timestamp",
              "timestamp": "1619798400",
              "offset":3600
            },
            {
                "type": "past",
                "past": {
                        "amount": 1,
                        "unit": "day"
                },
                "offset":7199
            }
        ]
        "timezone": "Asia/Shanghai"
}

5.2.3 content字段

具体的查询内容字段，以事件分析查询为例与产品控制台界面的以下配置功能类似。

content字段的各参数及说明如下。

{
  "profile_filters": [{}],     #过滤条件，详情见下文的profile_filters
  "profile_groups_v2": [],     #分组条件，只支持公共属性，详情见下文的profile_groups_v2。
  "orders": [],                #排序规则，此参数暂时无用，无需关注
  "query_type": "",            #查询类型，详情见下文的query_type
  "queries": [[],[]],          #查询，二维数组。不同的查询类型需要设置不同的queries数组，详情见下文的queries
  "option": {},                #查询选项
  "page": {},                  #查询分页，limit相关配置
}

5.2.4 content/profile_filters

表示查询时的过滤条件，与以下界面配置功能效果类似。

[{
  "show_name": "1",
  "show_label": 1,
  "expression": {
    "logic": "and",
    "conditions": [{
      "property_name": "custom_server_gender",
      "property_type": "profile",
      "property_operation": "=",
      "property_values": ["1"]
    }]
  }
}]

说明

私有化里面 "property_type" : "profile" 需要修改为 "property_type": "user_profile"

字段	类型	取值与含义	是否必须
show_name	string	前端参数，不影响查询结果，无需关注	否
show_label	string	前端参数，不影响查询结果，无需关注	否
expression	json	查询过滤条件的过滤表达式，包含过滤条件（conditions）和多个过滤条件间的逻辑关系（logic）。	是
logic	string	多个过滤条件conditions间的逻辑关系，支持：and/or。	是
conditions	json数组	具体的查询过滤条件，支持多个过滤条件，每个查询过滤条件的格式和字段要求如下文的condition所示。	是

###5.2.5 content/profile_filters/condition
查询过滤条件中，单个过滤条件的格式要求与字段说明。

{
      "property_name": "custom_server_gender",
      "property_type": "profile/user_profile",
      "property_operation": "=",
      "property_values": ["1"]
 }

字段	类型	取值与含义	是否必须
property_name	string	属性名称	否
property_type	string	属性类型，枚举值： profile：用户属性，SaaS适用 user_profile：用户属性，私有化适用 event_param：事件属性 common_param：事件公共属性 cohort：用户分群。	否
property_operation	string	计算表达式，不同的property_type支持的property_operation不一样，所有枚举值如下： `= != is_null is_not_null in not_in > >= < <= contain not_contain`	使用了过滤属性时必填
property_values	string/int/float数组	属性的表达式的值	使用了过滤属性时必填

5.2.6 content/profile_groups_v2

表示查询时的分组条件，只支持公共属性。

"profile_groups_v2": [
    {
        "property_type":"profile",
        "property_name":"user_is_new"
    },
    {
        "property_type":"profile",
        "property_name":"os_name"
    }
]

字段	类型	取值与含义	是否必须
profile_groups_v2	json数组	表示查询时的分组条件，为一个JSON数组，包含以下字段： property_type：分组的属性，SaaS需配置为profile，私有化需配置user_profile。 property_name：公共属性名称。	否

字段

类型

取值与含义

是否必须

profile_groups_v2

json数组

表示查询时的分组条件，为一个JSON数组，包含以下字段：

property_type：分组的属性，SaaS需配置为profile，私有化需配置user_profile。
property_name：公共属性名称。

否

5.2.7 content/query_type

字段	类型	字段描述	是否必须
query_type	string	查询的分析数据类型，枚举值：事件查询：event 留存查询：retention 转换查询：funnel 用户路径查询：path_find 生命周期查询：life_cycle web查询：web_session topk查询：event_topk LTV查询：ltv 归因查询：behavior_attribution 成分查询：composition 广告查询：advertise 置信度查询：confidence	是

字段

类型

字段描述

是否必须

query_type

string

查询的分析数据类型，枚举值：

事件查询：event
留存查询：retention
转换查询：funnel
用户路径查询：path_find
生命周期查询：life_cycle
web查询：web_session
topk查询：event_topk
LTV查询：ltv
归因查询：behavior_attribution
成分查询：composition
广告查询：advertise
置信度查询：confidence

是

5.2.8 content/queries

查询条件，二维数组，不同的查询类型，需要组织对应的query数组。具体参考案例：

{
  "event_name": "any_event",
  "event_id":1,
  "event_type": "origin",
  "show_name": "总次数",
  "groups_v2": [],
  "filters": [],
  "show_label": "A",
  "event_indicator": "events",
  "measure_info": {}
}

字段	类型	取值与含义	是否必须
event_name	string	事件名称	event_name和event_id必须有一个
event_id	int	事件id	event_name和event_id必须有一个
event_type	string	事件类型，目前支持三种类型 origin：一般事件 virtual：虚拟事件 bav：圈选事件	是
groups_v2	string数组	同profile_groups_v2，取事件属性、事件公共属性、用户属性	否
filter	数组	同profile_filters。	否
event_indicator	string	计算指标： events: 总次数 event_users: 总人数 uv_per_au: 渗透率 events_per_user: 人均次数 pv_per_au: 全活跃用户人均次数 measure: 计算	是
measure_info	json	计算指标补充，在 event_indicator 为 measure 时使用，格式和详情如下。 `{ "event_indicator": "measure", "measure_info": { "measure_type": "sum", "property_name": "time" } }` measure_type：测量尺度，枚举值如下： sum：按...求和 min：按...求最小值 max：按...求最大值 avg：按...求平均值 per_user：按...求人均值 sum_per_au：按...求全活跃用户人均值 pct：按...求分位数 distinct：按...求去重数 distinct_user_attr：按...和用户去重 property_name：计算属性	event_indicator 为 measure 时必填。
show_label	string	前端参数，不影响查询结果，无需关注	否

5.2.9 content/profile_filtersoption

存放跟查询相关的特定的配置，用来设置是否使用缓存，以及其他参数。

{
    "refresh_cache": false,
    "fusion": false
}

字段	取值与含义
所有查询通用字段
skip_cache	是否跳过缓存。true表示不走缓存，默认是false
refresh_cache	是否刷新缓存。查询默认会走缓存，当希望跳过缓存并且更新缓存数据的时候，可以设置refresh_cache为true
product	产品名称，默认是bytefinder。如果您使用的是tracer，则设置为bytetracer
转换查询/用户路径查询
window_period_type	窗口时间单位，取值同granularity
window_period	窗口时间
生命周期查询
lifecycle_query_type	取值枚举值： active 活跃用户。 lost 流失用户。
lifecycle_period	取值为一个json对象，属性固定为granularity、period： "granularity"：时间粒度 "period"：时间大小
留存分析
retention_type	窗口时间单位，取值同granularity
retention_n_days	时间窗口大小
web分析
web_session_params	web查询设置的参数。 `{ "session_params_type": "first", "session_timeout": 1200 }` session_params_type：当前支持三种枚举值： first：session 的属性全由第一个 pageview 决定。场景：来源页分析、入口页分析。 last：session 的属性全由最后个 pageview 决定。场景：退出页分析。 filter_first_group_last：session 的第一个属性全由第一个 pageview 决定，session 的第二个属性由最后个 pageview 决定，按第一个属性过滤，按第二个属性group by。场景：指定来源的退出页分析。 session_timeout：超时时间。
option	是否同时融合查询实时数据和离线数据，true表示融合，默认是false。

5.2.10 content/page

存放跟查询分页相关的信息。

"page": {
    "limit": 50,  # 指定最大返回维度的条数
    "offset": 0
}

字段	类型	取值与含义	是否必须
limit	int	指定要返回的最大维度数据条数。默认为 1000，最大支持50000。注意：`limit`设置过大可能导致查询超时或异常失败	否
offset	int	`offset`字段尚处于开发阶段，目前无法生效，无需关注。	否

6. 典型场景 DSL 示例

6.1 事件查询：event

{
    "use_app_cloud_id": true,
    "app_ids": [
        164***
    ],
    "periods": [
        {
            "granularity": "day",
            "type": "last",
            "last": {
                "amount": 7,
                "unit": "day"
            },
            "timezone": "Asia/Shanghai"
        }
    ],
    "version": 3,
    "content": {
        "profile_groups_v2": [],
        "profile_filters": [],
        "orders": [],
        "query_type": "event",
        "queries": [
            [
                {
                    "event_name": "app_launch",
                    "event_type": "origin",
                    "show_name": "应用启动",
                    "groups_v2": [],
                    "filters": [],
                    "show_label": "A",
                    "event_indicator": "events",
                    "measure_info": {},
                    "indicator_show_name": "总次数"
                }
            ]
        ],
        "option": {
            "refresh_cache": false,
            "fusion": false
        }
    }
}

6.2 留存查询：retention

{
    "app_ids": [
        164***
    ],
    "periods": [
        {
            "granularity": "day",
            "type": "last",
            "last": {
                "amount": 7,
                "unit": "day"
            },
            "timezone": "Asia/Shanghai"
        }
    ],
    "version": 3,
    "content": {
        "query_type": "retention",
        "profile_groups_v2": [],
        "profile_filters": [],
        "orders": [],
        "queries": [
            [
                {
                    "show_label": "A",
                    "event_name": "app_launch",
                    "event_type": "origin",
                    "groups_v2": [],
                    "filters": []
                },
                {
                    "show_label": "",
                    "event_name": "any_active_event",
                    "event_type": "origin",
                    "groups_v2": [],
                    "filters": []
                }
            ]
        ],
        "page": {
            "limit": 50,
            "offset": 0
        },
        "option": {
            "refresh_cache": false,
            "fusion": false
        }
    },
    "use_app_cloud_id": true

}

6.3 转化查询：funnel

{
    "app_ids": [
        164***
    ],
    "periods": [
        {
            "granularity": "day",
            "type": "last",
            "last": {
                "amount": 7,
                "unit": "day"
            },
            "timezone": "Asia/Shanghai"
        }
    ],
    "version": 3,
    "content": {
        "query_type": "funnel",
        "profile_groups_v2": [],
        "profile_filters": [],
        "orders": [],
        "page": {
            "limit": 50,
            "offset": 0
        },
        "queries": [
            [
                {
                    "show_label": "1",
                    "event_id": 234***,
                    "event_name": "app_launch",
                    "event_type": "origin",
                    "show_name": "",
                    "groups_v2": [],
                    "filters": []
                },
                {
                    "show_label": "2",
                    "event_id": 234***,
                    "event_name": "app_launch",
                    "event_type": "origin",
                    "show_name": "",
                    "groups_v2": [],
                    "filters": []
                }
            ]
        ],
        "option": {
            "window_period": 10, 
            "window_period_type": "minute",
            "fusion": false,
            "refresh_cache": false
        }
    },
    "use_app_cloud_id": true

}

6.4 用户路径查询：path_find

{
    "app_ids": [
        164***
    ],
    "periods": [
        {
            "type": "last",
            "last": {
                "amount": 7,
                "unit": "day"
            },
            "timezone": "Asia/Shanghai",
            "interval": "604800"
        }
    ],
    "version": 3,
    "content": {
        "profile_groups_v2": [],
        "profile_filters": [],
        "orders": [],
        "query_type": "path_find",
        "queries": [
            [
                {
                    "event_type": "origin",
                    "show_label": "A",
                    "groups_v2": [],
                    "filters": []
                },
                {
                    "event_type": "origin",
                    "show_label": "B",
                    "groups_v2": [],
                    "filters": []
                }
            ]
        ],
        "option": {
            "refresh_cache": false,
            "hide_unselected": true,
            "window_period_type": "minute", 
            "window_period": 10 
        }
    },
    "use_app_cloud_id": true

}

6.5 生命周期查询：life_cycle

{
    "app_ids": [
        164***
    ],
    "periods": [
        {
            "granularity": "day",
            "type": "last",
            "last": {
                "amount": 7,
                "unit": "day"
            },
            "timezone": "Asia/Shanghai"
        }
    ],
    "version": 3,
    "content": {
        "query_type": "life_cycle",
        "queries": [
            [
                {
                    "event_id": 516***,
                    "event_name": "any_active_event",
                    "event_type": "origin",
                    "groups_v2": [],
                    "filters": []
                }
            ]
        ],
        "profile_filters": [
        ],
        "profile_groups_v2": [],
        "option": {
            "lifecycle_period": {
                "granularity": "day",
                "period": 1
            },
            "lifecycle_query_type": "active"
        }
    },
    "use_app_cloud_id": true

}

6.6 web查询：web_session

{
    "app_ids": [
        164***
    ],
    "periods": [
        {
            "granularity": "day",
            "type": "last",
            "last": {
                "amount": 7,
                "unit": "day"
            },
            "timezone": "Asia/Shanghai"
        }
    ],
    "version": 3,
    "contents": [
        {
            "profile_groups_v2": [],
            "profile_filters": [],
            "orders": [],
            "query_type": "web_session",
            "queries": [
                [
                    {
                        "event_type": "none",
                        "show_name": "访客数",
                        "groups_v2": [],
                        "filters": [
                            {
                                "expression": {
                                    "logic": "and",
                                    "conditions": [
                                        {
                                            "property_values": [
                                                null
                                            ],
                                            "property_type": "event_param",
                                            "property_name": "referer_type",
                                            "property_operation": "is not null"
                                        }
                                    ]
                                }
                            }
                        ],
                        "show_label": "uv",
                        "event_indicator": "uv"
                    }
                ]
            ],
            "option": {
                "refresh_cache": false,
                "fusion": true
            }
        }
    ],
    "use_app_cloud_id": true

}

6.7 topk查询：event_topk

{
    "app_ids": [
        "164***"
    ],
    "use_app_cloud_id": true,
    "version": "3.0",
    "periods": [
        {
            "granularity": "day",
            "align_unit": "day",
            "timezone": "Asia/Shanghai",
            "type": "last",
            "last": {
                "amount": 7,
                "unit": "day"
            }
        }
    ],
    "content": {
        "show_option": {},
        "profile_groups_v2": [],
        "profile_filters": [],
        "orders": [],
        "query_type": "event_topk",
        "queries": [
            [
                {
                    "event_type": "none",
                    "event_indicator": "pv",
                    "show_name": "",
                    "show_label": "",
                    "event_name": null,
                    "groups_v2": [],
                    "filters": []
                }
            ]
        ],
        "option": {
        }
    }
}

6.8 LTV查询：ltv

{
    "app_ids": [
        164***
    ],
    "periods": [
        {
            "granularity": "day",
            "type": "last",
            "last": {
                "amount": 60,
                "unit": "day"
            },
            "timezone": "Asia/Shanghai"
        }
    ],
    "version": 3,
    "content": {
        "query_type": "ltv",
        "profile_groups_v2": [],
        "profile_filters": [],
        "orders": [],
        "queries": [
            [
                {
                    "show_label": "",
                    "event_name": "purchase",
                    "event_type": "origin",
                    "groups_v2": [],
                    "filters": [],
                    "event_indicator": "measure",
                    "measure_info": {
                        "measure_type": "plain",
                        "property_name": "currency_amount"
                    }
                },
                {
                    "show_label": "",
                    "event_name": "any_event",
                    "event_type": "origin",
                    "groups_v2": [],
                    "filters": []
                }
            ]
        ],
        "page": {
            "limit": 10,
            "offset": 2
        },
        "option": {}
    },
    "use_app_cloud_id": true

}

6.9 归因查询：behavior_attribution

{
    "use_app_cloud_id": true,
    "app_ids": [
        164***
    ],
    "periods": [
        {
            "granularity": "all",
            "type": "last",
            "last": {
                "amount": 7,
                "unit": "day"
            },
            "timezone": "Asia/Shanghai",
            "interval": "604800"
        }
    ],
    "version": 3,
    "content": {
        "profile_groups_v2": [],
        "profile_filters": [],
        "orders": [],
        "query_type": "behavior_attribution",
        "queries": [
            [
                {
                    "event_name": "purchase",
                    "event_type": "origin",
                    "show_name": "支付",
                    "groups_v2": [],
                    "event_indicator": "events",
                    "show_label": "A",
                    "measure_info": {},
                    "filters": []
                }
            ],
            [],
            [
                {
                    "event_name": "app_launch",
                    "event_type": "origin",
                    "show_name": "应用启动",
                    "groups_v2": [],
                    "event_indicator": "events",
                    "show_label": "A",
                    "measure_info": {},
                    "filters": []
                }
            ]
        ],
        "option": {
            "refresh_cache": false,
            "attribution_type": "last",
            "window_period": 0,
            "window_period_type": "day",
            "is_other_contact": false
        },
        "page": {
            "limit": 50,
            "offset": 0
        }
    }
}

6.10 成分查询：composition

{
    "app_ids": [
        164***
    ],
    "periods": [
        {
            "type": "last",
            "last": {
                "amount": 30,
                "unit": "day"
            },
            "timezone": "Asia/Shanghai",
            "align_unit": "day",
            "granularity": "all"
        }
    ],
    "version": 3,
    "content": {
        "query_type": "composition",
        "profile_groups_v2": [
            {
                "property_type" : "profile",
                "property_name": "age"
            }
        ],
        "profile_filters": [],
        "orders": [],
        "queries": [
            [
                {
                    "event_type": "none"
                }
            ]
        ],
        "option": {
            "refresh_cache": false
        }
    },
    "use_app_cloud_id": true

}

说明

私有化里面 "property_type" : "profile" 需要修改为 "property_type": "user_profile"

6.11 属性查询：attribute

{
    "use_app_cloud_id": true,
    "app_ids": [
        164***
    ],
    "periods": [
        {
            //只支持all粒度，不支持按时间粒度分组
            "granularity": "all",
            "type": "past_range",
            "spans": [
                {
                    "type": "past",
                    "past": {
                        "amount": 7,
                        "unit": "day"
                    }
                },
                {
                    "type": "past",
                    "past": {
                        "amount": 1,
                        "unit": "day"
                    }
                }
            ],
            "timezone": "Asia/Shanghai",
            "week_start": 1,
            "align_unit": "day"
        }
    ],
    "version": 3,
    "content": {
        "profile_groups_v2": [],
        "profile_filters": [],
        //自定义排序字段
        "orders": [
        {   //field形式为{property_type}#{property_name}的形式，direction为desc（降序）或者asc（升序）
                "field": "profile#loc_city_id",
                "direction": "desc"
            }
        ],
        //自定义分页字段，limit最大为10000，超过10000按10000处理
        "page": {
            "limit": 50,
            "offset": 0
        },
        //查询类型，仅支持openApi
        "query_type": "attribute",
        "queries": [
            [
                {
                    "indicator_show_name": "",
                    "measure_info": {},
                    "show_name": "",
                    "show_label": "A",
                    "event_name": "any_event",
                    "event_type": "origin",
                    "event_indicator": "None",
                    "filters": [],
                    //需要查询的属性
                    "groups_v2": [
                        {
                            "property_compose_type": "origin",
                            "property_name": "$event_name",
                            "property_type": "common_param"
                        },
                        {
                            "property_compose_type": "origin",
                            "property_name": "loc_city_id",
                            "property_type": "profile"
                        },
                        {
                            "property_compose_type": "virtual",
                            "property_name": "$_vp_zylvirtual",
                            "property_type": "common_param"
                        }
                    ],
                    "extra": {}
                }
            ]
        ],
        "option": {
            //是否分页（必传true）
            "is_paginate": true
        }
    },
    "option": {}
}

该DSL特用于多个属性分组，且分组值数量较大的查询场景，在此特定场景下支持分页。
查询限制：

不支持item属性的查询
必须指定事件名+日期
只支持同一事件下的属性查询
支持虚拟事件以及虚拟属性
最多同时支持5个属性的查询（超过5个的会被抛弃）
不支持时间粒度分组，仅支持granularity: all

说明

event_indicator需要固定传None。
is_paginate代表是否分页，必传true，否则只会取前page.limit条结果。
groups_v2在query type 为attribute的情况下传需要查询的属性列表。

7. 如何获取大批量的事件分析查询分析结果

目前，事件分析的openapi最多支持 50000 条分组数据的查询。部分客户使用中，可能存在分组基数很大的情况，50000 的限制无法满足客户获取数据的情况。因此在私有化4.6版本（含）后，支持通过OpenAPI获取CSV格式的文件数据，通过该方式最多可以一次性获取100万条数据。

API说明

Context-Path: /datafinder
Path：/openapi/v1/{app_id}/downloads
Method: POST
Content-type: application/json

Body:

字段	类型	说明
result_id	string	和 dsl 二选一，优先 result_id，根据 result_id 下载数据
dsl	string	和 result_id 二选一，优先 result_id，根据dsl下载数据，使用dsl的page中的limit字段限制返回条数，offset无效

Response
返回zip格式文件
Header
- Content-Disposition: attachment; filename={file_name}.zip
- Content-Type: application/zip

说明

条数限制：最大返回条数 100 w
并发限制：Saas中每 project_id / app_id 限制并发为 1；私有化无限制。
自定义指标限制：目前仅支持导出原子指标，不支持二次计算后的自定义指标。

1. 概述

2. 查询分析 OpenAPI 说明（SaaS）

2.1 API 定义

2.2 OpenAPI SDK使用样例

3. 查询分析 OpenAPI 说明（私有化）

3.1 使用 DSL 查询 API 定义

3.2 获取 result_id 查询结果 API 定义

3.3 OpenAPI SDK 使用样例

4. 如何快速构建 DSL

4.1 获取页面查询的 DSL（推荐）

4.2 使用 OpenAPI 提供的 DSLBuilder

5. DSL 结构说明

5.1 整体结构

5.2 字段详细说明

5.2.1 顶层结构

5.2.2 periods字段

5.2.3 content字段

5.2.4 content/profile_filters

5.2.6 content/profile_groups_v2

5.2.7 content/query_type

5.2.8 content/queries

5.2.9 content/profile_filtersoption

5.2.10 content/page

6. 典型场景 DSL 示例

6.1 事件查询：event

6.2 留存查询：retention

6.3 转化查询：funnel

6.4 用户路径查询：path_find

6.5 生命周期查询：life_cycle

6.6 web查询：web_session

6.7 topk查询：event_topk

6.8 LTV查询：ltv

6.9 归因查询：behavior_attribution

6.10 成分查询：composition

6.11 属性查询：attribute

7. 如何获取大批量的事件分析查询分析结果

API说明

增长分析

查询API

2.1 API 定义

2.2 OpenAPI SDK使用样例

3.1 使用 DSL 查询 API 定义

3.2 获取 result_id 查询结果 API 定义

3.3 OpenAPI SDK 使用样例

4.1 获取页面查询的 DSL（推荐）

4.2 使用 OpenAPI 提供的 DSLBuilder

5.1 整体结构

5.2 字段详细说明

5.2.1 顶层结构

5.2.2 periods字段

5.2.3 content字段

5.2.4 content/profile_filters

5.2.6 content/profile_groups_v2

5.2.7 content/query_type

5.2.8 content/queries

5.2.9 content/profile_filtersoption

5.2.10 content/page

6.1 事件查询：event

6.2 留存查询：retention

6.3 转化查询：funnel

6.4 用户路径查询：path_find

6.5 生命周期查询：life_cycle

6.6 web查询：web_session

6.7 topk查询：event_topk

6.8 LTV查询：ltv

6.9 归因查询：behavior_attribution

6.10 成分查询：composition

6.11 属性查询：attribute

API说明