菜单

「导入创建」标签

文件

1.1 文件上传

API 说明

上传文件，支持文件切割分片上传

URL: /api/v2/sps/file/upload

Method: POST

Request

RequestHeader:

key value 描述
Content-Type multipart/form-data  
Cookie api_server_id

api_server_id 的值在 8 个字符以内

分片上传时，需要保证同一个文件的分片请求中的 api_server_id 的值是一样的

tips：

集群环境，进行分片上传的时候，需要保证所有的分片请求打到同一台机器；

可以将分片请求的第一次请求返回的结果中的全部 http header 信息，在后续分片请求的 http header 中传入，来保证所有分片请求打到同一台服务器。

key type value required description
project string 例: default true 项目英文名
token string 例：75eb2cfcbb73c40dd106d3d2f75628920517d77726b01400487326722d1082ac true

token 获取文档
file_size integer 例：1024 true

文件总大小（字节），用于判断文件大小限制和磁盘剩余空间是否足够，不用于判断文件完整性，不得大于 2 GB（2147483648L）。

单次上传的文件大小不能超过 100 M，超过 100 M 需要将文件切片上传。
slice_amount integer 例：1 true 文件总数量（切片的时候，该值大于 1）
index integer 例：0 true 文件索引（第几个文件），从 0 开始
file_name string 例：test.txt true 文件名称（同一批文件名称需一致）
file_md5 string 例：2724581a42dae8d9f71544c6fdaf3216 true 整个文件的 md5 值
current_md5 string 例：c1afb715b12ac8caf3df0aead131d251 true （切片文件上传时候，指定当前分配的 MD5）当前文件的 md5 值

RequestBody:

key type value required description
file file   true 文件内容；文件内容超过 100 M 需要分片上传

Response

ResponseBody:

key

 type

value

description
is_finished boolean true/false 是否完成全部文件上传
file_name string   最终存储在服务器上的临时文件名称，只有 is_finished = true 时才会返回该字段
error string   上传文件失败时的异常信息

使用 curl 命令模拟请求 API

上传第一个文件，文件内容为：

111
222
333
444

curl 命令：

curl -X POST 'http://127.0.0.1:8107/api/v2/sps/file/upload?project=default&token=75eb2cfcbb73c40dd106d3d2f75628920517d77726b01400487326722d1082ac&file_size=32&slice_amount=2&index=0&file_name=test.txt&file_md5=2724581a42dae8d9f71544c6fdaf3216&current_md5=c1afb715b12ac8caf3df0aead131d251' \
  -F "file=@文件全路径"  \
  -H 'Cookie: sps_web_route=123456' \
  --compressed \
  --insecure

返回值：

{"is_finished":false}

上传第二个文件，文件内容为：

123
123
123
123

curl 命令：

curl -X POST 'http://127.0.0.1:8107/api/v2/sps/file/upload?project=default&token=75eb2cfcbb73c40dd106d3d2f75628920517d77726b01400487326722d1082ac&file_size=32&slice_amount=2&index=1&file_name=test.txt&file_md5=2724581a42dae8d9f71544c6fdaf3216&currentt_md5=11a84a45830d980769eecab371593936' \
  -H 'Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryYuxPY2tAQZiUcDIR' \
  --data-binary $'------WebKitFormBoundaryYuxPY2tAQZiUcDIR\r\nContent-Disposition: form-data; name="file"; filename="blob"\r\nContent-Type: application/octet-stream\r\n\r\n123\n123\n123\n123\n\r\n------WebKitFormBoundaryYuxPY2tAQZiUcDIR--\r\n' \
  -H 'Cookie: sps_web_route=123456' \
  --compressed \
  --insecure

返回值：

{"to_hdfs":"true","file_name":"dGVzdDEwMy50eHQCVuSFdUoQ","is_finished":true}

1.1.7. java 样例

使用 Java 代码调用 API

public static String upload(File file) throws IOException {
    String url = "http://127.0.0.1:8107/api/v2/sps/file/upload";
    HttpPost httpPost = new HttpPost(url);
    try (FileInputStream fileInputStream = new FileInputStream(file);
         CloseableHttpClient httpClient = HttpClients.createDefault()) {
        String md5 = DigestUtils.md5Hex(new FileInputStream(file));
        MultipartEntityBuilder builder = MultipartEntityBuilder.create();
        builder.setCharset(StandardCharsets.UTF_8);
        builder.setMode(HttpMultipartMode.BROWSER_COMPATIBLE);

        builder.addTextBody("project", "default");
        builder.addTextBody("token", "75eb2cfcbb73c40dd106d3d2f75628920517d77726b01400487326722d1082ac");
        builder.addTextBody("file_size", String.valueOf(file.length()));
        builder.addTextBody("slice_amount", "1");
        builder.addTextBody("index", "0");
        builder.addTextBody("file_name", file.getName());
        builder.addTextBody("file_md5", md5);
        builder.addTextBody("current_md5", md5);
        builder.addBinaryBody("file", fileInputStream, ContentType.MULTIPART_FORM_DATA, file.getName());

        HttpEntity entity = builder.build();
        httpPost.setEntity(entity);
        HttpResponse response = httpClient.execute(httpPost);
        HttpEntity responseEntity = response.getEntity();
        if (responseEntity != null) {
            return EntityUtils.toString(responseEntity, StandardCharsets.UTF_8);
        }
        return "";
    }
}

1.1.8 postman 样例

2. 标签

2.1. ID 上传创建标签

API 说明

通过上传文件创建标签，支持选择是否将文件中不在当前全量用户列表中的 ID 同步到全量表中。

通过上传 用户属性与属性对应的标签值 来筛选目标用户并给用户打标签，通过属性筛选用户的方式分为两种：

  • 若上传文件中用户属性为 设备 ID/登录 ID 可通过 ID 匹配或保留全部上传 ID 的方式筛选目标用户
  • 若上传文件中用户属性为用户的其他属性，只能通过属性匹配的方式筛选目标用户

示例：

URL: /api/v2/sps/user_tags/upload

Method: PUT

Request

RequestParam:

key

 type

value

 required

description
project string 例: default true 项目英文名
token string   true token 获取文档

RequestHeader:

key

value
Content-Type application/json;charset=utf-8

RequestBody:

key

 type

value

required

description
name   string 例：user_tag_1 true

标签英文名（唯一标识名）

必须以 user_tag_ 开头
cname   string 例：标签1 true 标签中文名（显示名）
data_type   string 例：STRING、BOOL、LIST、NUMBER、DATETIME true 标签值的数据类型
source_type   integer   true 固定值：5
status   string   true 固定值：RUNNING

dir_id

   integer  例：1 true

标签目录 ID，默认放置于未分类目录

通过下文 2.4.2 描述的接口：/api/v2/sps/user_tag_di/ 获取目录信息
upload_content   object   true  标签上传规则信息

   

 upload_filename string 例：dGVzdDEwMy50eHQCVuSFdUoQ false

上传文件产生的临时文件名，由上传文件的接口返回

该项为空时表示只创建标签，暂不上传文件

   

 matched_field string   false

需要上传的属性，通过属性匹配来筛选目标用户：

可选值 user.$first_id、user.$second_id、以及其他用户列表中的属性

可以为空，upload_filename 有值时必须传
    sync_profile boolean 例：true/false false

是否保留上传文件中不在全量列表中的用户：

只在 matched_field 选择 user.$first_id、user.$second_id 时生效，选择其他属性不支持将属性同步到全量用户列表。

使用 user.$first_id、user.$second_id 都是使用 distinct_id 匹配用户

  • true：保留上传文件中不在全量表中的用户，会将这部分用户同步到全量表
    • user.$first_id 按照 设备 ID 同步用户
    • user.$second_id 按照 登录 ID 同步用户
  • false：仅保留上传文件中存在于全量表中的用户

可以为空，upload_filename 有值时必须传

   

 upload_type string   false

 固定值：CREATE

可以为空，upload_filename 有值时必须传
    data_format string   false

文件内容格式，固定值：JSON、CSV_FILE、LINE_OF_DISTINCT_ID

JSON：json 格式；property 表示匹配属性值，value 表示标签值，类型需要跟「-t --data_type」的类型保持一致；分群的 value 固定为 true；例如：{"property":"xxxxx","value":"xxxx"}

CSV_FILE：csv 文件格式，逗号分割；第一列表示匹配属性值；第二例为标签值， LIST 类型的标签值用「、」分割；例如：

749f8ca636a8a098,北京、上海、广州

LINE_OF_DISTINCT_ID：仅支持一列，一行即为一列；仅支持分群或 BOOL 类型的标签

可以为空，upload_filename 有值时必须传

Response

HTTP 状态码返回 200 即算创建成功

使用 curl 命令模拟请求 API

curl 命令：

curl 'http://127.0.0.1:8107/api/v2/sps/user_tags/upload?project=default&token=75eb2cfcbb73c40dd106d3d2f75628920517d77726b01400487326722d1082ac' \
  -X 'PUT' \
  -H 'Content-Type: application/json' \
  --data-binary '{"cname":"测试上传创建标签2","name":"user_tag_test2","source_type":5,"status":"RUNNING","upload_content":{"upload_filename":"dGVzdDEwMy50eHQCVuSFdUoQ","sync_profile":false,"matched_field":"user.$first_id","upload_type":"CREATE", "data_format":"JSON"},"data_type":"STRING","dir_id":1}' \
  --compressed \
  --insecure

返回值：

{"id":569,"name":"user_tag_test2","cname":"测试上传创建标签2","dir_id":1,"user_name":"平台管理员","data_type":"BOOL","unit":"DAY","source_type":5,"is_routine":false,"status":"RUNNING","app_push_list":[],"failed_partition_count":0,"last_succeed_partition":{},"last_partition_info":{"base_time":"2020-09-11 00:00:00","start_time":"2020-09-11 16:33:04","finished_time":"2020-09-11 16:33:04","user_count":0,"status":"NEW","failed_message":{}}}

标签

API 说明

修改标签信息，支持修改标签中文名；支持文件上传重新计算标签。

URL: /api/v2/sps/user_tags/{id}/upload

Method: POST

Request

RequestParam:

key type value required description
project string 例: default true 项目英文名
token string   true token 获取文档

PathVariable

key type value required description
id integer 例：1 true url 路径变量，标签的 id

RequestHeader:

key value
Content-Type application/json;charset=utf-8

RequestBody

key type value required description
name   string   true

标签英文名（唯一标识名）

必须以 user_tag_ 开头 不能修改，传创建时的值
cname   string 例：标签1 true 修改后的标签中文名（显示名）
data_type   string   true 标签的数据类型，不能修改，传创建时的值
dir_id   string   true 标签目录 ID，建议传创建标签时的值；跟创建时的值不一样时，会更新
source_type   integer   true 固定值：5
upload_content   object   false 重新上传文件时，必须传。
    upload_filename string 例：dGVzdDEwMy50eHQCVuSFdUoQ false 上传文件产生的临时文件名，由上传文件的接口返回
    matched_field string   false

需要上传的属性，通过属性匹配来筛选目标用户：

可选值 user.$first_id、user.$second_id、以及其他用户列表中的属性

可以为空，upload_filename 有值时必须传
    sync_profile boolean 例：true/false false

是否保留上传文件中不在全量列表中的用户：

只在 matched_field 选择 user.$first_id、user.$second_id 时生效，选择其他属性不支持将属性同步到全量用户列表。

使用 user.$first_id、user.$second_id 都是使用 distinct_id 匹配用户

  • true：保留上传文件中不在全量表中的用户，会将这部分用户同步到全量表
    • user.$first_id 按照设备 ID 同步用户
    • user.$second_id 按照登录 ID 同步用户
  • false：仅保留上传文件中存在于全量表中的用户
可以为空，upload_filename 有值时必须传
    upload_type string   false

可选值：CREATE、OVERWRITE

CREATE：第一次上传

OVERWRITE：覆盖上传

可以为空，upload_filename 有值时必须传
    data_format string   false

文件内容格式，固定值：JSON、CSV_FILE、LINE_OF_DISTINCT_ID

JSON：json 格式；property 表示匹配属性值，value 表示标签值，类型需要跟「-t --data_type」的类型保持一致；分群的 value 固定为 true；例如：{"property":"xxxxx","value":"xxxx"}

CSV_FILE：csv 文件格式，逗号分割；第一列表示匹配属性值；第二例为标签值， LIST 类型的标签值用「、」分割；例如：

749f8ca636a8a098,北京、上海、广州

LINE_OF_DISTINCT_ID：仅支持一列，一行即为一列；仅支持分群或 BOOL 类型的标签

可以为空，upload_filename 有值时必须传
    base_time string 例：日期格式 yyyy-MM-dd false 操作指定日期的数据

Response

HTTP 状态码返回 200 即算调用成功

使用 curl 命令模拟请求 API

curl 命令：

curl 'http://127.0.0.1:8107/api/v2/sps/user_tags/14/upload?project=default&token=0cde93ddaa12fb940f7dacc93fd00db394a213a56f820c5bb00aaa8acf4ed156' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  --data-binary '{"name":"标签英文名","cname":"导入标签_改个名字","data_type":"STRING","source_type":5,"status":"RUNNING","dir_id":1,"upload_content":{"upload_filename":"dGVzdDEwMy50eHfdsafwer","sync_profile":false,"matched_field":"user.$first_id","upload_type":"OVERWRITE", "data_format":"JSON"}}' \
  --compressed \
  --insecure

返回值：

{"id":14,"name":"user_group_test2","cname":"导入标签_改个名字","user_name":"平台管理员","user_id":2,"create_time":"2020-10-27 15:35:41","data_type":"BOOL","unit":"DAY","source_type":5,"is_routine":false,"status":"RUNNING","app_push_list":[],"failed_partition_count":0,"last_succeed_partition":{"base_time":"2020-10-27 00:00:00","start_time":"2020-10-27 15:46:46","finished_time":"2020-10-27 15:47:38","user_count":1,"status":"SUCCEED"},"last_partition_info":{"base_time":"2020-10-27 00:00:00","start_time":"2020-10-27 15:46:46","finished_time":"2020-10-27 15:47:38","user_count":1,"status":"SUCCEED","failed_message":{}}}

2.3. 创建标签目录

2.3.1. API 说明

创建一个标签目录，标签目录名称不能重复。

URL: /api/v2/sps/user_tag_dir

Method: POST

Request

RequestParam:

key type value required description
project string 例: default true 项目英文名
token string   true token 获取文档
parents boolean   false

默认 false

为 true 时，效果类似 mkdir -p 创建多级目录

RequestHeader:

key value
Content-Type application/json;charset=utf-8

RequestBody:

key type value required description
id   integer 例：1 false 目录 ID
cname   string 例：标签目录 1 true 目录名
type   string 例：DIR true 类型，固定：DIR
parent   object   false

上级目录，创建子目录时必传；不传默认为一级目录(跟「未分类」目录同级)
    id integer 例：1 false 上级目录中的 ID，RequestParam 中的 parents 参数为 false 时，必传
    cname string 例：上级目录 1 true 上级目录中的目录名
    type string 例：DIR true 上级目录中的类型，固定值：DIR
    parent object   false 上级目录，结构同上

2.3.5. Response

HTTP 状态码返回 200 即算创建成功

使用 curl 命令模拟请求 API

创建一级目录

curl 'http://127.0.0.1:8107/api/v2/sps/user_tag_dir?project=default&token=0cde93ddaa12fb940f7dacc93fd00db394a213a56f820c5bb00aaa8acf4ed156&parents=false' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  --data-binary '{"cname":"测试100","type":"DIR"}' \
  --compressed \
  --insecure

返回值：

{"id": 61, "cname": "测试100", "type": "DIR" }

创建子目录一：

curl 'http://127.0.0.1:8107/api/v2/sps/user_tag_dir?project=default&token=0cde93ddaa12fb940f7dacc93fd00db394a213a56f820c5bb00aaa8acf4ed156&parents=false' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  --data-binary '{"cname":"测试300","type":"DIR","parent":{"id":1,"cname":"未分类","type":"DIR"}}' \
  --compressed \
  --insecure

返回值：

{"id": 62, "cname": "测试300", "type": "DIR", "parent": {"id": 1, "cname": "未分类", "type": "DIR"} }

创建子目录二：

curl 'http://127.0.0.1:8107/api/v2/sps/user_tag_dir?project=default&token=0cde93ddaa12fb940f7dacc93fd00db394a213a56f820c5bb00aaa8acf4ed156&parents=false' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  --data-binary '{"cname":"测试400","type":"DIR","parent":{"id": 62, "cname": "测试300", "type": "DIR", "parent": {"id": 1, "cname": "未分类", "type": "DIR"} }}' \
  --compressed \
  --insecure

返回值：

{"id": 63, "cname": "测试400", "type": "DIR", "parent": {"id": 62, "cname": "测试300", "type": "DIR", "parent": {"id": 1, "cname": "未分类", "type": "DIR"} }}

创建多级目录

# 注意 RequestParma 中的 parents 的值是 true
curl 'http://127.0.0.1:8107/api/v2/sps/user_tag_dir?project=default&token=0cde93ddaa12fb940f7dacc93fd00db394a213a56f820c5bb00aaa8acf4ed156&parents=true' \
  -X 'POST' \
  -H 'Content-Type: application/json' \
  --data-binary '{"cname": "测试多级", "type": "DIR", "parent": {"cname": "父级二", "type": "DIR", "parent": {"cname": "父级一", "type": "DIR"} }}' \
  --compressed \
  --insecure

返回值：

{"id": 65, "cname": "测试多级", "type": "DIR", "parent": {"id": 64, "cname": "父级二", "type": "DIR", "parent": {"id": 63, "cname": "父级一", "type": "DIR"} }}

2.4. 查询标签目录

2.4.1. API 说明

查询所有的标签目录

URL: /api/v2/sps/user_tag_dir

Method: GET

Request

RequestParam:

key

 type

value

 required

description
project string 例: default true 项目英文名
token string   true

token 获取文档
need_user_tag boolean   true

固定值：false

Response

http 状态码返回 200 即算调用成功

使用 curl 命令模拟请求 API

查询目录

curl 'http://127.0.0.1:8107/api/v2/sps/user_tag_dir?project=default&token=0cde93ddaa12fb940f7dacc93fd00db394a213a56f820c5bb00aaa8acf4ed156&need_user_tag=false' \
  -X 'GET' \
  --compressed \
  --insecure

返回值：

[{"type": "DIR", "id": 1, "cname": "未分类", "items": [{"type": "DIR", "id": 43, "cname": "新增分类", "items": [] }, {"type": "DIR", "id": 58, "cname": "测试100", "items": [{"type": "DIR", "id": 59, "cname": "测试200", "items": [] }, {"type": "DIR", "id": 60, "cname": "测试300", "items": [] } ] } ] }, {"type": "DIR", "id": 55, "cname": "新增分类", "items": [] }, {"type": "DIR", "id": 54, "cname": "测试目录", "items": [] } ]
上一个
标签 API
下一个
分群API
最近修改: 2025-05-23