設置用戶屬性 | Marketing Automation REST API 繁體中文

調用地址

POST /v1/user/property

調用驗證

EngageLab REST API 採用 HTTP 基本認證的驗證方式：HTTP Header（頭）里加 Authorization：

Authorization: Basic ${base64_auth_string}

              
              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/property > Content-Type: application/json > Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

              
              > POST /v1/user/property
> Content-Type: application/json
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==

此代碼塊在浮窗中顯示

請求體

{ "euid":10362473, "type": "set", "properties":{ "user_number_once":46.2, //用戶屬性名稱和屬性值 "user_string_once":"refef", "user_datetime_once": "2023-12-12 00:56:23" } }

              
              {
    "euid":10362473,
    "type": "set",
    "properties":{
        "user_number_once":46.2, //用戶屬性名稱和屬性值
        "user_string_once":"refef",
        "user_datetime_once": "2023-12-12 00:56:23"
    }
}

此代碼塊在浮窗中顯示

請求參數

字段	類型	必填	描述
euid	Long	是	EngageLab MA 用戶唯一ID
type	String	是	對屬性進行更新的操作類型
properties	JSON	是	用戶屬性列表，key 是屬性名，value 是屬性值

操作類型說明

同一請求中的所有屬性使用相同的 type。支援 set、increase、add、remove、delete、setOnce、update：

操作	適用屬性類型	說明
`set`	所有類型	更新屬性值；`object_array` 必須傳物件陣列並覆蓋原陣列。
`increase`	數字	將傳入數值累加至現有值；屬性不存在時以 `0` 為初始值。
`add`	清單、物件陣列	清單追加並去重；物件陣列追加一個物件。
`remove`	清單、物件陣列	清單移除傳入元素；物件陣列依標識欄位移除一個物件。
`delete`	所有類型	刪除該屬性的全部值。
`setOnce`	所有類型	僅在屬性尚未設定時寫入。
`update`	物件陣列	依標識欄位局部更新一個物件陣列元素。

物件陣列操作

對於 object_array 屬性，add 的屬性值為單一 JSON 物件；set 的屬性值為 JSON 物件陣列。remove 與 update 透過 $identifier_key 及 $identifier_value 定位元素；標識欄位必須是該屬性已定義的 string 或 number 子欄位。

remove 的屬性值只能包含這兩個標識欄位：

{ "euid": 10362473, "type": "remove", "properties": { "devices": { "$identifier_key": "device_id", "$identifier_value": "ios-001" } } }

              
              {
  "euid": 10362473,
  "type": "remove",
  "properties": {
    "devices": {
      "$identifier_key": "device_id",
      "$identifier_value": "ios-001"
    }
  }
}

此代碼塊在浮窗中顯示

update 還必須提供非空的 $new_object。$new_object 不得包含標識欄位；值為 null 的欄位會從匹配元素中移除。標識條件必須恰好匹配一個陣列元素。

{ "euid": 10362473, "type": "update", "properties": { "devices": { "$identifier_key": "device_id", "$identifier_value": "ios-001", "$new_object": { "model": "iPhone 16", "legacy_field": null } } } }

              
              {
  "euid": 10362473,
  "type": "update",
  "properties": {
    "devices": {
      "$identifier_key": "device_id",
      "$identifier_value": "ios-001",
      "$new_object": {
        "model": "iPhone 16",
        "legacy_field": null
      }
    }
  }
}

此代碼塊在浮窗中顯示

返回參數

字段	類型	必填	描述
code	Int	是	接口調用是否成功，0 表示成功或者部分成功，其他值代表失敗
message	String	是	接口調用結果描述，對返回碼的說明

全部成功

{ "code": 0, "message": "success" }

              
              {
    "code": 0,
    "message": "success"
}

此代碼塊在浮窗中顯示

全部失敗

{ "code": 55102, "message": "Invalid user attributes exist" }

              
              {
    "code": 55102,
    "message": "Invalid user attributes exist"
}

此代碼塊在浮窗中顯示

錯誤碼

錯誤碼	描述	詳細說明
40050	I接口鑒權失敗	確認項目ID和項目密鑰是否正確
40007	EUID為空	請檢查 EUID 的值
50031	項目 ID 非法	請檢查 APIKey 和 APISecret 是否正確
50034	項目 ID 不存在	請檢查 APIKey 和 APISecret 是否正確，檢查項目是否已被刪除
50074	API 數據源不存在	請檢查 APIKey 和 APISecret 是否正確，請檢查 API 數據源是否已被刪除
55004	業務參數不合法	請檢查請求參數字段是否正確
55101	用戶標識個數超限	確認用戶標識的值的數量是否超過 100 個
55102	存在無效的用戶屬性名稱	確認屬性名稱是否符合命名要求，是否為空/用到了保留字符/超過長度限制
55103	用戶屬性值不能為空	確認請求體中用戶屬性的值是否為空
55105	用戶標識的 value 值不能超過 256 個字符	確認用戶標識的值是否超過256個字符
55106	用戶標識的名稱不在支持範圍內	確認用戶標識的名稱是否是 user_id、 anonymous_id、registration_id
55107	用戶標識的 value 值為空	確認請求體中用戶標識的值是否為空
55108	無效的 EUID	請檢查 EUID 的值
-1	服務器內部錯誤	請聯繫 EngageLab 技術支持