1. 文件

1.1. 文件上传

1.1.1. API 说明

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

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

1.1.3. Method: POST

1.1.4. 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	文件总大小（字节），用于判断文件大小限制和磁盘剩余空间是否足够，不用于判断文件完整性，不得大于2GB (2147483648L)
slice_amount	integer	例：1	true	文件总数量
index	integer	例：0	true	文件索引（第几个文件），从 0 开始
file_name	string	例：test.txt	true	文件名称（同一批文件名称需一致）
file_md5	string	例：2724581a42dae8d9f71544c6fdaf3216	true	整个文件的 md5 值
current_md5	string	例：c1afb715b12ac8caf3df0aead131d251	true	当前文件的 md5 值

RequestBody:

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

1.1.5. Response

ResponseBody:

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

1.1.6. 使用 curl 命令模拟请求 api

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

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}

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

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样例

注：需引入 apache httpclient 和 apache httpmime 包1.3. 使用 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 上传创建标签

2.1.1. API 说明

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

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

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

示例：

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

2.1.3. Method: PUT

2.1.4. 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有值时必须传

2.1.5. Response

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

2.1.6. 使用 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":{}}}

2.2. 修改标签

2.2.1. API 说明

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

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

2.2.3. Method: POST

2.2.4. 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	操作指定日期的数据

2.2.5. Response

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

2.2.6. 使用 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说明

2.3.2. URL: /api/v2/sps/user_tag_dir

2.3.3. Method: POST

2.3.4. 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 即算创建成功

2.3.6. 使用 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说明

查询所有的标签目录

2.4.2. URL: /api/v2/sps/user_tag_dir

2.4.3. Method: GET

2.4.4. Request

RequestParam:

key	type	value	required	description
project	string	例: default	true	项目英文名
token	string		true	token获取文档
need_user_tag	boolean		true	固定值：false

2.4.5. Response

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

2.4.6. 使用 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": [] } ]