You need to enable JavaScript to run this app.
导航
V1.0
最近更新时间:2024.05.06 17:07:30首次发布时间:2024.04.30 15:17:28

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
}