本文档提供火山引擎增长分析中旧版用户标签 OpenAPI 的使用说明。如您的环境使用的是新版标签(私有化>=4.5版本面向新客开放),请参考V2.0版本OpenAPI。
旧版标签界面示例:
新版标签示例:
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" }
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 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) |
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 }
本OpenAPI为您提供根据上传文件创建标签的能力,当前暂不支持追加或修改已创建好的标签。
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 | 总的执行时间 |
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 }
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 | 最新结果的计算日期(建议使用) |
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 }
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 | 当前分区计算日期(建议使用) |
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 }
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 | false |
Response:
二进制数据流
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
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 | 更新时间时间戳 |
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 }
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 | 更新时间时间戳 |
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 }
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 | 总的执行时间 |
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 }