AgentbaseDocs
文档目录

消息目标(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 为用户批量导入备用通知邮箱、值班手机号或绑定自定义 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 中,用户基础通信资料与 Target 保持自动联动,减少人工重复配置:

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:调用 POST /v1/users/{userId}/targets 返回 409 Conflict(user_target_already_exists)?

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

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

相关文档