消息目标(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) 三大核心子系统,其架构关系如下:
流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。
核心概念与字段定义
| 核心概念 / 属性字段 | 标识符 / 类型 | 架构职责与业务语义说明 |
|---|---|---|
| 消息目标(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)会随之更新。
删除用户级联清理:
当删除某个 Auth 用户时,该用户下属的所有 Targets 以及关联的 Topic Subscribers 记录会在同一清理流程中被移除,确保不会向已注销用户继续发送任何营销或告警信息。
2. 通过 Server API / SDK 注册扩展 Target(Push 设备与备用通知渠道)
在用户详情的 「Targets」 页签,具备相应权限时可点击 创建推送目标,选择渠道并填写接收标识;名称、目标 ID 和提供商 ID 可按需填写。也可通过 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: 创建设备目标;确认 HTTP 2xx 和返回内容。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X POST "${APPBASE_ENDPOINT}/users/user_zhangwei_001/targets" -f -i \
-H "Content-Type: application/json" \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
--header @- \
-d '{
"targetId": "tgt_zhangwei_ios_oncall",
"providerType": "push",
"identifier": "apns_prod_token_9f8e7d6c5b4a3210fedcba9876543210",
"name": "张伟-iPhone16Pro-值班终端"
}'
)步骤 2: 创建成功后,单独查询用户的设备目标。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -sS -X GET "${APPBASE_ENDPOINT}/users/user_zhangwei_001/targets" -f -i \
-H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
--header @-
)预期返回 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:目标注册时间戳。
批量解绑与清理失效终端:
当员工更换手机、卸载客户端 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并保存。

