You need to enable JavaScript to run this app.
导航
分群 OpenAPI-DSL 结构说明
最近更新时间:2024.05.29 16:21:47首次发布时间:2023.03.17 18:05:26

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_logicand 时:内层数组的关系为 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": {}
 }

新增字段含义说明:

字段

取值与含义

是否必须

例子

period

分群条件的时间范围,参考 DSL period结构

选择事件、或者all_value用户属性的时候一定需要时间

3 样例

3.1 用户做过

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

3.2 用户没做过

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

3.3 用户是

{
    "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
                                        ]
                                    }
                                ]
                            }
                        }
                    ]
                }
            ]
        ]
    }
}

3.4 用户不是

{
    "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
                                        ]
                                    }
                                ]
                            }
                        }
                    ]
                }
            ]
        ]
    }
}

3.5 行为序列

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