Logo Site EngageLab Mark Colored Transparent文档
MA
文档首页
产品概述控制台指南REST API客戶端 SDK数据安全更新日志
搜索
登录
REST API/设置用户属性
REST API设置用户属性...

设置用户属性

最新更新：大约 2 个月前

调用地址

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 是 对属性进行更新的操作类型，支持 set、increase、add、remove、delete 5 种类型。
properties JSON 是 用户属性列表，key 是属性名，value 是属性值

操作类型说明

一次请求中的所有属性使用同一个 type。支持 set、increase、add、remove、delete、update：

操作 适用属性类型 说明
set 所有类型 更新属性值；object_array 类型必须传完整的对象数组并覆盖原数组。
increase 数字 将传入数值累加到现有值；属性不存在时以 0 为初始值。
add 列表、对象数组 列表追加并去重；对象数组追加一个对象。
remove 列表、对象数组 列表移除传入元素；对象数组按标识字段移除一个对象。
delete 所有类型 删除该属性的全部值。
update 对象数组 按标识字段局部更新一个对象数组中的某一个对象。

对象数组操作说明

对于 object_array 属性的操作说明如下，假设 devices 是一个对象数组类型的属性

set ：属性值需要设置为整个对象数组，对整体做覆盖更新

{ "euid": 10362473, "type": "set", "properties": { "devices": [ {"device_id":123,"model_id": "F20C_RK","create_time": "2026-05-23T01:39:40Z","scene":"outdoor"}, {"device_id":124,"model_id": "F20C_RK_C","create_time": "2026-06-23T01:39:40Z","scene":"outdoor"} ] } }
              
              {
  "euid": 10362473,
  "type": "set",
  "properties": {
    "devices": [ 
      {"device_id":123,"model_id": "F20C_RK","create_time": "2026-05-23T01:39:40Z","scene":"outdoor"},
      {"device_id":124,"model_id": "F20C_RK_C","create_time": "2026-06-23T01:39:40Z","scene":"outdoor"}
    ]
    }
}
此代码块在浮窗中显示

add :属性值为单个或者多个 JSON 对象，将在这个对象数组中新增该对象，并支持在每一个对象中使用$identifier_key来去重

  • 若不传递$identifier_key，则直接添加该对象
  • 若传递了$identifier_key，则在已有属性值中查询，$identifier_key已存在时将不会添加该对象，$identifier_key不存在时才会添加该对象
  • 传递的$identifier_key必须在该对象中存在，将使用该 Key 与 值进行去重判断
{ "euid": 10362473, "type": "add", "properties": { "devices": {"device_id":125,"model_id": "F20C_RK","create_time": "2026-05-23T01:39:40Z","scene":"outdoor"} } }
              
              {
  "euid": 10362473,
  "type": "add",
  "properties": {
    "devices": {"device_id":125,"model_id": "F20C_RK","create_time": "2026-05-23T01:39:40Z","scene":"outdoor"}
    }
}
此代码块在浮窗中显示
{ "euid": 10362473, "type": "add", "properties": { "devices": [ {"$identifier_key": "device_id","device_id":125,"model_id": "F20C_RK","create_time": "2026-05-23T01:39:40Z","scene":"outdoor"}, {"device_id":124,"model_id": "F20C_RK_C","create_time": "2026-06-23T01:39:40Z","scene":"outdoor"} ] } }
              
              {
  "euid": 10362473,
  "type": "add",
  "properties": {
    "devices": [
      {"$identifier_key": "device_id","device_id":125,"model_id": "F20C_RK","create_time": "2026-05-23T01:39:40Z","scene":"outdoor"},
      {"device_id":124,"model_id": "F20C_RK_C","create_time": "2026-06-23T01:39:40Z","scene":"outdoor"}
    ]
    }
}
此代码块在浮窗中显示

remove ：通过 $identifier_key 与 $identifier_value 来查询到符合条件的对象（可能为多个），将从属性值中移除这些对象

  • 传递的属性值只需要包含这两个标识字段
  • $identifier_key 必须是该对象数组属性下，已经定义好的一个 string 或 number 类型的子字段。
{ "euid": 10362473, "type": "remove", "properties": { "devices": { "$identifier_key": "device_id", "$identifier_value": "123" } } }
              
              {
  "euid": 10362473,
  "type": "remove",
  "properties": {
    "devices": {
      "$identifier_key": "device_id",
      "$identifier_value": "123"
    }
  }
}
此代码块在浮窗中显示

update ：通过 $identifier_key 与 $identifier_value 来查询到符合条件的对象（可能为多个），对这些对象进行某些子字段的更新，需要提供非空的 $new_object。

  • $identifier_key 必须是该对象数组属性下，已经定义好的一个 string 或 number 类型的子字段。
  • $new_object 中的子字段，如果在查找到的对象中已存在则覆盖更新，不存在则添加，如果子字段的值为 null 则该字段会从对象中移除。
  • $new_object 中不允许包含$identifier_key
{ "euid": 10362473, "type": "update", "properties": { "devices": { "$identifier_key": "device_id", "$identifier_value": "123", "$new_object": { "model_id": "F20C_RK", "update_time": "2026-07-23T01:39:40Z", "legacy_field": null } } } }
              
              {
  "euid": 10362473,
  "type": "update",
  "properties": {
    "devices": {
      "$identifier_key": "device_id",
      "$identifier_value": "123",
      "$new_object": {
        "model_id": "F20C_RK",
        "update_time": "2026-07-23T01:39:40Z",
        "legacy_field": null
      }
    }
  }
}
此代码块在浮窗中显示

delete ：删除整个属性

{ "euid": 10362473, "type": "delete", "properties": { "devices": null, } }
              
              {
  "euid": 10362473,
  "type": "delete",
  "properties": {
    "devices": null,
    }
}
此代码块在浮窗中显示

object 的操作说明

set ：需要是 JSON 格式，传递的子字段如果存在则覆盖，不存在则添加，如果子字段的值为 null 则该字段会从对象中移除。

  • 已存在但本次未传递的字段不会被改变，如需更新整个属性请传递所有字段
{ "euid": "user_123", "type": "set", "properties": { "home_address": {"city": "上海", "district": "浦东"} } }
              
              {
  "euid": "user_123",
  "type": "set",
  "properties": {
    "home_address": {"city": "上海", "district": "浦东"}
  }
}
此代码块在浮窗中显示

delete ：删除整个属性

{ "euid": 10362473, "type": "delete", "properties": { "home_address": null, } }
              
              {
  "euid": 10362473,
  "type": "delete",
  "properties": {
    "home_address": 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 接口鉴权失败 确认项目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 技术支持
Icon Solid Transparent White Qiyu
联系销售