统一 IM 网关是 DataWorks 管理中心提供的租户级 IM 接入能力,统一托管钉钉、飞书、企业微信的机器人凭据,支持以当前账号或身份映射指定的 DataWorks 账号身份执行消息处理,并将 Data Agent 等 Agent 实例接入 IM。您无需为每个实例重复创建和维护机器人,即可在 IM 中通过 @ 机器人与 Agent 对话,完成数据查询、任务诊断等操作。本文介绍统一 IM 网关的接入步骤、常见用法与工作原理。
功能概述
在企业数据开发与运维场景中,钉钉、飞书、企业微信等 IM 平台通常是团队协作与沟通的主要入口。统一 IM 网关在租户维度统一管理 IM 机器人与凭据,您无需为每个 Agent 实例重复创建和维护机器人;Data Agent、AI助理服务、数据专家 Agent 等不同类型的 Agent 实例可通过机器人直接使用,无需绑定或解绑。消息将路由至会话中选定的目标 Agent 实例,并按机器人配置的执行身份(当前账号或身份映射)执行处理。您无需切换平台,即可在 IM 群聊或单聊中通过 @ 机器人与 Agent 交互,完成对话式的数据查询、任务诊断与运维处理,并实时查看 Agent 的执行过程。
统一 IM 网关提供以下核心能力:
-
机器人统一托管:在租户维度集中创建和维护钉钉、飞书、企业微信机器人及其凭据,各 Agent 实例共享同一机器人,无需重复创建。
-
灵活的执行身份:机器人执行身份支持当前账号与身份映射两种模式。当前账号模式下,以创建该机器人时所使用的 DataWorks 账号身份执行;身份映射模式下,群聊中多人共用一个机器人时,每个 IM 用户映射到自己的 DataWorks 账号,经本人授权后以各自的身份执行,权限按人隔离,避免全群共享一个账号的权限。
-
自动接入与消息路由:机器人自动接入,可用 Agent 无需绑定即可通过机器人使用;网关按会话将 IM 消息路由到选定的目标 Agent 实例。
-
三端一致的交互体验:在钉钉、飞书、企业微信中提供一致的对话、切换实例等交互能力。
-
定时任务结果推送:作为模块内(如运维中心)定时任务的结果推送通道,将任务执行结果推送至指定 IM 会话。
统一 IM 网关支持两类用法:在 IM 中与 Agent 对话,完成数据查询、任务诊断与运维处理;以及作为定时任务执行结果的推送通道,将结果推送至指定 IM 会话。以下介绍接入操作步骤与常见用法,工作原理与链路示意图请参见文档后半部分及附录。
前提条件
-
已开通 DataWorks,且当前账号具备管理中心租户配置的管理权限。
-
已创建目标 Agent 实例(如 Data Agent),创建方式请参见 Data Agent 简介。
-
已在对应 IM 平台创建企业机器人,并获取机器人凭据(如 AppKey、AppSecret)。本文示例中的凭据均为占位符,请替换为您的真实值。各平台机器人需开通的最小权限及配置项,请参见步骤一:在 IM 平台创建机器人并开通权限。
使用限制
-
支持的 IM 平台为钉钉、飞书、企业微信。
-
各平台的交互能力存在差异,具体如下表所示。
能力
钉钉
飞书
企业微信
流式回复
支持(流式卡片)
支持(流式卡片)
支持(原生流式)
停止回复
支持(停止按钮)
支持(停止按钮)
不支持
信息补充
正文文字反问
正文文字反问
正文文字反问
读取引用的文件内容
支持
暂不支持
支持
-
群聊场景下需要 @ 机器人后再发送消息。群聊会话模式在实例的网关配置中设置,详见网关配置(可选)。
-
使用身份映射时,未映射、待本人确认、已拒绝或已撤销的映射关系不能通过该映射执行;同一份映射配置内,IM 用户与 DataWorks 账号均不可重复。
快速创建
以下步骤用于完成统一 IM 网关的接入:步骤一在 IM 平台创建机器人并开通权限,步骤二在统一 IM 网关添加机器人,步骤三(可选)配置身份映射,步骤四在 IM 中验证接入,步骤五(可选)将定时任务结果推送到 IM。如需让不同 IM 用户以各自的 DataWorks 账号身份执行,请完成步骤三,详见步骤三:配置身份映射(可选)。
步骤一:在 IM 平台创建机器人并开通权限
在 IM 平台创建机器人应用时,需为应用开通以下最小权限并完成相应配置,机器人方可正常收发消息、返回流式卡片与交互表单。
钉钉
在钉钉开发者后台创建企业内部应用,添加应用能力“机器人”,将消息接收模式设置为 Stream 模式后发布应用。接入统一 IM 网关时填写 Client ID(AppKey)与 Client Secret(AppSecret)。创建机器人后,其余所需权限均默认开启,仅需额外开通以下两个权限:
|
权限名称 |
权限标识 |
对应功能 |
|
互动卡片实例写权限 |
|
回答卡片、交互表单 |
|
AI 卡片流式更新权限 |
|
流式回答 |
飞书
在飞书开发者后台创建企业自建应用,添加应用能力“机器人”,开通下列权限,并在“事件与回调”中以长连接方式订阅接收消息(im.message.receive_v1)与卡片回传交互(card.action.trigger),发布应用。接入统一 IM 网关时填写 App ID 与 App Secret。机器人需开通的最小权限:
|
权限名称 |
权限标识 |
对应功能 |
|
以应用的身份发消息 |
|
回答、结果推送、卡片发送和更新 |
|
读取用户发给机器人的单聊消息 |
|
私聊 Agent |
|
接收群聊中 @机器人消息事件 |
|
群内 @ Agent |
|
创建与更新卡片 |
|
流式回答、交互表单 |
|
发送、删除消息表情回复 |
|
排队、处理中表情 |
|
获取单聊、群组消息 |
|
引用消息读取、附件下载 |
|
获取群组中所有消息(包含机器人) |
|
群引用消息读取、话题续聊 |
企业微信
在企业微信管理后台创建智能机器人,开启 API 模式并选择长连接后获取凭据。接入统一 IM 网关时填写 Bot ID 与长连接 Secret。企业微信智能机器人通过凭据直接接入,无需在开放平台额外开通 API 权限。
步骤二:在统一 IM 网关添加机器人
-
登录 DataWorks 控制台,进入管理中心。
-
在左侧导航栏,选择租户配置 > 统一 IM 网关,单击机器人管理页签。
-
单击添加机器人,选择 IM 平台(钉钉、飞书或企业微信),填写机器人名称与凭据,选择机器人执行身份(当前账号或身份映射;选择身份映射后需继续选择映射名称),然后单击确定。
凭据填写示例如下(请替换为您的真实值):
-
AppKey:
<YOUR-APP-KEY> -
AppSecret:
<YOUR-APP-SECRET>
-
在 IM 平台创建机器人时,需为应用开通的最小权限及配置项(如钉钉的 Stream 模式、飞书的长连接事件与回调),请参见步骤一:在 IM 平台创建机器人并开通权限。
机器人执行身份两种模式(当前账号、身份映射)的含义与对比,请参见执行身份与身份映射。选择身份映射后,需在步骤三完成映射配置与本人授权,成员映射关系方可生效。
在机器人列表中,可对已有机器人执行以下管理操作:
|
操作 |
说明 |
|
编辑 |
修改机器人名称、凭据或执行身份。 |
|
启用 / 停用 |
控制机器人是否生效。停用后该机器人不再接收和回复消息。 |
|
删除 |
删除机器人。删除前需要输入机器人名称进行二次确认。 |
步骤三:配置身份映射(可选)
本步骤可选:若机器人执行身份为当前账号,可跳过本步骤,直接执行步骤四。身份映射用于建立 IM 成员与 DataWorks 账号的对应关系,是一份独立、可复用的配置:一份配置可包含多条成员映射关系,多个机器人可引用同一份配置。机器人执行身份选择身份映射后,IM 用户通过机器人发起的请求将以映射中已生效的 DataWorks 账号身份执行。
身份映射涉及以下角色:
-
映射配置管理员:可查看、使用和编辑该映射配置。创建者默认为管理员且不可移除;租户管理员拥有全部身份映射的管理权限。
-
被映射账号本人:核对并决定是否允许某个 IM 用户使用自己的 DataWorks 身份,可同意、拒绝或撤销授权。
管理员操作:创建身份映射
-
登录 DataWorks 控制台,进入管理中心。
-
在左侧导航栏,选择租户配置 > 统一 IM 网关,单击身份映射管理页签。
-
单击创建身份映射,输入映射名称,选择 IM 类型,并按需添加管理员。
-
单击添加成员映射,在左侧选择 IM 成员,在右侧选择对应的 DataWorks 账号。录入方式支持以下两种:
-
从已聊用户中选择(默认):从与机器人发生过交互的用户中选择。若目标成员未出现在列表中,可先让其与机器人单聊,再重新查询。
-
手动录入:填写平台实际使用的用户 ID(如钉钉用户 ID)与用户名。请勿以显示名代替用户 ID;可先让成员与机器人单聊,或在 Agent Web 端对应 IM 会话中核对 ID。
-
-
单击确定保存配置。
同一份映射配置内,IM 用户与 DataWorks 账号均不可重复。新增或变更的映射关系需经对应 DataWorks 账号本人授权后方可生效;管理员保存关系不等于本人已授权。
账号本人操作:本人授权
成员映射关系保存后,需由被映射的 DataWorks 账号本人完成授权:
-
管理员将授权信息发送给目标 DataWorks 账号本人。
-
本人使用该 DataWorks 账号登录管理中心,在统一 IM 网关的身份映射管理页签单击待我授权,打开我的授权。
-
核对 IM 用户与执行身份后,选择同意或拒绝。
-
返回映射详情刷新并核对映射关系状态。
我的授权支持按全部、待本人确认、已生效、已拒绝、已撤销筛选授权记录,各状态含义如下:
|
状态 |
说明 |
|
待本人确认 |
关系已保存,等待账号本人核对并决定。 |
|
已生效 |
本人已同意,该 IM 用户可通过引用此映射的机器人使用本人身份执行。 |
|
已拒绝 |
本人已拒绝,不授予该 IM 用户使用本人身份的权限。 |
|
已撤销 |
本人已撤销此前的授权,该关系不再生效。 |
已生效的授权记录支持复制授权信息与撤销操作。
复制或打开授权链接不会自动完成授权,仍需本人在确认界面同意。撤销已有授权不会自动终止已经运行的任务。
步骤四:验证接入
-
在 IM 平台与机器人单聊,或在群聊中 @ 机器人。
-
发送一条数据查询或任务诊断消息,若机器人正常返回 Agent 的处理结果,即表示接入成功。首次对话时 Agent 选择卡的使用与实例切换方式,请参见在 IM 中与 Agent 对话。
步骤五:将定时任务结果推送到 IM(可选)
除在 IM 中与 Agent 对话外,统一 IM 网关还可作为定时任务执行结果的推送通道。DataWorks 模块内(如运维中心)的定时任务支持在结果推送配置中选择统一 IM 网关,任务执行完成后将结果推送至指定 IM 会话。
配置结果推送
以运维中心的 AI 定时任务为例,配置步骤如下:
-
在新建或编辑定时任务对话框中,切换到结果推送。
-
在推送方式中勾选统一 IM 网关。
-
选择 IM 机器人与会话类型(群聊或单聊)。
-
选择推送目标。目标可为用户或群聊,下拉列表仅展示与机器人有过消息交互的对象,即机器人曾向其发送过消息的用户,或机器人曾在其中发送过消息的群聊。单击添加推送目标可配置多个推送目标。
-
完成其余任务配置并保存。任务执行完成后,执行结果经统一 IM 网关推送至指定 IM 会话。
推送效果
任务执行完成后,机器人向指定群聊或单聊发送结果消息,内容包含任务名称、成功或失败状态、执行摘要与详情入口;任务失败时,相关人员可在 IM 中即时感知并处理。
结果推送复用统一 IM 网关已托管的机器人,无需额外配置凭据;推送目标须为机器人可触达的 IM 会话。
在 IM 中与 Agent 对话
完成接入后,您可以在单聊或群聊中与 Agent 对话,完成数据查询、任务诊断等对话式操作。以下以钉钉为例,飞书、企业微信操作相同。
与 Agent 对话
-
在 IM 中与机器人单聊并直接发送请求;群聊中 @ 机器人后发送。示例:@机器人 帮我诊断昨日实例 X 同步任务的失败原因。
-
首次对话时,机器人返回 Agent 选择卡,在卡中选择 Agent 类型与实例;选择结果按当前会话生效,后续可重新执行
/list变更。 -
Agent 按机器人执行身份处理请求,并在会话中返回结果;需要补充信息时,以正文文字反问,您在后续消息中回复后即可继续处理。
对话效果
Agent 按机器人执行身份处理请求,结果在会话中实时返回;您可继续追问,或执行 /list 切换其他 Agent 实例。示例对话(钉钉群聊):
用户:@机器人 帮我诊断昨日实例 X 同步任务的失败原因。
Agent:返回诊断结论与处理建议,并附执行详情。
机器人执行身份为身份映射时,同一群内的请求按发起人分别执行,效果如下:
-
已生效成员以本人身份执行:请求以发起人映射的 DataWorks 账号身份执行,可见资源与可执行操作与该账号的权限一致,权限按人隔离。
-
未生效关系不能执行:未映射、待本人确认、已拒绝或已撤销的发起人不能通过该映射执行,机器人会提示其完成授权。
-
与当前账号模式的对比:当前账号模式下,群内所有成员均以创建机器人时所使用的同一账号的身份执行,共享该账号的权限;身份映射模式避免了全群共享一个账号带来的权限放大。
示例(群聊,身份映射模式):张三、李四的成员映射关系均已生效。
张三:@机器人 列出我有权限查看的同步任务。机器人以张三的 DataWorks 账号执行,仅返回张三权限范围内的任务。
李四:@机器人 诊断昨日实例 X 同步任务的失败原因。机器人以李四的账号执行;若李四对该任务无权限,则无法通过机器人查看或操作该任务。
Agent 类型
机器人可使用的 Agent 分为以下类型,选择卡中会标注类型与运行状态:
|
Agent 类型 |
说明 |
实例展示范围 |
休眠 / 唤醒 |
|
Data Agent |
通用智能体,支持创建多个实例。 |
展示当前账号可用的实例(含休眠中)。 |
支持。会话中若实例处于休眠状态,将自动唤醒。 |
|
AI助理服务 |
面向数据运维场景的 Agent,支持创建多个实例。 |
仅运行中实例。 |
不支持。 |
|
数据专家 Agent |
如数据集成、数据质量、数据治理、数据运维、知识助理等内置 Agent,每种类型仅一个实例,无需单独创建。 |
展示当前账号可用的实例(含休眠中)。 |
支持。会话中若实例处于休眠状态,将自动唤醒。 |
IM 命令
在单聊或群聊中,支持以下命令。命令的选择结果按会话生效,重新执行 /list 选择即覆盖之前的选择。
|
命令 |
说明 |
|
|
返回 Agent 选择卡,单击选项即切换本会话的默认 Agent。 |
|
|
列出运行中的 Data Agent,确认后异步休眠所选实例。 |
|
|
列出休眠中的 Data Agent,选择后自动唤醒所选实例。 |
交互能力
-
单聊与群聊:单聊中直接发送消息即可与 Agent 对话;群聊中需要 @ 机器人。
-
流式回复与停止:Agent 的处理过程以流式方式实时展示。钉钉和飞书支持在回复过程中停止。
-
卡片更多操作(钉钉):钉钉会话的回复卡片提供更多操作菜单,用于会话与实例管理:开始新会话、重置会话、压缩上下文、切换 Agent、唤醒实例。
-
信息补充:当 Agent 需要补充信息时,钉钉、飞书、企业微信均以正文文字反问收集,您在后续消息中回复后即可继续处理。
-
图片与文件:支持发送图片与文件供 Agent 识别处理;仅发送文件时会返回接收回执,引用该文件并发问后由 Agent 读取处理。
-
引用消息:支持引用一条消息并追问,Agent 的回复会结合被引用的内容。
网关配置(可选)
在实例的IM 频道 > 平台托管(IM 网关)中单击网关配置,可配置当前 Agent 实例通过 IM 网关发起的会话行为。该配置仅对当前实例的 IM 网关会话生效。网关配置项随 Agent 实例的镜像版本发布,若页面提示某配置项不支持,请更新实例的镜像版本后再试。
-
群聊会话模式:决定群聊中上下文如何组织,支持以下两种模式:
模式
上下文组织
适用场景
共享会话
同一群内的成员共同延续会话上下文,可围绕此前的讨论接力追问。
团队共同分析、多人接力排查、群内协同讨论。
独立会话
按群内发起人分别组织上下文,各成员独立延续自己的问题。
同群多人并行提问,各自维持任务上下文。
-
Qwen 模型与思考强度:Qwen 模型用于选择当前实例经 IM 网关调用时使用的模型;思考强度用于选择该模型支持的推理设置。可选项以实例实际提供的下拉列表为准;使用模型默认值表示沿用模型自身设置。该选择仅针对通过 IM 网关发起的会话,不影响 Web 端直接会话的模型配置。
-
飞书群话题隔离:开启后,飞书群的新消息将创建话题,同一话题内的消息延续同一上下文,便于同一群中的不同讨论围绕话题展开。该项仅针对飞书群聊。
-
企业微信群任务完成后私信发送人:开启后,企业微信群聊中的任务结束时,除群内回复外,额外向该任务的发起人发送私信完成通知,便于发起人及时感知任务结果。该通知仅发送给发起人,不改变执行账号或身份映射授权。
群聊会话模式决定上下文如何划分,身份映射决定以谁的 DataWorks 身份执行,两者相互独立。选择独立会话后,回复仍可能出现在原群聊中,请勿将其作为保密空间使用。
工作原理
机器人托管与自动接入
统一 IM 网关在租户维度集中创建和维护钉钉、飞书、企业微信机器人及其凭据,各 Agent 实例共享同一组机器人,无需按实例重复创建。当前账号可用的 Data Agent、AI助理服务、数据专家 Agent 等实例可通过机器人直接使用,无需绑定或解绑。用户发送消息后,统一 IM 网关按当前会话选定的 Agent 实例路由消息。
群聊场景下,群聊会话模式决定上下文如何组织:共享会话模式下群内全体成员共同延续同一会话上下文;独立会话模式下按群内发起人分别组织上下文。会话模式在实例的网关配置中设置,详见网关配置(可选)。
执行身份与身份映射
机器人执行身份决定机器人处理消息时,以谁的 DataWorks 身份访问资源,支持当前账号与身份映射两种模式:
|
模式 |
执行账号 |
适用场景 |
是否需本人授权 |
|
当前账号 |
经该机器人的所有请求,均以创建该机器人时所使用的 DataWorks 账号身份执行。 |
个人使用或小范围可信团队。请核对该账号的目标覆盖范围。 |
不需要。 |
|
身份映射 |
按已生效的成员映射关系,以发起人对应的 DataWorks 账号身份执行,权限按人隔离。 |
群聊中多人共用一个机器人,且各成员需以各自账号身份执行。 |
需要。成员映射关系经账号本人授权后生效。 |
身份映射是一份独立、可复用的配置,用于建立 IM 成员与 DataWorks 账号的对应关系:一份配置可包含多条成员映射关系,多个机器人可引用同一份配置。每条成员映射关系由管理员保存后处于待本人确认状态,经账号本人同意后 生效 ,本人也可拒绝或撤销授权;未映射、待本人确认、已拒绝或已撤销的关系不能通过该映射执行。配置与授权操作请参见步骤三:配置身份映射(可选)。
常见问题
-
Q:接入统一 IM 网关后,还需要在实例内单独填写机器人凭据吗?
A:实例通过统一 IM 网关接入时无需重复填写凭据,凭据由网关统一托管;若在实例内 IM 频道创建机器人,则需在创建时填写机器人凭据,创建后纳入统一 IM 网关统一托管。
-
Q:统一 IM 网关接入与实例内独立频道接入应如何选择?
A:统一 IM 网关在租户维度托管机器人,机器人可被多个实例共享、凭据集中维护,适合多实例、多平台的统一接入场景。实例内独立频道接入在实例维度单独维护凭据,适合单个实例的独立接入。建议优先使用统一 IM 网关。
-
Q:从实例内独立频道迁移到统一 IM 网关时需要注意什么?
A:先在统一 IM 网关添加机器人并完成接入验证,再停用实例内原有的独立频道配置。同一机器人不应同时在两处启用,否则可能出现重复连接和重复回复。
-
Q:机器人无响应或消息收发异常,应如何排查?
A:建议按以下责任边界逐层排查:
-
平台连接:确认机器人处于启用状态,机器人状态为已连接。
-
执行身份与实例路由:确认机器人执行身份符合预期——当前账号模式下该账号权限需覆盖目标资源;身份映射模式下发起人的映射关系需已生效(详见步骤三:配置身份映射(可选)),且会话中已选定目标 Agent 实例。
-
实例执行:确认目标实例处于运行中;若处于休眠中,可发送
/awake唤醒。 -
最终回复:确认所涉及的能力在目标 IM 平台受支持(各平台能力差异请参见使用限制)。
-
-
Q:在群聊中 @ 机器人没有反应,如何处理?
A:确认机器人已启用并已接入;群聊中需先 @ 机器人再发送消息。若实例的网关配置选择共享会话,群内成员共享同一会话上下文,任一成员切换实例会对群内全体成员生效。
-
Q:添加成员映射时,目标成员未出现在“从已聊用户中选择”列表中,如何处理?
A:该列表仅展示与机器人发生过交互的用户。可先让该成员与机器人单聊,再重新查询;也可改用手动录入,填写平台实际使用的用户 ID(如钉钉用户 ID)与用户名,请勿以显示名代替用户 ID。
-
Q:将授权链接发给成员或打开链接后,身份映射会自动生效吗?
A:不会。复制或打开授权链接不等于完成授权,仍需账号本人在我的授权中核对并同意后才生效。撤销已有授权后关系不再生效,但不会自动终止已经运行的任务。
附录:消息与结果推送链路示意图
以下示意图展示统一 IM 网关的消息处理链路与定时任务结果推送链路,帮助您理解消息在各环节之间的流转过程。
消息链路
接入统一 IM 网关后,消息按以下链路流转:用户在 IM 平台向机器人发送消息,机器人将消息转发至统一 IM 网关。网关接收后按机器人执行身份解析实际操作账号:当前账号模式下,所有成员统一绑定创建机器人时所使用的 DataWorks 账号;身份映射模式下,网关按消息发送者的 IM UserID 查询身份映射配置,取得各成员已生效的 DataWorks 账号(未映射或待确认的成员不执行)。解析完成后,网关以对应 DataWorks 账号的身份将消息路由至会话中选定的目标 Agent 实例执行,实例处理完成后将结果返回统一 IM 网关,最终由机器人回复到 IM 平台。
结果推送链路
DataWorks 模块内(如运维中心)的定时任务支持在结果推送配置中选择统一 IM 网关。任务执行完成后,执行结果由统一 IM 网关通过已托管的机器人发送至指定 IM 会话(群聊或单聊),无需为定时任务单独创建机器人。