設置渠道關聯標識
渠道關聯標識是觸達通道上的標識值，可作為該通道的觸達對象。設置和解綁均基於 EUID 與通道 ID 執行。
完整調用地址由資料中心的 Base URL 與下方介面路徑組成。Base URL、API Key 與 API Secret 的獲取方式請參見 REST API 概述。
調用驗證
EngageLab REST API 採用 HTTP 基本認證 的驗證方式：HTTP Header（頭）里加 Authorization：
Authorization: Basic ${base64_auth_string}
上述 base64_auth_string 的生成算法為：base64(api_key:api_secret)
- Header 名稱是 "Authorization"，值是 base64 轉換過的 "username:password" 對（中間有個冒號）。
- 在 MA API 的場景里，username 是 APIKey，password 是 APISecret。請在數據來源中添加 API 類型的數據源獲得 APIKey 與 API Secret。
設置渠道關聯標識
調用地址
POST /v1/user/channel
請求示例
請求頭
> POST /v1/user/channel
> Content-Type: application/json
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
請求體
{
"euid": 10362473,
"channel_id": 8801,
"ma_rid": "1a0018970d1c9f8f8e2",
"value": [
"channel_identifier_1",
"channel_identifier_2"
]
}
請求參數
| 字段 | 類型 | 必填 | 描述 |
|---|---|---|---|
euid |
Long | 是 | 用戶唯一 ID。必須是目前專案中已存在的用戶。 |
channel_id |
Long | 是 | 觸達通道 ID。必須是目前專案中已存在的通道。 |
ma_rid |
String | 否 | MA Registration ID。傳入後，本次寫入的渠道標識綁定該 MA RID，並記錄其平台；該 MA RID 轉移到其他 EUID 時，綁定了它的渠道標識會隨之轉移。不傳、空字串或只含空白時，本次寫入不建立綁定；若本次寫入的標識值此前已有綁定，原綁定會被清除。無法從該值解析出平台時，設置失敗。 |
value |
Array<String> | 是 | 待設置的渠道關聯標識值列表。列表不能為空，每項不能為空白。值按原文保存，區分大小寫，不會去掉首尾空白。同一次請求中的重複值會去重。 |
同一 euid + channel_id 下，相同的標識值按本次請求重寫：原記錄刪除後寫入新記錄，更新時間變為目前時間。本次列表之外的已有標識值保持不變，新值追加保存。
對於 AppPush/WebPush 通道，同一 channel_id 下的同一個渠道標識只允許歸屬一個 EUID。寫入新的 EUID 成功後，系統再從其他仍持有該值的 EUID 移除它。其他通道類型不做這個唯一性換綁。
返回參數
| 字段 | 類型 | 必填 | 描述 |
|---|---|---|---|
code |
Int | 是 | 接口調用是否成功，0 表示成功。 |
message |
String | 是 | 接口調用結果描述。 |
成功示例
{
"code": 0,
"message": "success"
}
解綁渠道關聯標識
調用地址
POST /v1/user/channel/unbind
請求示例
請求頭
> POST /v1/user/channel/unbind
> Content-Type: application/json
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
請求體
{
"euid": 10362473,
"channel_id": 8801,
"value": [
"channel_identifier_1",
"channel_identifier_2"
]
}
請求參數
| 字段 | 類型 | 必填 | 描述 |
|---|---|---|---|
euid |
Long | 是 | 用戶唯一 ID。 |
channel_id |
Long | 是 | 觸達通道 ID。 |
value |
Array<String> | 是 | 要解綁的渠道關聯標識值列表。每一項必須與已設置的標識值完全一致，區分大小寫，不會去掉首尾空白。 |
解綁按渠道標識值匹配，不按 ma_rid 匹配。解綁請求沒有 ma_rid 字段。按 euid + channel_id + value 精確匹配並移除。用戶不存在，或該用戶下沒有完全一致的標識值時，不修改資料，仍返回成功。解綁不校驗 channel_id 是否屬於目前專案。
返回參數
| 字段 | 類型 | 必填 | 描述 |
|---|---|---|---|
code |
Int | 是 | 接口調用是否成功，0 表示成功。 |
message |
String | 是 | 接口調用結果描述。 |
成功示例
{
"code": 0,
"message": "success"
}
錯誤碼
設置接口在業務校驗失敗時返回下列錯誤碼，HTTP 狀態碼為 400。響應體裡的 message 是英文說明，不是下表中的中文描述。解綁接口只在必填參數不合法或請求體無法解析時返回 55004；用戶不存在或標識值不存在時仍返回成功。
| 錯誤碼 | 描述 | 詳細說明 |
|---|---|---|
| 55004 | 業務參數不合法 | 設置時，channel_id 在目前專案中不存在，響應 message 為 channel_id does not exist in current project: {channel_id}。設置時，ma_rid 無法解析出平台，響應 message 為 ma_rid is invalid。設置和解綁時，必填字段缺失、value 為空或含空白項，以及請求體無法解析（此時 message 為 Invalid request payload format），也返回該錯誤碼。 |
| 55108 | 無效的 EUID | 僅設置接口返回。目前專案中不存在該 EUID，響應 message 為 EUID does not exist: {euid}。 |
失敗示例
channel_id 不存在：
{
"code": 55004,
"message": "channel_id does not exist in current project: 8801"
}
ma_rid 無法解析：
{
"code": 55004,
"message": "ma_rid is invalid"
}
EUID 不存在：
{
"code": 55108,
"message": "EUID does not exist: 10362473"
}
