n8n 中文文档

设置 Teams 渠道

提示

功能可用性

Microsoft Teams 渠道可用于:

  • n8n Cloud: 所有计划
  • 自托管: n8n 2.32.3 起的所有计划

提示

预览状态

面向 agent 的 Microsoft Teams 渠道处于 Preview 阶段,未来版本中可能会变化。请避免在生产环境中依赖它。

使用推荐设置或手动设置,将 n8n agent 连接到 Microsoft Teams。有关渠道的工作原理以及用户可以在哪里使用 agent,请参阅将 agent 连接到 Microsoft Teams。

先决条件

开始之前,请确认你具备:

  • 一个你可以编辑、且至少发布过一次的 agent。
  • 一个 Microsoft 可以通过 HTTPS 访问的 n8n 实例。在自托管 n8n 上,将 N8N_WEBHOOK_URL 设置为实例的公开 HTTPS URL。
  • 全球 Microsoft 云中的 Microsoft 365 工作或学校账户。个人账户和主权云无法使用,例如 GCC,或由 21Vianet 运营的 Microsoft Azure。
  • 用于 Azure Bot 的 Azure 订阅。
  • 在 Teams 中添加自定义应用的权限。要么你的 Teams 策略允许上传自定义应用,要么管理员可以把应用发布到你的组织。

推荐设置

推荐设置会在 Microsoft 中为你创建全部资源。n8n Cloud 开箱即用。在自托管 n8n 上,必须先由实例所有者完成设置。请参阅在自托管 n8n 上使用推荐设置。如果它不可用,Teams 渠道只会显示手动设置,标签为 Use your own Microsoft app 使用你自己的 Microsoft 应用。

要连接 Teams:

  1. 打开 agent,前往 Channels 渠道,然后选择 Microsoft Teams。请确认已选择 Recommended setup 推荐设置。
  2. 在 Connect to Microsoft 连接到 Microsoft 中,选择 Sign in with Microsoft 使用 Microsoft 登录,并使用该 agent 的用户所在组织的工作或学校账户登录。
  3. 在 Create Teams app 创建 Teams 应用 中,选择 Create app 创建应用。n8n 会在 Microsoft Entra 中注册该应用。这最多可能需要 30 秒。
  4. 在 Deploy Azure Bot 部署 Azure Bot 中,选择一个 Azure subscription Azure 订阅,然后选择 Create Azure Bot 创建 Azure Bot。这最多可能需要一分钟。
  5. 在 Choose where it works 选择可用范围 中,从用户可以在哪里使用 agent中选择选项。
  6. 在 Install app 安装应用 中,选择 Install for me 为我安装 或 Publish to organization 发布到组织。请参阅上传应用或发布到组织。
  7. 在 Approve access 批准访问 中,立即批准 Microsoft Graph 权限,或稍后在渠道设置中批准。请参阅批准访问。
  8. 在 Connect Microsoft Teams 连接 Microsoft Teams 中,在 Teams 里完成应用添加,然后选择 Done 完成。

n8n 为你创建的内容

资源 详情
应用注册 名称为 <agent-name> (n8n),单租户,带有名为 n8n agent channel 的客户端密钥。n8n 还会创建其服务主体。
资源组 位于 West Europe 的 n8n-agents。如果你选择的订阅中尚不存在,则会创建它。
Azure Bot 以 agent 命名,使用免费 F0 层级,并已启用 Microsoft Teams 渠道。渠道设置会链接到它。
n8n 凭据 一个 Microsoft Entra Service Principal 凭据,包含应用的 ID 和密钥。你不需要把密钥复制到任何地方。

如果再次运行某个步骤,n8n 会复用同一个应用注册和 bot,而不会新建。

推荐设置所需的权限

登录时,n8n 会向 Microsoft 请求这些委派权限。n8n 只在设置 agent 时,以登录用户的身份使用它们:

权限 n8n 用它做什么
User.Read 读取你的个人资料和组织。
Application.ReadWrite.All 创建应用注册、其客户端密钥及其服务主体。
AppCatalog.ReadWrite.All 将 Teams 应用发布到组织的应用目录。
AppCatalog.Submit 当你无法直接发布时,将 Teams 应用提交给管理员批准。
Azure Service Management (user_impersonation) 列出你的 Azure 订阅并创建 Azure Bot。

Application.ReadWrite.All 和 AppCatalog.ReadWrite.All 需要管理员同意。你所在 Microsoft 组织的管理员批准 n8n 一次之后,任何人都可以登录,而不再看到权限界面。如果登录时 Microsoft 显示 Need admin approval,必须先由管理员批准 n8n。选择 Copy link for an admin 复制管理员链接,并把链接发给一位管理员。

这些权限只允许 n8n 以你的身份操作。你在 Microsoft 中还需要具备以下权限:

步骤 你的账户需要什么 如果缺少
Create Teams app 创建 Teams 应用 在 Microsoft Entra 中注册应用程序的权限。你的组织可能将其限制为某些角色。 请管理员注册该应用,或在设置中选择 Use your own Microsoft app instead 改用你自己的 Microsoft 应用 链接,切换到手动设置。
Deploy Azure Bot 部署 Azure Bot Azure 订阅上的 Contributor 角色。 向 Azure 管理员申请 Contributor 访问权限,或选择 Use your own Microsoft app instead 改用你自己的 Microsoft 应用 链接,切换到手动设置。
Publish to organization 发布到组织 直接发布需要 Teams administrator 角色。 n8n 会改为提交应用以供批准。请参阅发布到组织。

手动设置

如果推荐设置不可用,或者你的组织不允许使用它,请使用手动设置。你在 Microsoft 中自行创建资源,并用凭据把它们连接起来。

在 Teams 渠道中,选择 Use your own Microsoft app 使用你自己的 Microsoft 应用。在推荐设置中,Use your own Microsoft app instead 改用你自己的 Microsoft 应用 链接会进入同一位置。请按以下步骤操作:

  1. 在 Microsoft Entra 中注册应用。
  2. 在 n8n 中创建凭据。
  3. 部署 Azure Bot。
  4. 选择可用范围。
  5. 下载应用包。
  6. 批准 Graph 权限(可选)。
  7. 在 Teams 中添加应用。

在 Microsoft Entra 中注册应用

如果你已经有一个其他 agent 未使用的应用注册凭据,请跳过此步骤。

  1. 选择 Open Microsoft Entra 打开 Microsoft Entra,或前往 Microsoft Entra 管理中心 > App registrations > New registration。
  2. 输入名称,例如你的 agent 名称。
  3. 在 Supported account types 中,选择 Accounts in this organizational directory only(单租户)。
  4. 你不需要重定向 URI。选择 Register。
  5. 在 Overview 页面上,复制 Directory (tenant) ID 和 Application (client) ID。
  6. 前往 Certificates & secrets > Client secrets > New client secret。添加描述和到期时间,然后复制密钥的 Value,而不是 Secret ID。Microsoft 只显示该值一次。

bot 发送和接收消息不需要任何 API 权限。

在 n8n 中创建凭据

在 Create credential 创建凭据 中创建新凭据:

  1. Authentication 身份验证: Client Secret 客户端密钥。Teams 渠道不支持证书。
  2. Directory (Tenant) ID 目录(租户)ID: 你复制的租户 ID。
  3. Application (Client) ID 应用程序(客户端)ID: 你复制的客户端 ID。
  4. Client Secret 客户端密钥: 你复制的密钥值。
  5. Microsoft Graph API Base URL Microsoft Graph API 基础 URL: Global 全球。

n8n 会向 Microsoft 验证该凭据。验证通过后,n8n 会显示 Credential verified with Microsoft Entra. 已通过 Microsoft Entra 验证凭据。 每个凭据只能将一个 agent 连接到 Teams。如果另一个 agent 已经在使用它,请为此 agent 注册一个新应用。

有关此凭据类型的更多信息,请参阅 Microsoft Entra Service Principal 凭据。

部署 Azure Bot

选择以下选项之一:

  • New bot 新建 bot: 选择 Deploy to Azure 部署到 Azure。Azure 门户会打开一个模板,n8n 已填入 bot 名称、应用的 ID 和消息终结点。Azure 可能会提示该模板并非来自 Microsoft。选择订阅和资源组,然后创建部署。你需要该订阅上的 Contributor 角色。
  • Existing bot 现有 bot: 选择 Use an existing Azure Bot 使用现有 Azure Bot,并复制 Messaging endpoint 消息终结点。在 Azure 门户中,打开该 bot 的 Configuration 页面,将其粘贴到 Messaging endpoint,并确保该 bot 使用同一个应用注册。然后前往 Channels,打开 Microsoft Teams。

选择可用范围

选择用户可以在哪里使用 agent,以及它如何监听。私聊始终开启。开启 Team channels 团队频道 或 Group and meeting chats 群聊和会议聊天,以便用户在这些位置添加 agent 并 @提及它。读取全部选项会让 agent 在每条消息上运行,每次都会消耗模型额度。详情请参阅用户可以在哪里使用 agent和 agent 如何在频道和群聊中监听。

下载应用包

选择 Download app package 下载应用包。这也会把渠道连接到 agent。该包使用 agent 的名称和图标。

批准 Graph 权限

要让 agent 查找人员和频道并读取附加文件,管理员需要添加 Microsoft Graph 应用程序权限并授予管理员同意。选择 Approve access 批准访问,然后选择 Approve now 立即批准 或 Copy link for admin 复制管理员链接。请参阅批准访问。

如果 agent 只在有人给它发消息时回复,请跳过此步骤。你可以稍后在渠道设置中批准。

在 Teams 中添加应用

  1. 在 Teams 中,前往 Apps > Manage your apps > Upload an app,并上传 zip 文件。
  2. 根据 agent 应工作的位置,选择 Add to a team 或 Add to a chat。
  3. 在 n8n 中选择 Done 完成。

如果看不到 Upload an app,说明你的 Teams 策略不允许自定义应用。请 Teams administrator 允许上传自定义应用,或让其把应用上传到组织的应用目录。

手动设置的权限

权限 类型 谁授予 用于 没有它时
注册应用程序 Microsoft Entra 设置或角色 你的 Microsoft Entra 管理员 注册应用 你无法创建应用注册。
Contributor 订阅上的 Azure 角色 你的 Azure 管理员 部署 Azure Bot 你无法创建 bot。
上传自定义应用 Teams 应用设置策略 你的 Teams administrator 上传应用包 只有管理员可以通过 Teams 管理中心添加应用。
User.ReadBasic.All、Team.ReadBasic.All、Channel.ReadBasic.All 和 Files.Read.All Microsoft Graph 应用程序权限 具有管理员同意权限的 Microsoft 管理员 查找人员和频道,以及频道和群聊中附加的文件 agent 只能在收到消息时回复,并且无法读取这些文件。
ChannelMessage.Read.Group 由 Team channels 团队频道 添加的 RSC 权限 添加应用时的 team owner 读取频道消息和粘贴的图片 agent 无法在频道中工作。
ChatMessage.Read.Chat 由 Group and meeting chats 群聊和会议聊天 添加的 RSC 权限 将应用添加到聊天的人 读取聊天消息和粘贴的图片 agent 无法在群聊中工作。

在自托管 n8n 上使用推荐设置

在自托管 n8n 上,推荐设置需要一个用于在设置过程中让用户登录的 Microsoft 应用。n8n Cloud 会提供一个。在你自己的实例上,由实例所有者提供:

  1. 在 Microsoft Entra 中注册一个多租户应用(Accounts in any organizational directory)。
  2. 将重定向 URI <n8n-url>/rest/oauth2-credential/callback 添加为 Web 平台。
  3. 添加以下委派 API 权限:
    • Microsoft Graph:User.Read、Application.ReadWrite.All、AppCatalog.ReadWrite.All、AppCatalog.Submit、openid、profile、offline_access
    • Azure Service Management:user_impersonation
  4. 创建客户端密钥。
  5. 将客户端 ID 和密钥作为凭据类型 microsoftTeamsManagerOAuth2Api 的凭据覆盖提供:

    json { "microsoftTeamsManagerOAuth2Api": { "clientId": "<client-id>", "clientSecret": "<client-secret>" } }

覆盖生效后,Teams 渠道会显示 Recommended setup 推荐设置。有关如何设置凭据覆盖,请参阅凭据覆盖和预配置 Microsoft OAuth 凭据。

Microsoft Graph 权限

在对话中回复以及读取粘贴的图片,使用应用包中的权限即可。除此之外,应用注册需要四项 Microsoft Graph application 权限:

权限 agent 可以借助它做什么
User.ReadBasic.All 按电子邮件查找人员,以便向他们发送私聊消息并提及他们。
Team.ReadBasic.All 按名称查找团队,以便在其频道中发帖。
Channel.ReadBasic.All 按名称查找频道,以便在其中发帖。
Files.Read.All 读取用户在频道和群聊中附加的文件。

你所在 Microsoft 组织的管理员会一次性批准全部四项。你不能只批准其中一部分。没有这些权限时,agent 只能在有人给它发消息时回复。

批准访问

两种设置都会显示 Approve access 批准访问 步骤。说明会列出,对于你已开启的位置,批准后将解锁哪些能力。你也可以稍后批准:在管理员批准之前,渠道设置会在 Where it works 可用范围 下显示警告。

选择 Approve access 批准访问,然后选择以下之一:

  • Approve now 立即批准: 如果你是组织中的管理员,请自行打开批准页面。
  • Copy link for admin 复制管理员链接: 复制链接并发送给可以批准的管理员。

链接打开的内容取决于设置方式:

  • Recommended setup 推荐设置: Microsoft 管理员同意界面。n8n 已经把权限添加到应用注册。管理员审核这些权限并接受。
  • 手动设置: Microsoft Entra 中该应用注册的 API permissions 页面。管理员在那里添加权限:
    1. 选择 Add a permission > Microsoft Graph > Application permissions。
    2. 搜索并添加上表中的每一项权限。
    3. 选择 Grant admin consent。

警告

使用应用程序权限

请将权限添加为 Application 权限,而不是 Delegated 权限。agent 以应用身份操作,而不是以登录用户身份操作,因此无法使用委派权限。

连接渠道后,两种设置下的渠道设置都会为你检查状态。Microsoft 确认批准后,它们会显示 Permissions approved. 权限已批准。 agent 最多可能需要一小时才能使用这些权限。

相关资源

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。