ARTICLE DETAIL

资讯详情

深耕编程入门与网站建设的一线实战洞察。

OneUptime 连接 Microsoft Teams 工作区指南:从账号授权到告警与事件通知规则配置

OneUptime 连接 Microsoft Teams 工作区指南:从账号授权到告警与事件通知规则配置 OneUptime 连接 Microsoft Teams 工作区指南从账号授权到告警与事件通知规则配置【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本文以 OneUptime 的 Workspace Connection 功能为主线完整讲解如何把 Microsoft Teams 接入 OneUptime 项目并把事件Incident、告警Alert与计划维护Scheduled Maintenance通知投递到 Teams 频道。读完本文你将掌握账号级 OAuth 授权、团队级应用安装含私有频道与共享频道的边界、基于规则的频道通知配置以及自托管部署下 Bot 消息端点的网络可达性要求。一、接入前准备账号与项目在开始任何配置之前需要先具备两样东西一个 OneUptime 账号。前往 oneuptime.com 注册后登录。在账号下创建一个项目Project。Workspace 连接、通知规则等所有配置都以项目为边界隔离Teams 授权令牌、安装的团队列表和通知规则都归属于某一个具体项目。创建项目后整个 Teams 接入链路才能有归属地后续 OAuth 授权回调中的state参数会携带projectId:userId两个标识见下文源码分析OneUptime 正是借此把 Microsoft 身份与你的项目和用户一一对应。二、连接 Microsoft Teams 到 OneUptime 项目在 OneUptime 控制台进入项目设置Project SettingsMicrosoft Teams按照页面提示完成 Microsoft Teams 账号与当前项目的连接。这一步在底层发生的是标准 OAuth 2.0 授权码流程对应源码位于 Common/Server/API/MicrosoftTeamsAPI.ts浏览器跳转到GET /api/microsoft-teams/auth该端点要求同时配置了MICROSOFT_TEAMS_APP_CLIENT_ID与MICROSOFT_TEAMS_APP_CLIENT_SECRET并通过state参数格式projectId:userId携带项目与用户标识回调携带授权码后服务端向https://login.microsoftonline.com/common/oauth2/v2.0/token换取访问令牌grant_typeauthorization_code请求 scope 固定包含https://graph.microsoft.com/User.Readhttps://graph.microsoft.com/Team.ReadBasic.Allhttps://graph.microsoft.com/Channel.ReadBasic.Allhttps://graph.microsoft.com/ChannelMessage.Send随后调用https://graph.microsoft.com/v1.0/me获取用户资料并把用户级令牌写入WorkspaceUserAuthTokenworkspaceType 为MicrosoftTeams若项目尚未完成管理员授权则跳转至管理员同意流程。管理员同意流程对应两个端点同样是stateprojectId:userIdGET /api/microsoft-teams/admin-consent向https://login.microsoftonline.com/tenant/v2.0/adminconsent发起租户级授权GET /api/microsoft-teams/admin-consent/callback回调中携带tenant、admin_consent等参数OneUptime 使用client_credentials换取应用级 Graph 令牌将tenantId、appAccessToken、availableTeams等数据合并写入WorkspaceProjectAuthToken并把该租户 ID 作为workspaceProjectId持久化——这是后续「一个微软租户只能连接一个项目」判断的数据基础。三、把 OneUptime 应用添加到每个团队必做步骤仅连接账号远远不够。Microsoft 只允许 OneUptime Bot 向「已经添加了该应用」的团队发消息因此必须为每一个需要接收通知的团队单独执行安装。正确操作方式在 Microsoft Teams 中点击团队名称注意不是频道名称旁边的...选择管理团队Manage team应用Apps更多应用More apps找到OneUptime点击添加Add。需要特别区分的三种安装边界场景能否向团队频道发消息说明个人安装Installing for yourself否属于个人维度安装添加到聊天groupChat否仅作用于该聊天添加到团队team是唯一能让 Bot 向该团队频道发消息的安装方式添加到私有频道private channel视情况私有频道必须在频道自身内部安装打开频道 ...管理频道Manage channel应用添加应用仅做团队级安装不会覆盖私有频道共享频道shared channel否Microsoft Teams 不支持 Bot 出现在共享频道中OneUptime 无法向共享频道投递通知典型排错信号如果测试通知返回「OneUptime 应用未安装在该团队中」几乎都是因为漏做了本步骤。从源码看OneUptime 之所以能给出「未安装」这类明确诊断依赖 Teams 应用清单Manifest中的 Resource-Specific ConsentRSC权限TeamsAppInstallation.Read.Group——它允许 OneUptime 在向某个团队发消息前确认该团队里安装的确实是本部署生成的 OneUptime 应用包。若缺少该权限应用会退化为「未知」并把发送交给 Microsoft 去拒绝。清单的完整生成逻辑见 MicrosoftTeamsAPI.ts 中的getTeamsAppManifest()。四、配置事件通知规则Incident Notification Rules连接成功后进入事件页面Incidents PageMicrosoft Teams添加规则即可把事件通知投递到 Teams 频道。例如创建一个「事件创建时向某 Teams 频道发消息」的规则。规则的底层模型是 Common/Models/DatabaseModels/WorkspaceNotificationRule.tsCRUD 端点/workspace-notification-rule其核心字段决定了规则的行为边界name/description规则名称与描述workspaceType工作区类型Teams 场景下取值为MicrosoftTeamseventType触发规则的事件类型如事件创建、监控状态变更等对应NotificationRuleEventType枚举notificationRuleJSON 格式的具体规则体包含目标团队、目标频道、要创建的频道等投递细节projectId规则归属项目所有规则按项目隔离。值得说明的是规则是按需触发的如果规则中开启了「创建 Microsoft Teams 频道Create Microsoft Teams Channel」那么测试该规则时会真的创建频道并向其发消息——但这只能证明 Bot 能向「该频道所属的团队」发消息不能证明其他团队也可达。真实通知是否到达应以设置Settings 通知日志Notification Logs中的记录为准失败时日志会保留 Microsoft 返回的原始错误。五、为告警与计划维护配置同样的通知告警Alerts与计划维护Scheduled Maintenance的通知配置方式与事件完全一致分别进入对应模块页面按照同样的方式配置投递到 Teams 频道的规则即可。OneUptime 为每一类实体提供了独立的消息构建器与动作处理器源码结构位于 Common/Server/Utils/Workspace/MicrosoftTeams/Messages/目录下的Incident.ts、Alert.ts、ScheduledMaintenance.ts、Monitor.ts等负责把实体状态渲染为 Teams 可识别的消息卡片Actions/目录下的同名文件负责处理用户在卡片上的交互动作如确认事件、跳转处理并通过 Bot Framework 适配器接收用户的点击回调。此外个人维度的 Teams 绑定也有对应的直接消息能力UserMicrosoftTeamsAPI.ts 提供POST /user-microsoft-teams/test端点可向用户本人发送一条 Teams 私聊测试消息用于在真实页面依赖它之前提前暴露「应用未为用户安装」这类可操作的错误。六、底层链路Bot Framework 与关键 API 端点云托管与自托管场景下Teams 集成的消息链路都依赖以下几个由 OneUptime 暴露的端点全部位于 MicrosoftTeamsAPI.ts端点方法作用/api/microsoft-teams/authGETOAuth 授权回调stateprojectId:userId/api/microsoft-teams/admin-consentGET发起租户级管理员同意/api/microsoft-teams/admin-consent/callbackGET管理员同意回调换取并持久化应用级 Graph 令牌/api/microsoft-bot/messagesPOSTBot Framework 消息端点接收 Bot 消息、会话安装事件与卡片动作/api/microsoft-bot/messagesGET健康自检返回405 Method Not Allowed即证明路由存在且部署可达/api/microsoft-bot/testGET回显本部署的clientId、botId与消息端点/api/microsoft-teams/app-manifest-zipGET下载本部署专属的 Teams 应用清单 ZIP 包/api/microsoft-teams/teams、/channels、/chatsGET拉取可选团队、频道与 Bot 已加入的会话列表其中GET /api/microsoft-bot/messages是排查「Azure 是否可达本部署」最便宜的探针返回405说明路由存在若返回404且响应体是{message:Page not found - /api/microsoft-bot/messages}则请求已经到达OneUptime通常是旧版本或前置代理剥离了/api前缀若返回的是 nginx/Ingress 的 HTML 错误页则请求根本没到达应用。七、自托管部署的网络访问要求如果你运行的是自托管 OneUptimeTeams 集成的网络要求与云托管不同完整细节见 App/FeatureSet/Docs/Content/en/self-hosted/microsoft-teams-integration.md。核心要点如下OneUptime 的 Teams 集成依赖 Azure Bot。Incoming Webhook 或 Teams Workflow URL 无法替代 Bot 的消息端点Microsoft 要求自托管 Bot 必须有公网可达的 HTTPS 端点。方向目的地用途OneUptime → MicrosoftTCP 443 HTTPS 至 Microsoft Graph、Microsoft 身份与 Bot Framework 服务令牌交换、团队/频道查询与通知投递Microsoft → OneUptimePOST /api/microsoft-bot/messagesBot 消息、会话安装事件与卡片动作用户浏览器 → OneUptime/api/microsoft-teams/auth与/api/microsoft-teams/admin-consent/callback登录与管理员同意跳转需要警惕的认知误区OneUptime 向频道投递告警卡片时是 OneUptime 主动调用 Microsoft 完成鉴权并发送不需要Azure 能反向连回你而卡片按钮点击、help命令、会话注册则全部依赖 Azure Bot Service 主动 POST 到/api/microsoft-bot/messages。因此「告警卡片能正常收到」只能证明出站投递正常不能证明入站 Bot 端点可用——这也是最常见的「看起来半坏」状态。自托管部署需要额外完成创建 Azure App Registration建议单租户配置重定向 URIhttps://your-domain.com/api/microsoft-teams/auth与https://your-domain.com/api/microsoft-teams/admin-consent/callback在 API 权限中授予 Microsoft Graph 委托权限User.Read、Team.ReadBasic.All、Channel.ReadBasic.All、ChannelMessage.Send与应用权限Team.ReadBasic.All、Channel.ReadBasic.All、TeamsAppInstallation.ReadForTeam.All并执行管理员同意创建客户端密钥务必复制密钥值而非密钥 ID创建 Azure Bot 资源并把 Messaging endpoint 设为https://your-domain.com/api/microsoft-bot/messages通过 Docker Compose 环境变量MICROSOFT_TEAMS_APP_CLIENT_ID、MICROSOFT_TEAMS_APP_CLIENT_SECRET、MICROSOFT_TEAMS_APP_TENANT_ID或 Helm valuesmicrosoftTeamsApp.clientId/clientSecret/tenantId注入配置并重启服务从项目设置 工作区 Microsoft Teams下载应用清单在 Teams 中通过「上载自定义应用」安装再按本文第三节逐团队添加应用。发布私有部署的 Bot 端点时还需要把GET /api/microsoft-bot/messages的 405 探针、openssl s_client证书链校验、公网 DNS 解析检查纳入验收流程并注意完全没有入站连接受限策略如完全断网隔离的环境无法使用 Teams 集成——命令、卡片动作与会话发现都依赖 Microsoft 能访问 OneUptime。八、常见问题速查「OneUptime 应用未安装在该团队」应用确实未安装私有频道需在频道内安装按第三节完成安装即可「Microsoft Teams 拒绝了消息因为 Bot 不是该会话成员」BotNotInConversationRoster依次排查 ① 团队里装的是否本部署清单生成的应用包比对botId与MICROSOFT_TEAMS_APP_CLIENT_ID② Azure Bot 是否启用了 Microsoft Teams 频道③ 应用是否仅个人安装而未加入团队④ 目标频道是否为私有频道一个团队能收到、另一个团队收不到安装是按团队逐个生效的为每个需要通知的团队重复第三节「Test Rule」通过但真实通知不到检查规则实际启用的目标真实发送结果以设置 通知日志为准「找不到你的项目配置」消息来源租户与项目连接的租户不一致常见于来宾/B2B 账号比对WorkspaceProjectAuthToken表中的workspaceProjectId与日志中的租户 ID「该 Microsoft 365 组织连接了多个 OneUptime 项目」同一微软租户只能连接一个 OneUptime 项目请在多余项目中断开 Teams 连接。参考资料本指南依据workspace-connections/microsoft-teams.md自托管完整配置self-hosted/microsoft-teams-integration.md核心 API 实现Common/Server/API/MicrosoftTeamsAPI.ts个人消息测试端点Common/Server/API/UserMicrosoftTeamsAPI.ts通知规则数据模型Common/Models/DatabaseModels/WorkspaceNotificationRule.ts消息与动作处理Common/Server/Utils/Workspace/MicrosoftTeams/【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表