查询API--增长分析 DataFinder-火山引擎

文档中心

立即注册

导航

查询API

最近更新时间：2024.04.30 15:17:28首次发布时间：2024.04.30 15:17:28

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；私有化无限制。
自定义指标限制：目前仅支持导出原子指标，不支持二次计算后的自定义指标。