消息目标(User Targets)
功能概述
消息目标(Target) 是 Agentbase 认证用户(Auth User)名下绑定的具体消息投递终端地址,涵盖 电子邮件地址(Email)、手机短信特服号/手机号(SMS) 以及 客户端设备推送令牌(Push Token,如 APNs / FCM 设备标识) 三类渠道。在企业级应用中(例如「企业智能客服与知识中台 enterprise-ai-hub-210」),同一个自然人用户(如架构师 user_zhangwei_001 张伟)往往同时拥有工作邮箱、值班手机号与移动办公 App 设备令牌。消息服务(Messaging)在进行 P1 故障告警广播、工单状态变更通知或知识库发布提醒时,并非直接向抽象的 userId 发送物理报文,而是将用户或主题(Topic)解析为其名下处于有效状态的 Target,再按 Target 的 providerType(email / sms / push)路由至对应的第三方通道提供商(Messaging Provider)完成最终投递。
通过将「用户身份(User)」与「通信终端(Target)」解耦为一对多模型,Agentbase 实现了多渠道精细化触达治理:支持创建用户时自动派生主邮箱与手机号 Target,支持通过 Server API 动态注册与轮换移动端 Push 设备令牌,支持将特定 Target 订阅到不同的消息主题(Topic Subscriber),并在用户注销或设备挂失时支持从控制台一键清理失效终端。
核心概念与架构
消息目标贯穿了 认证用户(Auth Users)、消息主题(Messaging Topics) 与 通道提供商(Messaging Providers) 三大核心子系统,其架构关系如下:
graph LR
subgraph Auth["认证与用户域 (Auth)"]
U["Auth 用户 (User)<br/>user_zhangwei_001"]
T1["Email Target<br/>zhangwei@enterprise.example.com"]
T2["SMS Target<br/>+8613800138001"]
T3["Push Target<br/>iOS / Android Device Token"]
U -->|1:N 拥有| T1
U -->|1:N 拥有| T2
U -->|1:N 拥有| T3
end
subgraph Messaging["消息与触达域 (Messaging)"]
TP["消息主题 (Topic)<br/>topic_sla_p1_alerts"]
SUB["订阅者记录 (Subscriber)<br/>绑定 Target ID"]
MSG["消息任务 (Message)<br/>Email / SMS / Push"]
P_MAIL["Email Provider<br/>SMTP / Mailgun / SendGrid"]
P_SMS["SMS Provider<br/>Twilio / Aliyun SMS"]
P_PUSH["Push Provider<br/>APNs / FCM"]
end
T1 & T2 & T3 -->|注册为| SUB
TP -->|包含| SUB
MSG -->|按 Topic 或 Target ID 寻址| SUB
T1 -->|providerType=email| P_MAIL
T2 -->|providerType=sms| P_SMS
T3 -->|providerType=push| P_PUSH核心概念与字段定义
| 核心概念 / 属性字段 | 标识符 / 类型 | 架构职责与业务语义说明 | ||
|---|---|---|---|---|
| 消息目标(Target) | $id(targetId) | 隶属于单个 userId 的通信目的地实体,全局在用户维度唯一,生命周期受所属用户控制(删除用户级联清理其全部 Target)。 | ||
**渠道类型(providerType)** | email \ | sms \ | push | 标识该目标接收消息的通信通道类别,决定了消息下发时匹配的 Provider 类型及 identifier 校验格式。 |
**终端标识符(identifier)** | string | 实际投递地址:email 渠道为标准 RFC 5322 邮箱地址;sms 渠道为带国际区号的 E.164 格式手机号(如 +8613800138001);push 渠道为客户端 SDK 获取的 FCM Registration Token 或 APNs Device Token。 | ||
**绑定提供商(providerId)** | `string \ | null` | 可选绑定的具体 Messaging Provider 实例 ID。若为空,则在发送消息时自动路由至项目内当前已启用的默认同类型 Provider。 | |
**终端名称(name)** | string(最长 128 字符) | 可读备注名称(如 张伟的 iPhone 16 Pro 值班机),主要用于 push 类型设备区分与控制台运维识别。 | ||
**会话关联(sessionId)** | `string \ | null` | 客户端通过会话注册 Push Target 时可选关联的 Session ID;当该会话登出或过期清理时,便于识别设备状态。 | |
**过期标记(expired)** | boolean | 标识该 Target 是否已被远端通道(如 APNs / FCM 反馈 Unregistered)标记为失效终端。 |
角色、入口与关联关系
适用角色与职责分工
| 角色名称 | 核心使用场景 | 所需权限范围(Role / API Scope) |
|---|---|---|
| 组织管理员 / 安全管理员 | 在控制台审计用户绑定的邮箱、手机号与推送设备,清理离职人员或挂失设备的 Target | 控制台 owner / admin / developer 角色 |
| 后端应用研发工程师 | 使用 Server SDK / REST API 为用户批量导入备用通知邮箱、值班手机号或绑定自定义 Provider | API Key 具备 users.read、targets.read、targets.write |
| 移动端 / 前端开发工程师 | 在用户登录 App 后获取系统 Push Token 并注册为当前账号的 Push Target | Client Session 认证(调用 Account Push Target 接口)或经业务后端代理注册 |
| 运维值班经理 | 将 VIP 架构师与值班工程师的 Target 加入告警主题(如 topic_sla_p1_alerts)并在消息中心核对投递回执 | 控制台访问权限 + messages.read、topics.write、subscribers.write |
控制台入口与导航路径
- 登录 Agentbase 控制台,进入目标组织(如
Agentbase 企业智能中台)下的项目 **企业智能客服与知识中台(enterprise-ai-hub-210)**。 - 在左侧主导航栏选择 **「构建」 -> 「认证」(
/auth),默认打开 「用户」(Users)** 列表页。 - 单击目标用户行(例如
user_zhangwei_001张伟),进入用户详情视图。 - 在用户详情页顶部水平页签栏中切换至 「Targets」(消息目标) 页签(路径:
/console/project-default-enterprise-ai-hub-210/auth/user-user_zhangwei_001/targets)。
上下游模块关联关系
- **上游身份源(
认证 -> 用户)**:当通过控制台或POST /v1/users创建用户且传入email或phone时,系统在数据库事务内自动派生对应的emailTarget 与smsTarget;当用户更新主邮箱或主手机号时,系统同步维护默认 Target。 - **下游订阅与群发(
消息 -> 主题 Topics)**:在Messaging -> Topics(如topic_sla_p1_alerts「P1 紧急故障 SLA 告警通道」)中添加订阅者(Subscriber)时,必须选择某个用户下的具体targetId;一条 Topic 既可包含 Email Target,也可包含 SMS 与 Push Target,从而支持全渠道告警。 - **下游单点直投(
消息 -> 消息列表 Messages)**:调用POST /v1/messaging/messages/{email|sms|push}时,可通过users[](自动展开为该用户对应渠道的所有有效 Target)或显式指定targets[](精确投递到指定设备或备用邮箱)下发消息。
功能详解与操作指南
1. 自动生成与生命周期同步机制
在 Agentbase 中,用户基础通信资料与 Target 保持自动联动,减少人工重复配置:
- 创建用户自动派生:
- 在控制台 「认证 -> 用户 -> 创建用户」 或调用
POST /v1/users时,只要填写了email(如zhangwei@enterprise.example.com),系统立即生成一条providerType = "email"的 Target。 - 若同时填写了符合 E.164 规范的
phone(如+8613800138001),系统同步生成一条providerType = "sms"的 Target。
- 在控制台 「认证 -> 用户 -> 创建用户」 或调用
- 修改用户联系方式同步:
- 当管理员在用户详情页修改用户的邮箱或手机号时,关联的自动 Target 标识符(
identifier)会随之更新。
- 当管理员在用户详情页修改用户的邮箱或手机号时,关联的自动 Target 标识符(
- 删除用户级联清理:
- 当删除某个 Auth 用户时,该用户下属的所有 Targets 以及关联的 Topic Subscribers 记录会在同一清理流程中被移除,确保不会向已注销用户继续发送任何营销或告警信息。
2. 通过 Server API / SDK 注册扩展 Target(Push 设备与备用通知渠道)
版本事实说明:当前控制台的用户详情 「Targets」 页签仅提供目标列表的查看、筛选与批量删除能力(前端代码虽保留了创建弹窗组件,但页面未暴露新建按钮)。如需为用户注册移动端 Push 设备令牌,或在同一用户下绑定多个备用通知邮箱/告警手机号,请通过 Server API 或 SDK 调用
POST /v1/users/{userId}/targets。
请求参数规范(POST /v1/users/{userId}/targets)
| 参数名 | 类型 | 必填 | 校验规则与默认值说明 |
|---|---|---|---|
userId | string | 是 | 路径参数,目标 Auth 用户的 $id(如 user_zhangwei_001)。 |
targetId | string | 否 | 自定义 Target ID(最长 36 字符,仅允许字母、数字、句点、连字符、下划线,且不得以特殊字符开头);传入 "unique()" 或缺省时由服务端自动生成唯一 ID。 |
providerType | string | 是 | 渠道枚举值,仅允许 email、sms、push 三者之一。 |
identifier | string | 是 | 投递终端地址:email 必须通过合法邮箱格式校验;sms 必须是以 + 开头且不超过 15 位数字的 E.164 手机号;push 为非空设备 Token 字符串。 |
providerId | string | 否 | 关联的 Messaging Provider ID(如指定的 APNs 或 FCM Provider ID);缺省时使用项目同类型的默认 Provider。 |
name | string | 否 | 终端显示名称(1–128 字符),建议为 push 设备填写诸如 iOS-P1-OnCall-Device 的可读名称。 |
操作步骤与可执行命令示例
以下示例演示如何使用项目 API Key(需勾选 targets.write 与 targets.read 权限域)为 VIP 架构师 user_zhangwei_001 注册一台 iOS 移动端推送设备 Target,并查询其名下全部有效 Target:
# 1. 为用户 user_zhangwei_001 创建 Push 设备 Target
curl -sS -X POST "https://appbuild.oceanbase.com/v1/users/user_zhangwei_001/targets" \
-H "Content-Type: application/json" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>" \
-d '{
"targetId": "tgt_zhangwei_ios_oncall",
"providerType": "push",
"identifier": "apns_prod_token_9f8e7d6c5b4a3210fedcba9876543210",
"name": "张伟-iPhone16Pro-值班终端"
}'
# 2. 查询用户 user_zhangwei_001 名下的全部消息目标
curl -sS -X GET "https://appbuild.oceanbase.com/v1/users/user_zhangwei_001/targets" \
-H "X-Appwrite-Project: enterprise-ai-hub-210" \
-H "X-Appwrite-Key: <APPBASE_API_KEY>"预期返回 HTTP 201 Created(创建)与 200 OK(列表查询),响应体包含自动生成的 Email/SMS Target 以及新建的 Push Target:
{
"total": 3,
"targets": [
{
"$id": "6ad9ec41001122334455",
"$createdAt": "2026-10-22T10:42:15.000+00:00",
"$updatedAt": "2026-10-22T10:42:15.000+00:00",
"name": "",
"userId": "user_zhangwei_001",
"providerId": null,
"providerType": "email",
"identifier": "zhangwei@enterprise.example.com",
"expired": false
},
{
"$id": "6ad9ec410066778899aa",
"$createdAt": "2026-10-22T10:42:15.000+00:00",
"$updatedAt": "2026-10-22T10:42:15.000+00:00",
"name": "",
"userId": "user_zhangwei_001",
"providerId": null,
"providerType": "sms",
"identifier": "+8613800138001",
"expired": false
},
{
"$id": "tgt_zhangwei_ios_oncall",
"$createdAt": "2026-10-22T11:20:00.000+00:00",
"$updatedAt": "2026-10-22T11:20:00.000+00:00",
"name": "张伟-iPhone16Pro-值班终端",
"userId": "user_zhangwei_001",
"providerId": null,
"providerType": "push",
"identifier": "apns_prod_token_9f8e7d6c5b4a3210fedcba9876543210",
"expired": false
}
]
}3. 在控制台查看、审计与批量清理消息目标
- 进入 **
认证->用户-> 单击user_zhangwei_001->Targets页签**。 - 列表表格展示以下关键运维列:
- Target ID:目标唯一标识(支持一键复制
$id,用于在 Messaging 中配置精准投递或排查订阅关系)。 - Target:对于
push类型优先展示可读name(如张伟-iPhone16Pro-值班终端),对于email与sms类型展示具体邮箱地址或手机号identifier。 - Type:显示渠道标签(
Email/SMS/Push)。 - Provider:显示显式绑定的 Messaging Provider 名称或 ID;采用项目默认通道时为空。
- Created:目标注册时间戳。
- Target ID:目标唯一标识(支持一键复制
- 批量解绑与清理失效终端:
- 当员工更换手机、卸载客户端 App 或离职交接时,勾选表格左侧对应的复选框,底部或顶部将浮现批量操作栏。
- 单击 「Delete」(删除) 并在确认弹窗中二次确认,即可立即移除所选 Target。删除后,任何发往该用户或关联 Topic 的消息均不会再向该终端投递。
常见问题与排障
问题 1:调用 POST /v1/users/{userId}/targets 返回 409 Conflict(user_target_already_exists)?
- 原因分析:同一用户(
userId)名下已经存在相同providerType与相同identifier的 Target(例如创建用户时系统已自动生成了主邮箱或主手机号 Target,业务代码又重复调用创建接口写入同一邮箱/手机号),或传入的自定义targetId已存在。 - 解决措施:先调用
GET /v1/users/{userId}/targets检查该用户现有的目标列表;若相同identifier已存在,直接复用返回的$id即可;若是移动端设备 Token 刷新,请调用PATCH /v1/users/{userId}/targets/{targetId}更新identifier字段,而非重复新建。
问题 2:在「消息(Messaging)」模块向某用户或主题发送消息时,状态显示失败或提示未找到可用接收目标?
- 原因分析:消息任务的类型(如发送 SMS 短信或 Push 推送)与目标用户名下已有的 Target 类型不匹配(例如用户仅填写了邮箱,名下只有
emailTarget,未绑定sms或pushTarget),或者原有的 Push Target 因客户端卸载已被标记为expired: true。 - 解决措施:进入 「认证 -> 用户 -> 目标用户 -> Targets」 页签,确认是否存在对应
Type(Email/SMS/Push)的有效记录;若缺失,补充用户的手机号或通过 Server API 为其注册对应渠道的 Target。
问题 3:使用 API Key 管理用户 Target 时返回 401 Unauthorized(missing scopes (["targets.write"]))?
- 原因分析:自细粒度权限拆分后,用户消息目标的读写权限由独立的
targets.read与targets.write控制,仅勾选users.write不包含targets.write。 - 解决措施:前往 「概览 -> API Keys」,编辑当前后端使用的 API Key,在权限勾选面板的 Messaging / Users 分类下勾选
targets.read与targets.write并保存。