文档中心

V1.0

最近更新时间：2023.06.28 16:18:33

首次发布时间：2022.06.15 18:49:35

1.概述

本文档提供火山引擎增长分析中旧版用户标签 OpenAPI 的使用说明。如您的环境使用的是新版标签（私有化>=4.5版本面向新客开放），请参考V2.0版本OpenAPI。

旧版标签界面示例：

新版标签示例：

2.API 公共参数

Context-path: /datatag
Path-parameters:

Parameter	Type	Description	Required
app_id	int	应用id	true
tag_name	string	标签名称	true

Response:

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

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

3.上传文件 API

3.1 API 定义

Path：/openapi/v1/app/{app_id}/tag/file/upload
Method: POST
Content-type: multipart/form-data; boundary=xxx
Path-parameters: 参考公共参数即可
Response:

{
    "code": 200,
    "message": "success",
    "data": {
        "all_count": 4,
        "load_count": 4,
        "file_key": "tag_upload_uuid/164314/20220527/564b19debe5a448396504802ab5ea69a.json",
        "deduplication_count": 0,
        "deduplication_list": []
    },
    "total_execute_time": null
}

使用multipart/form-data来进行上传文件，文件的field name固定为“file”，使用boundary来进行区分每一个field，boundary需要自定义，保证在请求内不重复即可。文件格式为csv，文件大小限制为 20M，数量上限为40W，仅支持单个文件：

第一行为表头：user_id,value，即用户id，用户对应的标签值
从第二行开始是具体的数据
如果是list的类型的话，多个value值以逗号分隔
时间类型格式，参考“finder的时间类型属性”

样例：

user_id,value
a123456,value_a
b123456,value_b
c123456,value_c,value_c1

返回结果字段含义说明：
data 返回的是一个 JSON object, 针对关键字段进行说明

Field	Type	Description
all_count	int	总的行数
load_count	int	有效数据行数
file_key	string	保存到系统的文件名，创建的标签的时候需要使用到该参数
deduplication_count	int	重复数量
deduplication_list	array	重复的用户id(元素的类型为string)

3.2 OpenAPI SDK 使用样例

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

# 例如, 上传 user_tag.csv
method = 'POST'
service_url = '/datatag/openapi/v1/app/164314/tag/file/upload'
headers = {}  # headers 不需要显式添加'Content-Type'属性,否则会报错
files = {  # form-data 格式文件
    'file': ('user_tag.csv', open('user_tag.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'))

调用(Java):

String method = "POST";
String serviceUrl = "/datatag/openapi/v1/app/164314/tag/file/upload";
HashMap<String, String> headers = null;
HashMap<String, String> params = null;
File file = new File("user_tag.csv");  // 换成指定文件的路径

String resp = bc.uploadFile(method, serviceUrl, headers, params, file);
System.out.println(resp);

调用(Go)

method := "POST"
serviceUrl := "/datatag/openapi/v1/app/164314/tag/file/upload"

fileDir, _ := os.Getwd()
fileName := "user_tag.csv"
filePath := path.Join(fileDir, fileName)

res, err := bc.UploadFile(method, serviceUrl, nil, nil, filePath)
if err != nil {
   fmt.Println(err)
   return
}
defer res.Body.Close()
data, err := ioutil.ReadAll(res.Body)
fmt.Println(err, string(data))

调用(nodejs)

let method = 'post'
let serviceUrl = '/datatag/openapi/v1/app/164314/tag/file/upload'

fileName = 'user_tag.csv'

resp = bc.uploadFile(serviceUrl, {
    method: method,
    file: fileName
}).then(res => res.json())
    .then(response => {
        console.log("response: " + JSON.stringify(response));
    })
    .catch(error => console.error('error:', error));

调用(php)

$method = 'post';
$serviceUrl = '/datatag/openapi/v1/app/164314/tag/file/upload';
$fileName = '/xxx/user_tag.csv';
$result = $this->client->uploadFile($serviceUrl, $method, null, null, $fileName);
echo $result;

返回结果：

{
    "code": 200,
    "message": "success",
    "data": {
        "all_count": 4,
        "load_count": 4,
        "file_key": "tag_upload_uuid/164314/20220527/564b19debe5a448396504802ab5ea69a.json",
        "deduplication_count": 0,
        "deduplication_list": []
    },
    "total_execute_time": null
}

4.根据上传文件创建标签 API

4.1 API 定义

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

{
    "name": "tag_test_tag",  # "name" must start with "tag_"
    "show_name": "测试标签",
    "value_type": "string",
    "description": "",
    "create_type": "upload",
    "refresh_rule": "manual",
    "tag_rule": {
        "file": {
            "file_key": "tag_upload_uuid/164314/20220527/564b19debe5a448396504802ab5ea69a.json",  # file_key 需要和上传标签数据得到的返回结果一致
            "detail": {
                "name": "user_tag.csv"
            }
        }
    }
}

字段含义说明

Field	Type	Description	Required
name	string	标签名称, 必须以"tag_"开头，应用内唯一。规则参考：用户标签增长分析-火山引擎	true
show_name	string	标签展示名称，应用内唯一。	true
value_type	string	值类型(枚举类型): int、string、float、datetime	true
description	string	描述,可为空	false
create_type	string	创建类型,这里固定是 upload	true
refresh_rule	string	刷新类型: manual、daily, 上传文件固定刷新类型为 manual	true
tag_rule.file.file_key	string	系统的文件路径,需要和上传文件 API 得到的返回结果保持一致	false
tag_rule.file.detail.name	string	文件名	false

Response:

{
    "code": 200,
    "message": "success",
    "data": {
        "tag_name": "tag_test_tag"
    },
    "total_execute_time": null
}

字段含义说明

Field	Type	Description
code	int	状态码
message	string	返回message
tag_name	string	创建成功的标签名称
total_execute_time	int	总的执行时间

4.2 OpenAPI SDK样例

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

method = 'POST'
service_url = '/datatag/openapi/v1/app/164314/tag'
body = {
    "name": "tag_test_tag", 
    "show_name": "测试标签",
    "value_type": "string",
    "description": "",
    "create_type": "upload",
    "refresh_rule": "manual",
    "tag_rule": {
        "file": {
            "file_key": "tag_upload_uuid/164314/20220527/564b19debe5a448396504802ab5ea69a.json",
            "detail": {
                "name": "user_tag.csv"
            }
        }
    }
}
resp = bc.request(method=method, service_url=service_url, body=body)
print(resp.content.decode('utf-8'))

调用(Java):

String method = "POST";
String serviceUrl = "/datatag/openapi/v1/app/164314/tag";
HashMap<String, String> headers = null;
HashMap<String, String> params = null;
String body = "{\n" +
        "    \"name\": \"tag_test_tag\",\n" +
        "    \"show_name\": \"测试标签\",\n" +
        "    \"value_type\": \"string\",\n" +
        "    \"description\": \"\",\n" +
        "    \"create_type\": \"upload\",\n" +
        "    \"refresh_rule\": \"manual\",\n" +
        "    \"tag_rule\": {\n" +
        "        \"file\": {\n" +
        "            \"file_key\": \"tag_upload_uuid/164314/20220527/564b19debe5a448396504802ab5ea69a.json\",\n" +
        "            \"detail\": {\n" +
        "                \"name\": \"user_tag.csv\"\n" +
        "            }\n" +
        "        }\n" +
        "    }\n" +
        "}";

String resp = bc.request(method, serviceUrl, headers, params, body);
System.out.println(resp);

返回结果：

{
    "code": 200,
    "message": "success",
    "data": {
        "tag_name": "tag_test_tag"
    },
    "total_execute_time": null
}

5.查询标签最新结果 API

5.1 API定义

Path：/openapi/v1/app/{app_id}/tag/{tag_name}/result
Method: GET
Path-parameters: 参考公共参数即可
Response:

{
    "code": 200,
    "message": "success",
    "data": {
        "app_id": 164314,
        "tag_id": 240,
        "tag_name": "tag_testxxxx_wyx",
        "status": "success",
        "calculate_result": {
            "total": 28762,
            "details": [
                {
                    "name": "标签值1",
                    "count": 28762,
                    "percent": 1.0,
                    "pdate": "2022-05-05"
                }
            ],
            "trace_id": "12b35322-861f-4172-9d1b-5b5e9d8b5d7b",
            "calculate_date": 1651728069000,
            "timezone": "Asia/Shanghai",
            "tag_status": "success",
            "begin_at": 1651728069000,
            "end_at": 1651728092000,
            "pdate": "2022-05-05",
            "p_date": "2022-05-05"
        },
        "calculate_date": 1651728069000,
        "begin_at": 1651728069000,
        "end_at": 1651728092000,
        "timezone": "Asia/Shanghai",
        "pdate": "2022-05-05"
    },
    "total_execute_time": null
}

字段含义说明
data 返回的是一个 JSON object, 针对关键字段进行说明

Field	Type	Description
app_id	int	应用id
tag_id	int	标签id
tag_name	string	标签名称
status	string	计算状态
calculate_result	object	计算结果
calculate_result.total	int	数据总行数
calculate_result.details	object	计算结果详情
calculate_result.details.name	string	标签值
calculate_result.details.count	int	属于该标签值的数据行数
calculate_result.details.percent	double	属于该标签值的数据行数在数据总行数的占比
calculate_result.details.pdate	string	已废弃,标签计算开始的时间戳
calculate_date	int	已废弃,标签计算开始的时间戳
begin_at	int	已废弃,标签计算开始的时间戳(同calculate_date)
end_at	int	已废弃,标签计算结束的时间戳
timezone	string	时区
pdate	string	已废弃,最新结果的计算日期
p_date	string	最新结果的计算日期(建议使用)

5.2 OpenAPI SDK 样例

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

method = 'GET'
service_url = '/datatag/openapi/v1/app/164314/tag/tag_testxxxx_wyx/result'

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

返回结果：

{
    "code": 200,
    "message": "success",
    "data": {
        "app_id": 164314,
        "tag_id": 240,
        "tag_name": "tag_testxxxx_wyx",
        "status": "success",
        "calculate_result": {
            "total": 28762,
            "details": [
                {
                    "name": "标签值1",
                    "count": 28762,
                    "percent": 1.0,
                    "pdate": "2022-05-05"
                }
            ],
            "trace_id": "12b35322-861f-4172-9d1b-5b5e9d8b5d7b",
            "calculate_date": 1651728069000,
            "timezone": "Asia/Shanghai",
            "tag_status": "success",
            "begin_at": 1651728069000,
            "end_at": 1651728092000,
            "pdate": "2022-05-05",
            "p_date": "2022-05-05"
        },
        "calculate_date": 1651728069000,
        "begin_at": 1651728069000,
        "end_at": 1651728092000,
        "timezone": "Asia/Shanghai",
        "pdate": "2022-05-05"
    },
    "total_execute_time": null
}

6.查询标签历史计算结果 API

6.1 API 定义

Path：/openapi/v1/app/{app_id}/tag/{tag_name}/result/history
Method: POST
Content-type: application/json
Path-parameters: 参考公共参数即可
Body:

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

字段含义说明
整个 json 是一个 period 字段,详见开发者指南->数据开放->OpenAPI->查询API->5.2.2periods字段
Response:

{
    "code": 200,
    "message": "success",
    "data": {
        "app_id": 164314,
        "tag_name": "tag_testxxxx_wyx",
        "calculate_results": [
            {
                "total": 28762,
                "details": [
                    {
                        "name": "标签值1",
                        "count": 28762,
                        "percent": 1.0,
                        "pdate": "2022-05-05"
                    }
                ],
                "trace_id": "8a23c9b6-0d05-4cee-a1b6-f2977a489581",
                "calculate_date": 1651728069000,
                "timezone": "Asia/Shanghai",
                "tag_status": "success",
                "begin_at": 1651728069000,
                "end_at": 1651728092000,
                "pdate": "2022-05-05",
                "p_date": "2022-05-05"
            }
        ],
        "has_history": true
    },
    "total_execute_time": null
}

字段含义说明
data 返回的是一个 JSON object, 针对关键字段进行说明

Field	Type	Description
app_id	int	应用id
tag_name	string	标签名称
calculate_results	array	查询时间段的计算结果集
calculate_results.total	int	当前分区时间内的数据总行数
calculate_results.details	object	当前分区时间内的数据详情
calculate_results.details.name	string	标签值
calculate_results.details.count	int	属于该标签值的数据行数
calculate_results.details.percent	double	属于该标签值的数据行数在数据总行数的占比
calculate_results.details.pdate	string	冗余字段,同calculate_results.p_date
calculate_results.calculate_date	int	当前分区标签计算开始的时间戳
calculate_results.timezone	string	当前分区的时区
calculate_results.tag_status	string	当前分区的计算状态
calculate_results.begin_at	int	已废弃,当前分区标签计算开始的时间戳
calculate_results.end_at	int	已废弃,当前分区标签计算结束的时间戳
calculate_results.p_date	string	当前分区计算日期(建议使用)

6.2 OpenAPI SDK 样例

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

method = 'POST'
service_url = '/datatag/openapi/v1/app/164314/tag/tag_testxxxx_wyx/result/history'
body = {
    "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
}

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

返回结果：

{
    "code": 200,
    "message": "success",
    "data": {
        "app_id": 164314,
        "tag_name": "tag_testxxxx_wyx",
        "calculate_results": [
            {
                "total": 28762,
                "details": [
                    {
                        "name": "标签值1",
                        "count": 28762,
                        "percent": 1.0,
                        "pdate": "2022-05-05"
                    }
                ],
                "trace_id": "8a23c9b6-0d05-4cee-a1b6-f2977a489581",
                "calculate_date": 1651728069000,
                "timezone": "Asia/Shanghai",
                "tag_status": "success",
                "begin_at": 1651728069000,
                "end_at": 1651728092000,
                "pdate": "2022-05-05",
                "p_date": "2022-05-05"
            }
        ],
        "has_history": true
    },
    "total_execute_time": null
}

7.导出标签 API

7.1 API 定义

Path：/openapi/v1/app/{app_id}/tag/{tag_name}/download
Method: POST
Content-type: application/json
Path-parameters: 参考公共参数即可
Body:

{
    "type": "user",
    "condition": {
        "property_operation": "is_not_null",
        "snapshot": {
            "type": "day",
            "day": "2022-05-05"
        }
    },
    "period": {
        "timezone": "Asia/Shanghai"
    }
}

Field	Type	Description	Required
type	string	值为"distribution"下载概况	true
值为"user"下载详情
condition	object	选择条件	true
condition.property_operation	string	运算条件	true
condition.snapshot	object	过滤日期	false
period	object	详见开发者指南->数据开放->OpenAPI->查询API->5.2.2periods字段	false

Response:

二进制数据流

7.2 OpenAPI SDK 样例

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

method = 'POST'
service_url = '/datatag/openapi/v1/app/164314/tag/tag_testxxxx_wyx/download'
body = {
    "type": "user",
    "condition": {
        "property_operation": "is_not_null",
        "snapshot": {
            "type": "day",
            "day": "2022-05-05"
        }
    },
    "period": {
        "timezone": "Asia/Shanghai"
    }
}

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

返回结果：(二进制数据流, 以下只显示前 5 行数据)

user_id,stat_standard_id,device_id,tag_value
2514296972,6866a6a2-5d06-4594-a48e-fda240d3d9ba,444644287588669,标签值1
25241114489161081,0326b33f-0c8c-4d9f-87ae-a33e25ed1528,3312170353296040,标签值1
925791154365952304,ce85d5ad-cf51-40f9-9228-b3ff903655e2,585382263260008,标签值1
43294216333,686a7f08-4860-41d3-947d-4f90cf3bdbf6,3751957918129043,标签值1
922291870168956341,0d46fbd6-c068-484a-a5de-72a2ad39b4c4,22433244645320,标签值1

8.查询标签基本信息 API

8.1 API 定义

Path：/openapi/v1/app/{app_id}/tag/{tag_name}
Method: GET
Path-parameters: 参考公共参数即可
Response:

{
    "code": 200,
    "message": "success",
    "data": {
        "id": 456,
        "app_id": 164314,
        "category_id": 0,
        "name": "tag_test_tag",
        "show_name": "测试标签",
        "value_type": "string",
        "description": "",
        "status": "fail",
        "toggle": "enable",
        "create_type": "upload",
        "tag_rule": {
            "rules": null,
            "sql": null,
            "file": {
                "detail": {
                    "name": "user_tag.csv"
                },
                "file_key": "tag_upload_uuid/164314/20220523/c93ab7cbd0d24c2584a662f85e12cb02.json"
            }
        },
        "refresh_rule": "manual",
        "creator": "10000340",
        "user_info": null,
        "process_status": null,
        "created_at": 1653301122000,
        "updated_at": 1653301290000
    },
    "total_execute_time": null
}

字段含义说明
data 返回的是一个 JSON object, 针对关键字段进行说明

Field	Type	Description
app_id	int	应用id
name	string	标签名称
show_name	string	标签展示名
value_type	string	值类型(枚举类型): int、string、float、datetime
description	string	描述
status	string	计算状态
create_type	string	创建类型
tag_rule	object	创建规则
refresh_rule	string	刷新类型:manual、daily
creator	int	创建人id
created_at	int	创建时间时间戳
updated_at	int	更新时间时间戳

8.2 OpenAPI SDK 样例

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

method = 'GET'
service_url = '/datatag/openapi/v1/app/164314/tag/tag_test_tag'

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

返回结果：

{
    "code": 200,
    "message": "success",
    "data": {
        "id": 456,
        "app_id": 164314,
        "category_id": 0,
        "name": "tag_test_tag",
        "show_name": "测试标签",
        "value_type": "string",
        "description": "",
        "status": "fail",
        "toggle": "enable",
        "create_type": "upload",
        "tag_rule": {
            "rules": null,
            "sql": null,
            "file": {
                "detail": {
                    "name": "user_tag.csv"
                },
                "file_key": "tag_upload_uuid/164314/20220523/c93ab7cbd0d24c2584a662f85e12cb02.json"
            }
        },
        "refresh_rule": "manual",
        "creator": "10000340",
        "user_info": null,
        "process_status": null,
        "created_at": 1653301122000,
        "updated_at": 1653301290000
    },
    "total_execute_time": null
}

9.查询应用下所有标签 API

9.1 API 定义

Path：/openapi/v1/app/{app_id}/tag
Method: GET
Path-parameters: 参考公共参数即可
Response:

{
    "code": 200,
    "message": "success",
    "data": [
        {
            "id": 240,
            "app_id": 164314,
            "category_id": 0,
            "name": "tag_testxxxx_wyx",
            "show_name": "testxxxx_wyx",
            "value_type": "string",
            "description": "",
            "status": "success",
            "toggle": "enable",
            "create_type": "custom",
            "tag_rule": null,
            "refresh_rule": "manual",
            "creator": "213659",
            "user_info": null,
            "process_status": null,
            "created_at": 1644563482000,
            "updated_at": 1651728105000
        },
        {
            "id": 216,
            "app_id": 164314,
            "category_id": 0,
            "name": "tag_222",
            "show_name": "2222",
            "value_type": "string",
            "description": "",
            "status": "success",
            "toggle": "enable",
            "create_type": "custom",
            "tag_rule": null,
            "refresh_rule": "manual",
            "creator": "224443",
            "user_info": null,
            "process_status": null,
            "created_at": 1641957584000,
            "updated_at": 1642434178000
        }
    ],
    "total_execute_time": null
}

字段含义说明
data 返回的是一个 JSON array, 针对关键字段进行说明

Field	Type	Description
id	int	标签id
app_id	int	标签所属应用id
name	string	标签名称
show_name	string	标签展示名称
value_type	string	值类型(枚举类型): int、string、float、datetime
description	string	描述
status	string	计算状态
create_type	string	创建类型
tag_rule	object	创建规则
refresh_rule	string	刷新类型:manual、daily
creator	string	创建人id
created_at	int	创建时间时间戳
updated_at	int	更新时间时间戳

9.2 OpenAPI SDK 样例

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

method = 'GET'
service_url = '/datatag/openapi/v1/app/164314/tag'

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

返回结果：

{
    "code": 200,
    "message": "success",
    "data": [
        {
            "id": 240,
            "app_id": 164314,
            "category_id": 0,
            "name": "tag_testxxxx_wyx",
            "show_name": "testxxxx_wyx",
            "value_type": "string",
            "description": "",
            "status": "success",
            "toggle": "enable",
            "create_type": "custom",
            "tag_rule": null,
            "refresh_rule": "manual",
            "creator": "213659",
            "user_info": null,
            "process_status": null,
            "created_at": 1644563482000,
            "updated_at": 1651728105000
        },
        {
            "id": 216,
            "app_id": 164314,
            "category_id": 0,
            "name": "tag_222",
            "show_name": "2222",
            "value_type": "string",
            "description": "",
            "status": "success",
            "toggle": "enable",
            "create_type": "custom",
            "tag_rule": null,
            "refresh_rule": "manual",
            "creator": "224443",
            "user_info": null,
            "process_status": null,
            "created_at": 1641957584000,
            "updated_at": 1642434178000
        }
    ],
    "total_execute_time": null
}

10.触发标签计算 API

10.1 API 定义

Path：/app/{app_id}/tag/{tag_name}/calculation
Method: POST
Path-parameters: 参考公共参数即可
Response:

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

字段含义说明

Field	Type	Description
code	int	状态码
message	string	返回message
data	null	无返回数据
total_execute_time	int	总的执行时间

10.2 OpenAPI SDK 样例

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

method = 'POST'
service_url = '/datatag/openapi/v1/app/164314/tag/tag_test_tag/calculation'

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

返回结果：

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