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 的值是一樣的

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' \
  -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\n111\n222\n333\n444\n\r\n------WebKitFormBoundaryYuxPY2tAQZiUcDIR--\r\n' \
  -H 'Cookie: api_server_id=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: api_server_id=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	標籤英文名（唯一標識名）
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	false	標籤目錄ID，預設放置於未分類目錄
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"時生效，選擇其他屬性不支援將屬性同步到全量用戶清單 true：保留上傳檔中不在全量表中的使用者，會將這部分使用者同步到全量表 user.$first_id按照「設備 ID」同步使用者 user.$second_id按照「登錄 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/id?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
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"時生效，選擇其他屬性不支援將屬性同步到全量用戶清單 true：保留上傳檔中不在全量表中的使用者，會將這部分使用者同步到全量表 user.$first_id按照「設備 ID」同步使用者 user.$second_id按照「登錄 ID」同步使用者 id 指的是使用者標識，詳見：識別使用者 false：僅保留上傳檔中存在於全量表中的使用者可以為空，upload_filename有值時必須傳
	upload_type	string		false	可選值：CREATE、OVERWRITE、INCREMENT CREATE：第一次上傳 OVERWRITE：覆蓋上傳 INCREMENT：追加導入可以為空，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	操作指定日期的數據
	update_value	boolean		false	預設 false，僅針對追加模式有效 false：僅追加不存在的使用者 true：追加不存在的使用者，並更新已存在使用者的標籤值

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