文档中心

分群 OpenAPI

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

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

1.概述

本文档提供火山引擎增长分析中分群相关接口的说明。
分群相关接口能力包括：

获取分群列表
获取指定分群信息
获取指定分群的用户列表信息
下载指定分群用户列表信息
规则创建分群
刷新分群
上传文件创建分群
删除分群
修改分群

注：当前导出分群的上限为300W。

2.API 公共参数

Context-path: /datafinder
Path-parameters:

Parameter	Type	Description	Required
app_id	int	应用id	true

Response:

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

code 状态码，200 表示成功，其他非失败
message 成功或失败信息
data 结果数据，具体结构参考具体的 API 描述

3.获取分群列表 API

3.1 API 定义

Path：/openapi/v1/{app_id}/cohorts
Method: GET
Content-type: application/json
Path-parameters: 参考公共参数即可

Response:

{
    "code":200,
    "message":"success",
    "data":[
        {
            "app_id":123,
            "cohort_id":1054321,
            "cohort_name":"分群展示名称",
            "cohort_status":1,
            "cohort_type":4,
            "count":3950,
            "creator":"00000",
            "creator_time":1648446690,
            "description":"",
            "dsl_content": Object{...},
            "modify_time":1648538157,
            "modify_user":"00000",
            "part_date":"",
            "refresh_rule":1,
            "status":1,
            "user_info":{},
            "version":1
        }
    ]
}

获取分群列表接口返回的cohort_status含义：

0：表示计算中
1：表示计算成功
2：表示计算失败
3：表示查询被终止
4：表示查询超时
5：表示查询排队中

tatus跟cohort_status一样的含义，为了兼容老版结构，参考cohort_status 字段即可。

字段含义说明:
data 是一个JSON 对象数组，其中的JSON 关键字段说明

Field	Type	Description
cohort_id	int	分群ID
cohort_name	string	分群名称
refresh_rule	int	分群刷新规则 0: unsupport 不支持刷新 1: manual 支持手动刷新 2: daily 每日刷新
count	int	分群内用户的数量

3.2 OpenAPI SDK 样例

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

# 例如，app_id= 164314
res = bc.data_finder('/openapi/v1/164314/cohorts', method='get')
print(res.content)

返回结果：

{
    "code":200,
    "data":[
        {
            "app_id":164314,
            "cohort_id":1591,
            "cohort_name":"一线活跃用户",
            "cohort_status":1,
            "cohort_type":4,
            "count":34259,
            "creator":"00000",
            "creator_time":1568202530,
            "description":"北上广深，30天内活跃过",
            "dsl_content":Object{...},
            "modify_time":1655270356,
            "modify_user":"00000",
            "part_date":"2022-06-15",
            "refresh_rule":2,
            "status":1,
            "user_info":Object{...},
            "version":10132
        },
        Object{...},
        Object{...}
    ],
    "message":"success"
}

4.获取指定分群信息 API

4.1 API 定义

Path：/openapi/v1/{app_id}/cohorts/{cohort_id}
Method: GET
Content-type: application/json
Path-parameters:

Parameter	Type	Description	Required
cohort_id	int	分群ID	true

Response:

{
    "code":200,
    "message":"success",
    "data":{
        "app_id":123,
        "cohort_id":1054321,
        "cohort_name":"分群展示名称",
        "cohort_status":1,
        "cohort_type":4,
        "count":3950,
        "creator":"10000123",
        "creator_time":1648446690,
        "description":"",
        "dsl_content":Object{...},
        "modify_time":1648538157,
        "modify_user":"10000123",
        "part_date":"",
        "refresh_rule":1,
        "status":1,
        "user_info":Object{...},
        "version":1
    }
}

字段含义说明:
data 是一个JSON 对象数组(如果最多只会有一个)，其中的JSON 关键字段说明

Field	Type	Description
cohort_id	int	分群ID
cohort_name	string	分群名称
refresh_rule	int	分群刷新规则 0: unsupport 不支持刷新 1: manual 支持手动刷新 2: daily 每日刷新
count	int	分群内用户的数量

4.2 OpenAPI SDK 样例

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

# 例如，app_id= 164314 cohort id= 1001076
res = bc.data_finder('/openapi/v1/164314/cohorts/1001076', method='get')
print(res.content)

返回结果：

{
    "code":200,
    "data":{
        "app_id":164314,
        "cohort_id":1591,
        "cohort_name":"一线活跃用户",
        "cohort_status":1,
        "cohort_type":4,
        "count":34259,
        "creator":"00000",
        "creator_time":1568202530,
        "description":"北上广深，30天内活跃过",
        "dsl_content":Object{...},
        "modify_time":1655270356,
        "modify_user":"00000",
        "part_date":"2022-06-15",
        "refresh_rule":2,
        "status":1,
        "user_info":Object{...},
        "version":10132
    },
    "message":"success"
}

5.获取指定分群的用户列表信息 API

5.1 API 定义

Path：/openapi/v1/{app_id}/cohorts/{cohort_id}/sample
Method: GET
Content-type: application/json
Path-parameters:

Parameter	Type	Description	Required
cohort_id	int	分群ID	true

Query-parameters:

Parameter	Type	Description	Required
count	int	需要返回的分群用户数量limit	true

Response:

{
    "code":200,
    "data":{
        "sampleUsers":[
            {
                "uid":"xxx",
                "user_unique_id":"xxx",
                "ssid":"xxx"
            }
        ]
    },
    "message":"success"
}

字段含义说明

Field	Type	Description
uid	string	用户ID
user_unqiue_id	string	用户ID
ssid	string	datafinder统计

5.2 OpenAPI SDK 样例

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

# 例如，app_id= 164314 cohort id= 1001076
res = bc.data_finder('/openapi/v1/164314/cohorts/1001076/sample', method='get',params={"count":"30"})
print(res.content)
j=json.loads(res.content)
print(len(j["data"]["sampleUsers"]))
print(res.content)

返回结果：

{
    "code":200,
    "data":{
        "sampleUsers":[
            {
                "uid":"431108702006175",
                "user_unique_id":"431108702006175",
                "ssid":"2c46868d-c301-47d8-97fa-301f431d20af"
            }
        ]
    },
    "message":"success"
}

6.下载指定分群用户列表信息 (流式) API

6.1 API 定义

Path：/openapi/v1/{app_id}/cohorts/{cohort_id}/download
Method: GET
Content-type: application/json
Path-parameters:

Parameter	Type	Description	Required
cohort_id	int	分群ID	true

Response:
注意：

response的content/type为text/csv;charset=utf-8
response通过流式传输

[分群名称]:{分群名}
[编辑者]:{编辑人名}
[分群用户数]:{分群数量}
用户ID,stat_standard_id,device_id,web_id
{},{},{},{}
{},{},{},{}
{},{},{},{}

字段含义说明

Field	Type	Description
用户Id	string	用户ID
stat_standard_id	string	统计口径ID
device_id	string	设备ID
web_id	string	Web ID

6.2 OpenAPI SDK 样例

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

# 例如，app_id= 164314 cohort id= 1001076

# 按照行流式读取，可以采取如下操作：
resp = bc.data_finder("/openapi/v1/164314/cohorts/1001076/download")
for content in resp.iter_lines():
    print(content.decode("utf-8"))

返回结果：

[分群名称]:cohort_name
[编辑者]:datarangers
[分群用户数]:1064
用户ID,stat_standard_id,device_id,web_id
7039603993451071012,ce4f5339-b261-4567-ac87-b9e560ce5f71,0,7039603993451071012
256065,5c188cbd-9066-4c3f-817b-3656ed2d32eb,0,6981656913172432419
270159,619619ce-788e-4058-acf4-82063ca81374,0,7040148471437133327
...
...
...
204677,aa67d722-6af4-41f1-9b0c-e478553a0d4e,0,6981289846937978399
243118,58e53ded-b220-4978-99ac-ee7137210b23,0,6970956560466134558

7.规则创建分群API

7.1 API 定义

Path：/openapi/v1/{app_id}/cohorts
Method: POST
Content-type: application/json
Path-parameters: 参考公共参数
Body:

{
    "cohort_name": "分群名",
    "cohort_type": 4,
    "description": "分群描述",
    "dsl_content": {},
    "refresh_rule": 1
}

字段含义说明

Field	Type	Description
cohort_name	int	分群名
cohort_type	int	分群类型，固定为4，即规则创建，表示通过dsl_content创建分群
description	string	分群描述信息
dsl_content	object	分群规则，可在前端UI配置后拷贝修改，详见7.3节
refresh_rule	int	1：手动刷新 2：每日例行刷新

Response:

{
    "code": 200,
    "message": "success",
    "data": {
        "cohort_id": 6
    }
}

字段含义说明

Field	Type	Description
cohort_id	int	创建成功的分群id

7.2 OpenAPI SDK 样例

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

# 例如，app_id= 164314

dsl = {
    "cohort_name": "openapi-创建",
    "cohort_type": 4, # 4表示规则创建
    "description": "",
    "dsl_content": {
        "periods": [],
        "app_ids": [
            164314
        ],
        "content": {
            "profile_filters": [],
            "profile_groups": [],
            "queries": [
                [
                    {
                        "show_label": "event--A--A",
                        "event_name": "any_event",
                        "event_type": "origin",
                        "next_query_label": null,
                        "sequence_first": true,
                        "logic": true,
                        "condition": {
                            "property_operation": ">",
                            "property_values": [
                                0
                            ],
                            "period": {
                                "granularity": "day",
                                "last": {
                                    "amount": 7,
                                    "unit": "day"
                                },
                                "type": "last",
                                "timezone": "Asia/Shanghai"
                            }
                        },
                        "filters": [
                            {
                                "expression": {
                                    "logic": "and",
                                    "conditions": []
                                }
                            }
                        ],
                        "event_indicator": "events"
                    }
                ]
            ],
            "query_type": "$cohort"
        },
        "version": 3
    },
    "refresh_rule": 1 # 1表示手动刷新、2表示每日刷新
}
resp = bc.data_finder("/openapi/v1/164314/cohorts"， body=dsl)
cohort_id = resp.json()["data"]["cohort_id"]

返回结果：

{
    "code": 200,
    "message": "success",
    "data": {
        "cohort_id": 6
    }
}

7.3 从前端配置并获取分群dsl（推荐）

在分群配置页面中配置好规则，然后打开浏览器控制台，接着点击“预估人数”，查看overview接口的dsl_content字段。（注意：使用dsl_content的时候，最好把show_option节点整体删除）
更多关于分群OpenAPI-DSL结构的详细说明请看文档：https://www.volcengine.com/docs/6285/196703

8.刷新分群API

注意：刷新分群是占用查询资源的，频繁调用该接口可能导致查询速度变慢。

8.1 API 定义

Path：/openapi/v1/{app_id}/cohorts/{cohort_id}/refresh
Method: GET
Content-type: application/json
Path-parameters:

Parameter	Type	Description	Required
cohort_id	int	分群id	true

Response:

{
    "code": 200,
    "message": "success",
    "data": {
        "count": 9289,
        "refresh_time": "2022-07-11",
        "refresh_timestamp": 1657534754,
        "status": 1
    }
}

字段含义说明

Field	Type	Description
count	int	刷新后分群中的人数
refresh_time	string	刷新完成的日期
refresh_timestamp	int	刷新完成的时刻的10位时间戳
status	int	刷新状态 0: 刷新中 1：成功 2：错误 4：超时 5：分群待计算

8.2 OpenAPI SDK 样例

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

# 例如，app_id= 164314 cohort_id = 6

resp = bc.data_finder("/openapi/v1/164314/cohorts/6/refresh")
print(resp.json()["data"])

返回结果：

{
    "code": 200,
    "message": "success",
    "data": {
        "count": 9289,
        "refresh_time": "2022-07-11",
        "refresh_timestamp": 1657534754,
        "status": 1
    }
}

9.上传文件创建分群API

9.1 上传文件API 定义

该接口会将本地文件上传并生成uuid_file_key，只有通过uuid_file_key才可用于OpenAPI创建或更新通过文件定义的分群。
Path：/openapi/v1/{app_id}/cohorts/upload_uuid
Method: POST
Content-type: multipart/form-data
Path-parameters: 参考公共参数
Body:

{
    "file": {二进制文件},
}

Response:

{
    "code": 200,
    "message": "success",
    "data": {
        "uuid_file_key": "{file_key}"
    }
}

字段含义说明

Field	Type	Description
uuid_file_key	str	上传成功后的file_key

文件最大限制为200m
支持的文件格式为csv
支持的表头为user_unique_id，第二行开始为具体数据

9.2 OpenAPI SDK 样例

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

# 例如，app_id= 164314

# 例如, 上传 uuids.csv
method = 'POST'
service_url = '/datafinder/openapi/v1/164314/cohorts/upload_uuid'
headers = {}  # headers 不需要显式添加'Content-Type'属性,否则会报错
files = {  # form-data 格式文件
    'file': ('uuids.csv', open('uuids.csv', 'rb'))  # key 必须为 'file',value 为上传的 csv 文件
}

resp = bc.request(method=method, service_url=service_url, headers=headers, files=files)
print(resp.content.decode('utf-8'))

返回结果：

{
    "code": 200,
    "message": "success",
    "data": {
        "uuid_file_key": "upload_uuid/164314/20220819/1eb8f3c6-4447-4e9c-a538-c1b33a1cd0e4.csv"
    }
}

9.3 创建分群API 定义

同7.1，但是body格式如下：

{
    "cohort_name": "文件创建分群-openapi",
    "description": "",
    "refresh_rule": 0, # 只能是0,表示不支持刷新
    "cohort_type": 2, # 固定为2，表示文件创建分群
    "dsl_content": {
        "uuid_file_key": "upload_uuid/164314/20220819/1eb8f3c6-4447-4e9c-a538-c1b33a1cd0e4.csv", 
        // uuid_file_key需要通过9.1接口上传文件后获取
        "file_list": [
            {
                "name": "user_unique_id_template (3).csv" //上传文件的名称
            }
        ],
        "dsl_type": "user_unique_id" // 支持user_unique_id、ssid、device_id、web_id
    }
}

10.删除创建分群API

10.1 API 定义

Path：/openapi/v1/{app_id}/cohorts/{cohort_id}
Method: DELETE
Content-type: application/json
Path-parameters:

Parameter	Type	Description	Required
cohort_id	int	分群ID	true

Response:

{
    "code": 200,
    "message": "success",
    "data": null
}

10.2 OpenAPI SDK 样例

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

调用(Python)：

# 例如，app_id= 164314 cohort id= 1001076
res = bc.data_finder('/openapi/v1/164314/cohorts/1001076', method='delete')
print(res.content)

返回结果：

{
    "code": 200,
    "message": "success",
    "data": null
}

11.修改创建分群API

11.1 API 定义

Path：/openapi/v1/{app_id}/cohorts/{cohort_id}
Method: PATCH
Content-type: application/json
Path-parameters:

Parameter	Type	Description	Required
cohort_id	int	分群ID	true

Body:
修改通过上传文件创建分群：

{
    "cohort_name": "分群名",
    "cohort_type": 2, //2为文件上传类型的分群
    "description": "分群描述",
    "dsl_content": {
        "uuid_file_key": "upload_uuid/164314/20220819/1eb8f3c6-4447-4e9c-a538-c1b33a1cd0e4.csv", 
        // uuid_file_key需要通过9.1接口上传文件后获取
        "file_list": [
            {
                "name": "user_unique_id_template (3).csv" //上传文件的名称
            }
        ],
        "dsl_type": "user_unique_id" // 支持user_unique_id、ssid、device_id、web_id
    },
    "refresh_rule": 1
}

修改规则创建分群：

{
    "cohort_name": "分群名",
    "cohort_type": 4 //4为规则上传类型的分群
    "description": "分群描述",
    "dsl_content": {},
    "refresh_rule": 1
}

Response:

{
    "code": 200,
    "message": "success",
    "data": null
}

11.2 OpenAPI SDK 样例

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

# 例如，app_id= 164314 cohort id= 1001076
body = {
    "cohort_name": "openapi-修改",
    "cohort_type": 4, // 4表示规则创建
    "description": "",
    "dsl_content": {
        "periods": [],
        "app_ids": [
            164314
        ],
        "content": {
            "profile_filters": [],
            "profile_groups": [],
            "queries": [
                [
                    {
                        "show_label": "event--A--A",
                        "event_name": "any_event",
                        "event_type": "origin",
                        "next_query_label": null,
                        "sequence_first": true,
                        "logic": true,
                        "condition": {
                            "property_operation": ">",
                            "property_values": [
                                0
                            ],
                            "period": {
                                "granularity": "day",
                                "last": {
                                    "amount": 7,
                                    "unit": "day"
                                },
                                "type": "last",
                                "timezone": "Asia/Shanghai"
                            }
                        },
                        "filters": [
                            {
                                "expression": {
                                    "logic": "and",
                                    "conditions": []
                                }
                            }
                        ],
                        "event_indicator": "events"
                    }
                ]
            ],
            "query_type": "$cohort"
        },
        "version": 3
    },
    "refresh_rule": 2 # 从1修改为2
}
resp = bc.data_finder("/openapi/v1/164314/cohorts/1001076"， body=dsl)
cohort_id = resp.json()["data"]["cohort_id"]

返回结果：

{
    "code": 200,
    "message": "success",
    "data": {
        "cohort_id": 1001076
    }
}