Docs
文档目录

消息目标(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) 三大核心子系统,其架构关系如下:

消息目标(User Targets):流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

核心概念与字段定义

核心概念 / 属性字段标识符 / 类型架构职责与业务语义说明
消息目标(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 为用户批量导入备用通知邮箱、值班手机号或绑定自定义 ProviderAPI Key 具备 users.read、targets.read、targets.write
移动端 / 前端开发工程师在用户登录 App 后获取系统 Push Token 并注册为当前账号的 Push TargetClient Session 认证(调用 Account Push Target 接口)或经业务后端代理注册
运维值班经理将 VIP 架构师与值班工程师的 Target 加入告警主题(如 topic_sla_p1_alerts)并在消息中心核对投递回执控制台访问权限 + messages.read、topics.write、subscribers.write

控制台入口与导航路径

  1. 登录 Agentbase 控制台,进入目标组织(如 Agentbase 企业智能中台)下的项目 企业智能客服与知识中台(enterprise-ai-hub-210)。

  2. 在左侧主导航栏选择 「构建」 -> 「认证」(/auth),默认打开 「用户」(Users) 列表页。

  3. 单击目标用户行(例如 user_zhangwei_001 张伟),进入用户详情视图。

  4. 在用户详情页顶部水平页签栏中切换至 「Targets」(消息目标) 页签(路径:/console/project-default-enterprise-ai-hub-210/auth/user-user_zhangwei_001/targets)。

上下游模块关联关系

功能详解与操作指南

1. 自动生成与生命周期同步机制

在 Agentbase 中,用户基础通信资料与 Target 保持自动联动,减少人工重复配置:

  1. 创建用户自动派生:

    • 在控制台 「认证 -> 用户 -> 创建用户」 或调用 POST /v1/users 时,只要填写了 email(如 zhangwei@enterprise.example.com),系统立即生成一条 providerType = "email" 的 Target。

    • 若同时填写了符合 E.164 规范的 phone(如 +8613800138001),系统同步生成一条 providerType = "sms" 的 Target。

  2. 修改用户联系方式同步:

    • 当管理员在用户详情页修改用户的邮箱或手机号时,关联的自动 Target 标识符(identifier)会随之更新。

  3. 删除用户级联清理:

    • 当删除某个 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)

参数名类型必填校验规则与默认值说明
userIdstring是路径参数,目标 Auth 用户的 $id(如 user_zhangwei_001)。
targetIdstring否自定义 Target ID(最长 36 字符,仅允许字母、数字、句点、连字符、下划线,且不得以特殊字符开头);传入 "unique()" 或缺省时由服务端自动生成唯一 ID。
providerTypestring是渠道枚举值,仅允许 email、sms、push 三者之一。
identifierstring是投递终端地址:email 必须通过合法邮箱格式校验;sms 必须是以 + 开头且不超过 15 位数字的 E.164 手机号;push 为非空设备 Token 字符串。
providerIdstring否关联的 Messaging Provider ID(如指定的 APNs 或 FCM Provider ID);缺省时使用项目同类型的默认 Provider。
namestring否终端显示名称(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. 在控制台查看、审计与批量清理消息目标

  1. 进入 认证 -> 用户 -> 单击 user_zhangwei_001 -> Targets 页签。

  2. 列表表格展示以下关键运维列:

    • Target ID:目标唯一标识(支持一键复制 $id,用于在 Messaging 中配置精准投递或排查订阅关系)。

    • Target:对于 push 类型优先展示可读 name(如 张伟-iPhone16Pro-值班终端),对于 email 与 sms 类型展示具体邮箱地址或手机号 identifier。

    • Type:显示渠道标签(Email / SMS / Push)。

    • Provider:显示显式绑定的 Messaging Provider 名称或 ID;采用项目默认通道时为空。

    • Created:目标注册时间戳。

  3. 批量解绑与清理失效终端:

    • 当员工更换手机、卸载客户端 App 或离职交接时,勾选表格左侧对应的复选框,底部或顶部将浮现批量操作栏。

    • 单击 「Delete」(删除) 并在确认弹窗中二次确认,即可立即移除所选 Target。删除后,任何发往该用户或关联 Topic 的消息均不会再向该终端投递。

常见问题与排障

问题 1:调用 POST /v1/users/{userId}/targets 返回 409 Conflict(user_target_already_exists)?

问题 2:在「消息(Messaging)」模块向某用户或主题发送消息时,状态显示失败或提示未找到可用接收目标?

问题 3:使用 API Key 管理用户 Target 时返回 401 Unauthorized(missing scopes (["targets.write"]))?

相关文档