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-Typemultipart/form-data
Cookieapi_server_id

api_server_id的值在8个字符以内

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

tips:

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

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




key

type

value

required

description

projectstring例: defaulttrue项目英文名
tokenstring例:75eb2cfcbb73c40dd106d3d2f75628920517d77726b01400487326722d1082actrue

token获取文档

file_sizeinteger例:1024true文件总大小(字节),用于判断文件大小限制和磁盘剩余空间是否足够,不用于判断文件完整性,不得大于2GB (2147483648L)
slice_amountinteger例:1true文件总数量
indexinteger例:0true文件索引(第几个文件),从 0 开始
file_namestring例:test.txttrue文件名称(同一批文件名称需一致)
file_md5string例:2724581a42dae8d9f71544c6fdaf3216true整个文件的 md5 值
current_md5string例:c1afb715b12ac8caf3df0aead131d251true当前文件的 md5 值

  RequestBody:

key

type

value

required

description

filefile
true文件内容;文件内容超过100m需要分片上传

1.1.5. Response

  ResponseBody:

key

type

value

description

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

1.1.6. 使用 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样例

注:需引入 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

projectstring例: defaulttrue项目英文名
tokenstring
truetoken获取文档

RequestHeader:

key

value

Content-Typeapplication/json;charset=utf-8

RequestBody:

key

type

value

required

description

name
string例:user_tag_1true

标签英文名(唯一标识名)

必须以 user_tag_ 开头

cname
string例:标签1true标签中文名(显示名)
data_type
string例:STRING、BOOL、LIST、NUMBER、DATETIMEtrue标签值的数据类型
source_type
integer
true固定值:5
status
string
true固定值:RUNNING

dir_id


integer 例:1true

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

通过 下文 2.4.2 描述的接口:/api/v2/sps/user_tag_di/ 获取目录信息

upload_content
object
true 标签上传规则信息

   

upload_filenamestring例:dGVzdDEwMy50eHQCVuSFdUoQfalse

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

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

   

matched_fieldstring
false

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

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

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

   sync_profileboolean例:true/falsefalse

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

只在“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_typestring
false

 固定值:CREATE

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

   data_formatstring
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

projectstring例: defaulttrue项目英文名
tokenstring
true

token获取文档

PathVariable

key

type

value

required

description

idinteger例:1trueurl 路径变量,标签的 id

RequestHeader:

key

value

Content-Typeapplication/json;charset=utf-8

RequestBody

key

type

value

required

description

name
string
true

标签英文名(唯一标识名)

必须以 user_tag_ 开头

不能修改,传创建时的值

cname
string例:标签1true修改后的标签中文名(显示名)
data_type
string
true标签的数据类型,不能修改,传创建时的值
dir_id
string
true标签目录 ID,建议传创建标签时的值;跟创建时的值不一样时,会更新
source_type
integer
true固定值:5
upload_content
object
false重新上传文件时,必须传。

   

upload_filenamestring例:dGVzdDEwMy50eHQCVuSFdUoQfalse

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

   

matched_fieldstring
false

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

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

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

   sync_profileboolean例:true/falsefalse

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

只在“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_typestring
false

可选值:CREATE、OVERWRITE

CREATE:第一次上传

OVERWRITE:覆盖上传

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

   data_formatstring
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_timestring例:日期格式 yyyy-MM-ddfalse操作指定日期的数据

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

projectstring例: defaulttrue项目英文名
tokenstring
truetoken获取文档
parentsboolean
false

默认 false

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

RequestHeader:

key

value

Content-Typeapplication/json;charset=utf-8

RequestBody:

key

type

value

required

description

id
integer例:1false目录 ID

cname


string例:标签目录1true目录名
type
string例:DIRtrue类型,固定:DIR

parent


object
false

上级目录,创建子目录时必传;不传默认为一级目录(跟「未分类」目录同级)

   idinteger例:1false上级目录中的 ID,RequestParam中的 parents 参数为 false时,必传
   cnamestring例:上级目录1true上级目录中的目录名

   

typestring例:DIRtrue上级目录中的类型,固定值:DIR
   parentobject
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

projectstring例: defaulttrue项目英文名
tokenstring
true

token获取文档

need_user_tagboolean
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": [] } ]