文档中心

分群 OpenAPI-DSL 结构说明

最近更新时间：2024.02.27 11:48:00

首次发布时间：2024.02.27 11:48:00

1 概述

本文档提供对火山引擎增长分析中规则分群使用的DSL结构详细说明。

2 DSL 结构说明

2.1 从前端获取分群DSL（推荐）

在分群配置页面中配置好规则，打开浏览器控制台；接着点击“预估人数”，查看overview接口的dsl_content字段。（注意：使用dsl_content的时候，最好把show_option节点整体删除）

2.2 整体结构

分群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":[]              # 固定为[]
  }
}

2.3 字段详细说明

2.3.1 option 字段

{
 "cohort": {
     "outer_logic": "and"
 }
}

字段	取值与含义	是否必须	例子
outer_logic	最外层的逻辑关系：and/or	否	默认and

2.3.2 queries 字段

[                     
   [{query1},{query2}], 
   [{query3},{query4}]
   ...
]

2.3.2.1 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]

2.3.2.2 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": {}
 }