You need to enable JavaScript to run this app.
导航
分群 OpenAPI
最近更新时间:2024.05.29 16:21:46首次发布时间:2022.07.13 16:18:58

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:
注意:

  1. response的content/type为text/csv;charset=utf-8
  2. 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
    }
}