菜单

属性标签订阅服务接入

接口文档列表

属性-元数据

属性-在线接口列表

名词解释

名词
释义
属性

用户表的属性，如性别， 年龄等，在神策分析前端页面的『元数据管理』模块可以检索用户属性。属性订阅和属性在线查询，需要使用属性名（不是属性显示名）。
标签

神策系统中建立的标签，可以通过类似属性的方式被订阅和在线查询，具体概念解释参考官网文档：https://manual.sensorsdata.cn/sa/latest/zh_cn/Tag_Management-143163512.html

标签订阅和标签在线查询，需要使用标签名称（不是标签显示名）。

使用流程

属性相关接口的使用过程比较简单，主要包括以下阶段：

  1. 订阅属性： 接口调用成功之后，底层数据流会开始从 sa 侧同步属性，保存到 sfn 侧的 skv 中，提供高性能在线查询。属性同步完成会发出 ATTRIBUTE_QUERY_READY 通知
  2. 接收数据就绪通知：收到 ATTRIBUTE_QUERY_READY 之后，可以进行在线查询；
  3. 用户属性或标签在线查询，包括单个用户和批量用户在线查询；
  4. 不再需要查询属性之后， 需要调用取消订阅接口，回收存储和计算资源；
 

属性订阅

属性订阅以 HTTP API 形式接入，通过 HTTP API 方式订阅属性。

接口类型

method

Path
离线 /offline POST

/api/v3/focus/v1/express-attribute/subscribe

请求示例

curl -X 'POST' \
  'http://{offline-domain}/api/v3/focus/v1/express-attribute/subscribe' \
  -H 'Content-Type: application/json' \
  -H 'api-key: #K-7IGwJpE2M9CpID4101qj2hWg9t59hoF3' \
  -H 'X-Organization-Id: org-sep-3164dp4' \
  -H 'sensorsdata-project: default' \
  -d '{
      "entity_name": "user",
      "attribute_name": "phone_number_new",
      "subscriber": "test"
  }'

参数说明

参数位置

参数

是否必传

参数说明
body entity_name 非必传 实体名称，不传默认为用户实体，即 user
attribute_name 必传 订阅的属性名称，可以为用户属性、标签等名称
subscriber 必传 客户自定义填充，订阅方标识，同一个订阅方不能重复订阅同一个实体属性

返回结果示例

{
    "code": "SUCCESS",
    "message": null,
    "request_id": "94076ab01ef942448c702c9335f3d4a2",
    "data": {},
    "error_info": null
}

返回结果说明

参数

是否必返

参数说明
data 必返 调用成功后，暂不返回订阅的其他额外信息

 

通知内容解析

注册通知接口以后，已订阅的属性状态会及时通过通知的形式发送到业务系统。

协议：HTTP

请求方式：POST

Content-Type: application/json

请求示例

curl -X 'POST' \
  'http://{offline-domain}/{path} \
  -H 'Content-Type: application/json' \
  -H '{key1}: {value1}' \
  -H '{key2}: {value2}' \
  -d '{
     ...// 通知内容
  }'

通知内容

通知状态（type_code）
状态含义
通知示例
参数解释
ATTRIBUTE_QUERY_READY 属性可被在线查询，此时业务系统可以通过属性在线查询接口进行属性查询 
{
    "type": 1003,
    "type_code": "ATTRIBUTE_QUERY_READY",
    "notify_time": "1687937204745",
    "context_id":"context_test_session_xxxxxxx01",
    "attribute_notify_content":{
        "attributes":{
            "entity_name": "user",
            "attribute_names": ["phone_number_new"]
        }
    }
}

type /type_code/notify_time /context_id 等请参考下方「通知能力接入」部分。

  • entity_name：订阅的实体名称，如用户实体这里就是 user；
  • attribute_names：订阅的实体属性列表。
ATTRIBUTE_QUERY_NOT_READY 属性订阅中间过程处理失败，此时不可用于在线属性查询。 
{
    "type": 1004,
    "type_code": "ATTRIBUTE_QUERY_NOT_READY",
    "notify_time": "1687937204745",
    "context_id":"context_test_session_xxxxxxx01",
    "attribute_notify_content":{
        "attributes":{
            "entity_name": "user",
            "attribute_names": ["phone_number_new"]
        }
    }'
    "error_notify_content": {
        "error_msg": "xx原因导致失败"
    }
}
 部分字段同上，error_notify_content 表示错误原因等信息。

 

属性订阅状态查询

属性订阅状态查询以 HTTP API 形式接入，通过 HTTP API 方式订阅属性的订阅状态。

接口类型

method

Path
离线 /offline POST /api/v3/focus/v1/express-attribute/status/query

请求示例

curl -X 'POST' \
  'http://{offline-domain}/api/v3/focus/v1/express-attribute/status/query \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \    
  -H 'api-key: #K-7IGwJpE2M9CpID4101qj2hWg9t59hoF3' \     
  -H 'X-Organization-Id: org-sep-3164dp4' \
  -H 'sensorsdata-project: default' \
  -d '{
  "entity_name": "user",
  "attribute_names": ["first_id", "second_id", "$identity_mobile"]
}'

参数说明

参数位置

参数

是否必传

参数说明
body entity_name 非必传 实体名称，不传默认为用户实体，即 user
attribute_names 必传 订阅的属性名称列表，可以为用户属性、标签等名称，注意：不要传没有订阅的用户属性名称、标签名称

返回结果示例

{
    "code": "SUCCESS",
    "message": null,
    "request_id": "6e049dcdcad547d488d8da44a50c5056",
    "data": {
        "attribute_subscribe_statuses": [
            "ATTRIBUTE_SUBSCRIBE_PREPARING",
            "ATTRIBUTE_SUBSCRIBE_PREPARING",
            "ATTRIBUTE_SUBSCRIBE_READY"
        ]
    },
    "error_info": null
}

返回结果说明

参数

是否必返

参数说明
data 必返

调用成功后，针对 attribute_names 参数，对应分别返回对应的订阅状态：

  • ATTRIBUTE_SUBSCRIBE_PREPARING - 属性未订阅或同步中
  • ATTRIBUTE_SUBSCRIBE_READY         - 同步完成，可以查询

 

属性取消订阅

属性取消订阅以 HTTP API 形式接入，通过 HTTP API 方式取消订阅属性。

接口类型

method

Path
离线 /offline POST /api/v3/focus/v1/express-attribute/unsubscribe

请求示例

curl -X 'POST' \
  'http://{offline-domain}/api/v3/focus/v1/express-attribute/unsubscribe \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \       
  -H 'api-key: #K-7IGwJpE2M9CpID4101qj2hWg9t59hoF3' \     
  -H 'X-Organization-Id: org-sep-3164dp4' \
  -H 'sensorsdata-project: default' \
  -d '{
  "entity_name": "user",
  "attribute_name": "phone_number_new",
  "subscriber": "sfn"
}'

参数说明

参数位置

参数

是否必传

参数说明
body entity_name 非必传 实体名称，不传默认为用户实体，即 user
attribute_name 必传 订阅的属性名称，可以为用户属性、标签等名称
subscriber 必传 订阅方标识，同一个订阅方不能重复订阅同一个实体属性，注意：同一个属性、标签，取消订阅时，订阅方标识需要和订阅接口传的标识保持一致。

返回结果示例

{
    "code": "SUCCESS",
    "message": null,
    "request_id": "386bbd7510fb488594938ae0730c562b",
    "data": { },
    "error_info": null
}

返回结果说明

参数

是否必返

参数说明
data 必返 code 为 SUCCESS 即表示调用成功。

 

获取已订阅的属性标签列表

通过过滤条件获取属性标签列表

接口类型

method

Path
离线 /offline POST /api/v3/focus/v1/express-attribute/list

请求示例

curl -X 'POST' \
  'https://${sensors_data_url}/api/v3/focus/v1/express-attribute/list' \
  -H 'accept: application/json' \
  -H 'api-key: api-key' \
  -H 'sensorsdata-project: project-name' \
  -H 'Content-Type: application/json' \
  -H 'X-Organization-Id: ${X-Organization-Id}' \
  -d '{
  "project_id": 1,
  "keyword": "2",
  "status": "ACTIVE",
  "subscribe_start_date": "2020-01-01",
  "subscribe_end_date": "2032-01-01",
  "page_filter": {
    "limit": 50, // 分页数量，例如 50/页，表示每个页面展示 50 条记录
    "offset": 0 // 当前分页的起始值，例如 limit 为 50，则第二页的起始值为 50，第三页的起始值为 100
  }
}'

请求参数说明

参数

是否必传

参数说明
project_id 非必传 
非必传项目ID
 
keyword
 非必传 
搜索的关键字(订阅ID、属性名、标签名称)
 
status
 非必传 
订阅状态，取值范围：
PREPARING,  // 订阅成功且数据准备中，不可在线实时查询实体属性值
ACTIVE,     // 订阅成功且数据同步完成，可在线实时查询实体属性值
STOPPING,   // 延迟取消订阅，不可在线实时查询实体属性值
STOPPED     // 实际取消订阅，不可在线实时查询实体属性值
 
subscribe_start_date
 非必传 
订阅开始时间
 
subscribe_end_date
 非必传 
订阅结束时间
 
page_filter
 必传 
分页参数

返回示例

{
    "code": "SUCCESS",
    "message": null,
    "request_id": "131623053b2f851004d05236bf61325c",
    "data": {
        "page_filter": {
            "limit": 0,
            "offset": 0,
            "total": 4
        },
        "attribute_records": [
            {
                "id": 6,
                "project_id": 2,
                "name_cn": "test_tag",
                "name": "user_tag_ybq",
                "status": "ACTIVE",
                "type": "tag",
                "hubble_sub_id": 747,
                "create_time": 1734012041784,
                "sync_done_time": 1734012048000
            },
            {
                "id": 3,
                "project_id": 2,
                "name_cn": "oppo_id",
                "name": "oppo_id",
                "status": "ACTIVE",
                "type": "user_property",
                "hubble_sub_id": 744,
                "create_time": 1734001865378,
                "sync_done_time": 1734001866000
            },
            {
                "id": 2,
                "project_id": 2,
                "name_cn": "小程序标签1",
                "name": "user_tag_xcxbq1",
                "status": "ACTIVE",
                "type": "tag",
                "hubble_sub_id": 743,
                "create_time": 1734001605376,
                "sync_done_time": 1734001616000
            },
            {
                "id": 1,
                "project_id": 2,
                "name_cn": "test_flag",
                "name": "test_flag",
                "status": "ACTIVE",
                "type": "user_property",
                "hubble_sub_id": 578,
                "create_time": 1732089656068,
                "sync_done_time": 1732089661000
            }
        ]
    },
    "error_info": null
}

返回结果说明

参数

是否必返

参数说明

 
page_filter
 必返

查询的用户实体列表，其中 entity_id 代表用户标识

 
attribute_records

必返

 

 
属性订阅详情
  1. id: 属性订阅 ID
  2. project_id：项目 ID
  3. name_cn：中文名称
  4. name：英文名称
  5. status：订阅状态，PREPARING,ACTIVE,STOPPING,STOPPED   
  6. type：类型，如 tag/user_property
  7. hubble_sub_id：hubble 订阅 ID
  8. create_time： 创建时间
  9. sync_done_time：步完成时间

 

单用户的属性在线查询

在线查询单用户的已订阅的属性集，以 HTTP API 形式接入，通过 HTTP API 方式查询单用户的已订阅属性集。

接口类型

method

Path
在线 /online POST /api/v3/focus/v1/express-attribute-online/get

请求示例

curl -X 'POST' \
  'http://{online-domain}/api/v3/focus/v1/express-attribute-online/get' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'api-key: #K-7IGwJpE2M9CpID4101qj2hWg9t59hoF3' \
  -H 'X-Organization-Id: org-sep-3164dp4' \
  -H 'sensorsdata-project: default' \
  -d '{
  "entity_name": "user",
  "audience_entity_id": {
    "identity_id_map": {
      "distinct_id": "sddd"
    }
  },
  "attribute_names": ["phone_number_new", "user_tag_wxccc"]
}'

参数说明

参数位置

参数

是否必传

参数说明
body entity_name 非必传 实体名称，不传默认为用户实体，即 user
audience_entity_id 必传

查询的用户标识符，其中「用户标识」的字段含义如下：

  • entity_name 表示实体名称，不传表示 user
  • identity_id_map 为业务主键 map，key: id_name（业务 id 字段名）, value: id_value（具体的 id 值）; id_name，如 distinct_id（传用户唯一标识，可支持 IDMapping 2.0 和 IDMapping 3.0 环境）, first_id, second_id, $identity_mobile 等；identity_id_map 与 entity_id 只需设置其中一个，如果同时设置则以 entity_id 为准；identity_id_map 中本期只支持 distinct_id
  • entity_id 表示实体 id：
    • 实体 ID 目前只支持 user_id，为 int 类型，则值可表示为（具体值替换为具体的实体 id）："int_value": 123
attribute_names 必传 已订阅的属性名称列表，可以为用户属性、标签等名称

返回结果示例

{
    "code": "SUCCESS",
    "message": null,
    "request_id": "87c8382ffeed403b9c840dc448395cd3",
    "data": {
        "audience_entity": {
            "entity_id": {
                "data_type": "INT",
                "int_value": "-2443016794336717482"
            },
            "entity_name": "user",
            "audience_entity_attributes": [
                {
                    "name": "phone_number_new"
                },
                {
                    "name": "user_tag_wxccc",
                    "value": {
                        "data_type": "STRING",
                        "string_value": "分层1",
                        "list_value": []
                    }
                }
            ]
        }
    },
    "error_info": null
}

返回结果说明

参数

是否必返

参数说明
audience_entity 必返

查询的用户实体，其中 entity_id 代表用户标识
entity_name   实体名称
audience_entity_attributes  

实体属性 / 标签列表，列表项字段说明：

  • name：实体属性 / 标签名称
  • value：实体属性 / 标签值

 

批量用户的属性在线查询

在线查询一批用户的已订阅的属性集，以 HTTP API 形式接入，通过 HTTP API 方式查询一批用户的已订阅属性集。

接口类型

method

Path
在线 /online POST /api/v3/focus/v1/express-attribute-online/batch-get

请求示例

curl -X 'POST' \
  'http://{online-domain}/api/v3/focus/v1/express-attribute-online/batch-get' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'api-key: #K-7IGwJpE2M9CpID4101qj2hWg9t59hoF3' \
  -H 'X-Organization-Id: org-sep-3164dp4' \
  -H 'sensorsdata-project: default' \ 
  -d '{
  "entity_name": "user",
  "audience_entity_ids": [
    {
      "identity_id_map": {
        "distinct_id": "sddd"
      }
    }
  ],
  "attribute_names": ["first_id"]
}'

参数说明

参数位置

参数

是否必传

参数说明
body entity_name 非必传 实体名称，不传默认为用户实体，即 user
audience_entity_ids 必传

查询的用户标识符列表，其中单个「用户标识」的字段含义如下：

  • entity_name 表示实体名称，不传表示 user
  • identity_id_map 为业务主键 map，key: id_name（业务 id 字段名）, value: id_value（具体的 id 值）; id_name，如 distinct_id（传用户唯一标识，可支持 IDMapping 2.0 和 IDMapping 3.0 环境）, first_id, second_id 默认支持，如果是 IDMapping 3.0 的其它用户关联标识，如  $identity_mobile 等，需要调属性订阅接口订阅后才能识别用户；identity_id_map 与 entity_id 只需设置其中一个，如果同时设置则以 entity_id 为准；identity_id_map 中本期只支持 distinct_id
  • entity_id 表示实体 id：
    • 实体 ID 目前只支持 user_id，为 int 类型，则值可表示为（具体值替换为具体的实体 id）："int_value": 123
attribute_names 必传 已订阅的属性名称列表，可以为用户属性、标签等名称

返回结果示例

{
    "code": "SUCCESS",
    "message": null,
    "request_id": "0c7b4c998b7a4209b12ed8cc18a31ae1",
    "data": {
        "audience_entities": [
            {
                "entity_id": {
                    "data_type": "INT",
                    "int_value": "224266287"
                },
                "entity_name": "user",
                "audience_entity_attributes": [
                    {
                        "name": "first_id",
                        "value": {
                            "data_type": "STRING",
                            "string_value": "cc03",
                            "list_value": []
                        }
                    }
                ]
            },
            {
                "entity_id": {
                    "data_type": "INT",
                    "int_value": "-2443016794336717482"
                },
                "entity_name": "user",
                "audience_entity_attributes": [
                    {
                        "name": "first_id",
                        "value": {
                            "data_type": "DATA_TYPE_UNSPECIFIED",
                            "list_value": []
                        }
                    }
                ]
            }
        ]
    },
    "error_info": null
}

返回结果说明

参数

是否必返

参数说明
audience_entities 必返

查询的用户实体列表，其中 entity_id 代表用户标识
entity_id 必返
  • entity_id 表示实体 id：
    • 如果实体 ID 为 int 类型，则值可表示为（具体值替换为具体的实体 id）："int_value": 123
    • 如果实体 ID 为 String 类型，则值可表示为（具体值替换为具体的实体 id）："string_value": "xxxxx"
entity_name 必返 实体名称
audience_entity_attributes 必返

实体属性 / 标签列表，列表项字段说明：

  • name：实体属性 / 标签名称
  • value：实体属性 / 标签值，如果值不存在，则只返回 name


以上仅列举重要的接口，剩余接口请参考接口手册。

上一个
受众服务接入
下一个
实时标签服务接入
最近修改: 2025-09-05