统一 IM 网关

更新时间:
复制 MD 格式

统一 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)。创建机器人后,其余所需权限均默认开启,仅需额外开通以下两个权限:

权限名称

权限标识

对应功能

互动卡片实例写权限

Card.Instance.Write

回答卡片、交互表单

AI 卡片流式更新权限

Card.Streaming.Write

流式回答

飞书

在飞书开发者后台创建企业自建应用,添加应用能力“机器人”,开通下列权限,并在“事件与回调”中以长连接方式订阅接收消息(im.message.receive_v1)与卡片回传交互(card.action.trigger),发布应用。接入统一 IM 网关时填写 App ID 与 App Secret。机器人需开通的最小权限:

权限名称

权限标识

对应功能

以应用的身份发消息

im:message:send_as_bot

回答、结果推送、卡片发送和更新

读取用户发给机器人的单聊消息

im:message.p2p_msg:readonly

私聊 Agent

接收群聊中 @机器人消息事件

im:message.group_at_msg:readonly

群内 @ Agent

创建与更新卡片

cardkit:card:write

流式回答、交互表单

发送、删除消息表情回复

im:message.reactions:write_only

排队、处理中表情

获取单聊、群组消息

im:message:readonly

引用消息读取、附件下载

获取群组中所有消息(包含机器人)

im:message.group_msg.include_bot:read

群引用消息读取、话题续聊

企业微信

在企业微信管理后台创建智能机器人,开启 API 模式并选择长连接后获取凭据。接入统一 IM 网关时填写 Bot ID 与长连接 Secret。企业微信智能机器人通过凭据直接接入,无需在开放平台额外开通 API 权限。

步骤二:在统一 IM 网关添加机器人

  1. 登录 DataWorks 控制台,进入管理中心。

  2. 在左侧导航栏,选择租户配置 > 统一 IM 网关,单击机器人管理页签。

  3. 单击添加机器人,选择 IM 平台(钉钉、飞书或企业微信),填写机器人名称与凭据,选择机器人执行身份(当前账号或身份映射;选择身份映射后需继续选择映射名称),然后单击确定。

    凭据填写示例如下(请替换为您的真实值):

    • AppKey:<YOUR-APP-KEY>

    • AppSecret:<YOUR-APP-SECRET>

在 IM 平台创建机器人时,需为应用开通的最小权限及配置项(如钉钉的 Stream 模式、飞书的长连接事件与回调),请参见步骤一:在 IM 平台创建机器人并开通权限。

机器人执行身份两种模式(当前账号、身份映射)的含义与对比,请参见执行身份与身份映射。选择身份映射后,需在步骤三完成映射配置与本人授权,成员映射关系方可生效。

在机器人列表中,可对已有机器人执行以下管理操作:

操作

说明

编辑

修改机器人名称、凭据或执行身份。

启用 / 停用

控制机器人是否生效。停用后该机器人不再接收和回复消息。

删除

删除机器人。删除前需要输入机器人名称进行二次确认。

步骤三:配置身份映射(可选)

本步骤可选:若机器人执行身份为当前账号,可跳过本步骤,直接执行步骤四。身份映射用于建立 IM 成员与 DataWorks 账号的对应关系,是一份独立、可复用的配置:一份配置可包含多条成员映射关系,多个机器人可引用同一份配置。机器人执行身份选择身份映射后,IM 用户通过机器人发起的请求将以映射中已生效的 DataWorks 账号身份执行。

身份映射涉及以下角色:

  • 映射配置管理员:可查看、使用和编辑该映射配置。创建者默认为管理员且不可移除;租户管理员拥有全部身份映射的管理权限。

  • 被映射账号本人:核对并决定是否允许某个 IM 用户使用自己的 DataWorks 身份,可同意、拒绝或撤销授权。

管理员操作:创建身份映射

  1. 登录 DataWorks 控制台,进入管理中心。

  2. 在左侧导航栏,选择租户配置 > 统一 IM 网关,单击身份映射管理页签。

  3. 单击创建身份映射,输入映射名称,选择 IM 类型,并按需添加管理员。

  4. 单击添加成员映射,在左侧选择 IM 成员,在右侧选择对应的 DataWorks 账号。录入方式支持以下两种:

    • 从已聊用户中选择(默认):从与机器人发生过交互的用户中选择。若目标成员未出现在列表中,可先让其与机器人单聊,再重新查询。

    • 手动录入:填写平台实际使用的用户 ID(如钉钉用户 ID)与用户名。请勿以显示名代替用户 ID;可先让成员与机器人单聊,或在 Agent Web 端对应 IM 会话中核对 ID。

  5. 单击确定保存配置。

重要

同一份映射配置内,IM 用户与 DataWorks 账号均不可重复。新增或变更的映射关系需经对应 DataWorks 账号本人授权后方可生效;管理员保存关系不等于本人已授权。

账号本人操作:本人授权

成员映射关系保存后,需由被映射的 DataWorks 账号本人完成授权:

  1. 管理员将授权信息发送给目标 DataWorks 账号本人。

  2. 本人使用该 DataWorks 账号登录管理中心,在统一 IM 网关的身份映射管理页签单击待我授权,打开我的授权。

  3. 核对 IM 用户与执行身份后,选择同意或拒绝。

  4. 返回映射详情刷新并核对映射关系状态。

我的授权支持按全部、待本人确认、已生效、已拒绝、已撤销筛选授权记录,各状态含义如下:

状态

说明

待本人确认

关系已保存,等待账号本人核对并决定。

已生效

本人已同意,该 IM 用户可通过引用此映射的机器人使用本人身份执行。

已拒绝

本人已拒绝,不授予该 IM 用户使用本人身份的权限。

已撤销

本人已撤销此前的授权,该关系不再生效。

已生效的授权记录支持复制授权信息与撤销操作。

说明

复制或打开授权链接不会自动完成授权,仍需本人在确认界面同意。撤销已有授权不会自动终止已经运行的任务。

步骤四:验证接入

  1. 在 IM 平台与机器人单聊,或在群聊中 @ 机器人。

  2. 发送一条数据查询或任务诊断消息,若机器人正常返回 Agent 的处理结果,即表示接入成功。首次对话时 Agent 选择卡的使用与实例切换方式,请参见在 IM 中与 Agent 对话。

步骤五:将定时任务结果推送到 IM(可选)

除在 IM 中与 Agent 对话外,统一 IM 网关还可作为定时任务执行结果的推送通道。DataWorks 模块内(如运维中心)的定时任务支持在结果推送配置中选择统一 IM 网关,任务执行完成后将结果推送至指定 IM 会话。

配置结果推送

以运维中心的 AI 定时任务为例,配置步骤如下:

  1. 在新建或编辑定时任务对话框中,切换到结果推送。

  2. 在推送方式中勾选统一 IM 网关。

  3. 选择 IM 机器人与会话类型(群聊或单聊)。

  4. 选择推送目标。目标可为用户或群聊,下拉列表仅展示与机器人有过消息交互的对象,即机器人曾向其发送过消息的用户,或机器人曾在其中发送过消息的群聊。单击添加推送目标可配置多个推送目标。

  5. 完成其余任务配置并保存。任务执行完成后,执行结果经统一 IM 网关推送至指定 IM 会话。

推送效果

任务执行完成后,机器人向指定群聊或单聊发送结果消息,内容包含任务名称、成功或失败状态、执行摘要与详情入口;任务失败时,相关人员可在 IM 中即时感知并处理。

说明

结果推送复用统一 IM 网关已托管的机器人,无需额外配置凭据;推送目标须为机器人可触达的 IM 会话。

在 IM 中与 Agent 对话

完成接入后,您可以在单聊或群聊中与 Agent 对话,完成数据查询、任务诊断等对话式操作。以下以钉钉为例,飞书、企业微信操作相同。

与 Agent 对话

  1. 在 IM 中与机器人单聊并直接发送请求;群聊中 @ 机器人后发送。示例:@机器人 帮我诊断昨日实例 X 同步任务的失败原因。

  2. 首次对话时,机器人返回 Agent 选择卡,在卡中选择 Agent 类型与实例;选择结果按当前会话生效,后续可重新执行 /list 变更。

  3. Agent 按机器人执行身份处理请求,并在会话中返回结果;需要补充信息时,以正文文字反问,您在后续消息中回复后即可继续处理。

对话效果

Agent 按机器人执行身份处理请求,结果在会话中实时返回;您可继续追问,或执行 /list 切换其他 Agent 实例。示例对话(钉钉群聊):

用户:@机器人 帮我诊断昨日实例 X 同步任务的失败原因。

Agent:返回诊断结论与处理建议,并附执行详情。

机器人执行身份为身份映射时,同一群内的请求按发起人分别执行,效果如下:

  • 已生效成员以本人身份执行:请求以发起人映射的 DataWorks 账号身份执行,可见资源与可执行操作与该账号的权限一致,权限按人隔离。

  • 未生效关系不能执行:未映射、待本人确认、已拒绝或已撤销的发起人不能通过该映射执行,机器人会提示其完成授权。

  • 与当前账号模式的对比:当前账号模式下,群内所有成员均以创建机器人时所使用的同一账号的身份执行,共享该账号的权限;身份映射模式避免了全群共享一个账号带来的权限放大。

说明

示例(群聊,身份映射模式):张三、李四的成员映射关系均已生效。

张三:@机器人 列出我有权限查看的同步任务。机器人以张三的 DataWorks 账号执行,仅返回张三权限范围内的任务。

李四:@机器人 诊断昨日实例 X 同步任务的失败原因。机器人以李四的账号执行;若李四对该任务无权限,则无法通过机器人查看或操作该任务。

Agent 类型

机器人可使用的 Agent 分为以下类型,选择卡中会标注类型与运行状态:

Agent 类型

说明

实例展示范围

休眠 / 唤醒

Data Agent

通用智能体,支持创建多个实例。

展示当前账号可用的实例(含休眠中)。

支持。会话中若实例处于休眠状态,将自动唤醒。

AI助理服务

面向数据运维场景的 Agent,支持创建多个实例。

仅运行中实例。

不支持。

数据专家 Agent

如数据集成、数据质量、数据治理、数据运维、知识助理等内置 Agent,每种类型仅一个实例,无需单独创建。

展示当前账号可用的实例(含休眠中)。

支持。会话中若实例处于休眠状态,将自动唤醒。

IM 命令

在单聊或群聊中,支持以下命令。命令的选择结果按会话生效,重新执行 /list 选择即覆盖之前的选择。

命令

说明

/list

返回 Agent 选择卡,单击选项即切换本会话的默认 Agent。

/sleep

列出运行中的 Data Agent,确认后异步休眠所选实例。

/awake

列出休眠中的 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 平台。

image

结果推送链路

DataWorks 模块内(如运维中心)的定时任务支持在结果推送配置中选择统一 IM 网关。任务执行完成后,执行结果由统一 IM 网关通过已托管的机器人发送至指定 IM 会话(群聊或单聊),无需为定时任务单独创建机器人。

image

相关文档