导航
API说明与公共参数
最近更新时间：2024.06.30 18:36:02首次发布时间：2024.06.30 18:36:02
1.概述
本文档提供火山引擎增长分析中分群相关接口的说明。
分群相关接口能力包括：
- 获取分群列表
- 获取指定分群信息
- 获取指定分群的用户列表信息
- 下载指定分群用户列表信息
- 规则创建分群
- 刷新分群
- 上传文件创建分群
- 删除分群
- 修改分群
注：当前导出分群的上限为300W。
2.API 公共参数
Context-path: /datafinder
Path-parameters:
参数 | 类型 | 是否必选 | 示例值 | 描述 |
|---|---|---|---|---|
app_id | int | 是 | 123456 | 应用id |
Response:
{ "code": 200, "message": "success" "data": xxx }
- code 状态码，200 表示成功，其他非失败
- message 成功或失败信息
- data 结果数据，具体结构参考具体的 API 描述
3.分群 OpenAPI-DSL 结构说明
下文为您提供规则分群使用的DSL结构详细说明。
DSL 结构说明
从前端获取分群DSL（推荐）
在分群配置页面中配置好规则，打开浏览器控制台；接着点击“预估人数”，查看overview接口的dsl_content字段。（注意：使用dsl_content的时候，最好把show_option节点整体删除）
整体结构
分群DSL 整体结构跟查询API使用的整体结构是一致的，整体结构请参考： “查询API”->“DSL结构”说明。
分群的区别是在content的queries字段，扩展了相应的含义。整体结构：
{ "version": 3, # DSL的版本，本文档中全部为3 "app_ids": [], # 目标app "use_app_cloud_id": true, # app_ids参数中是否为app_cloud_id。请设置为true,false仅供内部使用 "periods": [], # 时间，分群这里固定为[] "content": {}, # 具体的查询内容字段 "option": {}, # json格式数据，请求相关的选项参数，分群不需要该字段 "show_option": {} # json格式数据，在结果中原样返回，分群不需要该字段 }
具体规则定义在 cotent字段中：
{ "content": { "query_type": "cohort_v3_idlist", # 固定使用这个类型 "queries":[ # 分群规则 [{query1},{query2}], [{query3},{query4}] ] "option":{}, # 分群参数 "profile_filters":[], # 固定为[] "profile_groups":[] # 固定为[] } }
字段详细说明
option 字段
{ "cohort": { "outer_logic": "and" } }
字段 | 取值与含义 | 是否必须 | 例子 |
|---|---|---|---|
outer_logic | 最外层的逻辑关系：and/or | 否 | 默认and |
queries 字段
[ [{query1},{query2}], [{query3},{query4}] ... ]
query 逻辑关系
queries 是一个二维数组，定义了每一个规则的关系。
当 outer_logic 为and 时：内层数组的关系为 or，外层关系为 and。比如：
"queries":[ # 分群规则 [{query1},{query2}], [{query3},{query4}] ] "option":{ "cohort": { "outer_logic": "and" } },
那么整体计算关系为：
[query1 or query2] and [query3 or query4]
当 outer_logic 为or 时：内层数组的关系为 and，外层关系为 or。比如：
"queries":[ # 分群规则 [{query1},{query2}], [{query3},{query4}] ] "option":{ "cohort": { "outer_logic": "or" } },
那么整体计算关系为：
[query1 and query2] or [query3 and query4]
query 结构
整体结构，参考“查询API”->“DSL结构”->“content字段/queries”。
{ "event_name": "any_event", "event_id":1, "event_type": "origin", "show_name": "总次数", "groups_v2": [], "filters": [], "show_label": "A", "event_indicator": "events", "measure_info": {}, "condition":{}, "logic": true, "sequence_first":true, "next_query_lable":"B", }
新增字段含义说明：
字段 | 取值与含义 | 是否必须 | 例子 |
|---|---|---|---|
condition | 分群的条件，结构同 DSL “condition” 结构 | 是 | |
logic | true表示用户做过、用户是；false 表示用户没做过、用户不是 | 是 | 注意：当logic为true的时候，并且用户做过，比如选择用户做过事件次数 大于 {n}，n的值一定是一个大于0的值。如果要选择 “用户做过事件A次数=0”，请使用“用户没做过事件A 的条件” |
sequence_first | true表示是“依次做过”，并且是依次做过的第一个事件 | 否 | “依次做过”下是必须的 |
next_query_label | “依次做过”的下一个事件的show_label值 | 否 |
condition 结构：
整体结构，参考“查询API”->“DSL结构”->“content字段/condition”
{ "property_operation": ">", "property_values": [0], "period": {} }
新增字段含义说明：
字段 | 取值与含义 | 是否必须 | 例子 |
|---|---|---|---|
period | 分群条件的时间范围，参考 DSL period结构 | 否 | 选择事件、或者all_value用户属性的时候一定需要时间 |
样例
用户做过
{ "periods": [], "version": 3, "use_app_cloud_id": true, "app_ids": [ 164314 ], "content": { "option": { "cohort": { "outer_logic": "and" } }, "query_type": "cohort_v3_idlist", "profile_filters": [], "profile_groups": [], "queries": [ [ { "show_label": "c06bed36-eede-4174-91bf-8f37eac3a8ee", "event_name": "any_event", "event_type": "origin", "logic": true, "event_indicator": "events", "measure_info": {}, "condition": { "property_operation": ">=", "property_values": [ 1 ], "period": { "granularity": "day", "type": "past_range", "spans": [ { "type": "past", "past": { "amount": 7, "unit": "day" } }, { "type": "past", "past": { "amount": 1, "unit": "day" } } ], "timezone": "Asia/Shanghai", "week_start": 1 } }, "filters": [ { "expression": { "logic": "and", "conditions": [] } } ] } ] ] } }
用户没做过
{ "periods": [], "version": 3, "use_app_cloud_id": true, "app_ids": [ 164314 ], "content": { "option": { "cohort": { "outer_logic": "and" } }, "query_type": "cohort_v3_idlist", "profile_filters": [], "profile_groups": [], "queries": [ [ { "show_label": "c06bed36-eede-4174-91bf-8f37eac3a8ee", "event_name": "any_event", "event_type": "origin", "logic": false, "event_indicator": "events", "measure_info": {}, "condition": { "property_operation": ">=", "property_values": [ 1 ], "period": { "granularity": "day", "type": "past_range", "spans": [ { "type": "past", "past": { "amount": 7, "unit": "day" } }, { "type": "past", "past": { "amount": 1, "unit": "day" } } ], "timezone": "Asia/Shanghai", "week_start": 1 } }, "filters": [ { "expression": { "logic": "and", "conditions": [] } } ] } ] ] } }
用户是
{ "periods": [], "version": 3, "use_app_cloud_id": true, "app_ids": [ 164314 ], "content": { "option": { "cohort": { "outer_logic": "and" } }, "query_type": "cohort_v3_idlist", "profile_filters": [], "profile_groups": [], "queries": [ [ { "show_label": "c06bed36-eede-4174-91bf-8f37eac3a8ee", "event_indicator": "events", "logic": true, "condition": { "period": { "granularity": "day", "type": "past_range", "spans": [ { "type": "past", "past": { "amount": 7, "unit": "day" } }, { "type": "past", "past": { "amount": 1, "unit": "day" } } ], "timezone": "Asia/Shanghai", "week_start": 1 }, "property_operation": ">", "property_values": [ 0 ] }, "filters": [ { "expression": { "logic": "and", "conditions": [ { "property_type": "profile", "property_name": "custom_Age", "property_compose_type": "origin", "property_operation": "=", "property_values": [ 35 ] } ] } } ] } ] ] } }
用户不是
{ "periods": [], "version": 3, "use_app_cloud_id": true, "app_ids": [ 164314 ], "content": { "option": { "cohort": { "outer_logic": "and" } }, "query_type": "cohort_v3_idlist", "profile_filters": [], "profile_groups": [], "queries": [ [ { "show_label": "c06bed36-eede-4174-91bf-8f37eac3a8ee", "event_indicator": "events", "logic": false, "condition": { "period": { "granularity": "day", "type": "past_range", "spans": [ { "type": "past", "past": { "amount": 7, "unit": "day" } }, { "type": "past", "past": { "amount": 1, "unit": "day" } } ], "timezone": "Asia/Shanghai", "week_start": 1 }, "property_operation": ">", "property_values": [ 0 ] }, "filters": [ { "expression": { "logic": "and", "conditions": [ { "property_type": "profile", "property_name": "custom_Age", "property_compose_type": "origin", "property_operation": "=", "property_values": [ 35 ] } ] } } ] } ] ] } }
行为序列
{ "periods": [], "version": 3, "use_app_cloud_id": true, "app_ids": [ 164314 ], "content": { "option": { "cohort": { "outer_logic": "and" } }, "query_type": "cohort_v3_idlist", "profile_filters": [], "profile_groups": [], "queries": [ [ { "show_label": "1c21dddc-bcc6-4389-90b2-09d6f66099b4", "event_name": "predefine_pageview", "event_id": 237198, "event_type": "origin", "logic": true, "event_indicator": "events", "sequence_first": true, "next_query_label": "e0edb616-3530-4316-9604-9141099db401", "condition": { "period": { "granularity": "day", "type": "past_range", "spans": [ { "type": "past", "past": { "amount": 7, "unit": "day" } }, { "type": "past", "past": { "amount": 1, "unit": "day" } } ], "timezone": "Asia/Shanghai", "week_start": 1 }, "property_operation": ">", "property_values": [ 0 ] }, "filters": [ { "expression": { "logic": "and", "conditions": [] } } ] }, { "show_label": "e0edb616-3530-4316-9604-9141099db401", "event_name": "order_pay_success", "event_id": 298968, "event_type": "origin", "logic": true, "event_indicator": "events", "sequence_first": false, "next_query_label": null, "condition": { "period": { "granularity": "day", "type": "past_range", "spans": [ { "type": "past", "past": { "amount": 7, "unit": "day" } }, { "type": "past", "past": { "amount": 1, "unit": "day" } } ], "timezone": "Asia/Shanghai", "week_start": 1 }, "property_operation": ">", "property_values": [ 0 ] }, "filters": [ { "expression": { "logic": "and", "conditions": [] } } ] } ] ] } }
4.API列表
API | 说明 |
|---|---|
获取分群列表 | |
获取指定分群信息 | |
获取指定分群的用户列表信息 | |
下载指定分群用户列表信息（流式） | |
规则创建分群 | |
刷新分群 | |
上传文件创建分群 | |
删除创建分群 | |
修改创建分群 |