RESEARCH.md 11 KB

Microsoft Teams 数据采集调研

核查日期:2026-09-08。结论依据微软官方文档;DOM 覆盖度、路线取舍属于工程判断,尚未通过用户的真实 Teams 账号验证。

后续实际抓包验证

用户随后明确要求通过网页抓包,在关闭 Teams 网页后直接使用 API。当前已改变下面「第一版选择」中的私有接口取舍:完成真实 Teams 消息 GET、聊天增量列表 GET、REST 日历 GET、OWA GetCalendarView/GetCalendarEvent 只读 POST 的重放与 SQLite 入库。接口适配以用户提供的本地 HAR 为证据,不根据名称猜测任意接口或发送未知请求。详见 抓包 API 实现与限制。

HAR 中保留的会话凭证可支持网页关闭后的请求,但本次没有取得与当前采集会话匹配的完整刷新流程,因此没有承诺无交互长期续期。第一版下文中的「不读取认证头、不重放私有请求」仅描述原 DOM 路线,不再代表用户授权后的抓包模式。

0.3.0 进一步加入工具发起的临时微软登录窗口:Playwright 使用独立持久配置目录,捕获通过已有验证器的业务读取请求,保存会话并关闭窗口;Node 进程接管后无需浏览器常驻。登录页仍由微软处理 SSO/MFA,这属于 Teams 网页自身登录,不把微软第一方 client ID 伪装为本工具。是否能通过组织设备/登录策略需要实际认证验证。Playwright 持久配置与关闭行为

历史分页已实测 startTime=0 及响应 backwardLink,消息范围可向前补采。聊天目录仍是已观察/增量发现范围;删除已捕获列表请求的同步头返回 400,没有将该猜测实现为全量目录。刷新令牌绑定用户与客户端、并不绑定单一资源;本次没有验证合法跨资源刷新流程,不能从返回资源不匹配推断其绝对不可行,也不能据此假定可长期自动续期。微软刷新令牌说明

第一版选择

以 Teams 网页 + 浏览器扩展 + 本地 SQLite 为主路线。用户不具备注册 Entra 应用的条件,因此无需先配置 Graph,也可在微软网页完成登录并尝试采集已呈现的数据。聊天、日历为首要目标;活动页捕获为可选实验能力,无法稳定识别时不影响其他数据采集。

路线 适用范围 前置条件和边界 本项目取舍
网页扩展 当前已加载、可见的聊天/消息、日历条目,实验性活动条目 用户正常登录 Teams 网页并启用扩展;关闭页面、未加载的历史和虚拟列表外内容无法保证采集 默认路线
Microsoft Graph 登录用户参与的聊天消息、用户日历 需要自有 Entra 应用注册和 delegated 授权;聊天接口不支持个人 Microsoft 账号 可选模块,默认约 30 秒轮询
Teams 桌面客户端 后续可研究受支持的系统集成或 UI 观察 未找到向外部采集器开放的稳定客户端数据读取接口 后续研究,不作为本版依赖
Teams 私有网页请求 可能涉及网页内部数据结构 未文档化接口没有可依赖的版本契约 不重放私有请求,不提取会话令牌

Edge 扩展通过限定 URL 的 host permissions 和 content-script 匹配访问页面,企业策略可能限制安装。新 Teams 客户端基于持续更新的 WebView2;这不意味着外部扩展可以直接安装进 Teams 客户端。扩展匹配规则、企业扩展管理、新 Teams 客户端说明

网页登录与覆盖度

扩展打开 https://teams.microsoft.com/v2/,用户在微软页面完成账户选择、密码和 MFA。扩展记录页面上的登录可见状态,而不是验证账号凭据;本地配对只授权向本地服务提交观察结果,与 Microsoft OAuth 无关。浏览器仍按自身机制保存 Teams 会话。

扩展只观察 Teams 页面的 DOM,不读取密码、输入框值、cookies、请求认证头或访问令牌。用户为每个账号设置唯一标签;切换 Teams 账号时应同步切换标签,避免把两个账号的数据记在一起。

“持续采集”表示监听页面变化后重复观察,并不承诺后台完整同步或确定的端到端延迟:

  • 聊天通常只能记录打开会话时已经渲染的消息;滚动加载历史后才有机会补录。
  • 日历只覆盖页面已展示的条目;不能据此推断所有日历、完整会议正文或整段时间范围都已同步。
  • 页面关闭、标签页休眠、网络中断、语言和 Teams DOM 更新均可能影响采集。
  • 条目暂时离开 DOM 不等于被删除;本版不会据此生成删除记录。
  • DOM 无可靠 ID 时只能使用派生标识;文本编辑可能被识别为新条目,不能保证跨来源自动合并。

这些限制来自网页观察方式本身;静态 DOM 测试通过也不能证明真实账号的覆盖率。

可选 Graph 接口与授权

数据 v1.0 请求 最低 delegated 权限
聊天列表 GET /me/chats Chat.ReadBasic
消息正文 GET /chats/{chat-id}/messages Chat.Read,同时可用于聊天列表
时间窗口内的日历实例 GET /me/calendar/calendarView?startDateTime=...&endDateTime=... Calendars.ReadBasic;需要正文使用 Calendars.Read
当前用户资料 GET /me User.Read

聊天列表和消息接口需要组织账号。日历视图会展开范围内的重复事件实例和例外。第一版 Graph 使用 User.Read、Chat.Read、Calendars.Read,不需要写聊天或写日历权限。聊天列表、聊天消息、日历视图、用户资料

Chat.Read 和 Calendars.Read delegated 权限本身不强制管理员同意,但租户仍能限制用户同意和应用注册;已有 Teams 登录不能替代自有 Graph 应用授权。权限表、用户同意策略

Graph 模块采用 MSAL Node public-client 授权码流程:浏览器授权 URL → 本地回调校验 state 和有效期 → 使用 PKCE verifier 交换令牌 → 后续静默续期。默认回调为 http://localhost:4318/auth/callback,必须与应用注册匹配,不使用 client secret。令牌只保存在服务内存中,服务重启后重新登录。MSAL Node 授权流程、OAuth 授权码与 PKCE

增量同步与推送边界

消息接口最大 $top=50。按修改时间增量读取时,应同时使用 $orderby=lastModifiedDateTime desc 和 $filter=lastModifiedDateTime gt ...;两者属性不一致会使过滤失效。必须遍历 @odata.nextLink 后再更新水位,并使用重叠窗口与幂等写入处理边界重复。不能仅看消息创建时间,否则会漏掉较早消息的编辑。消息查询规则

消息 ID 只在所属聊天内保证唯一,不同聊天可能重复。Graph adapter 将编码后的聊天 ID 与消息 ID 组合为 externalId,保留 parentId 和 raw.id,防止跨聊天归档覆盖。消息 ID 的作用域

日历 calendarView/delta 可跟踪指定时间窗口的变化;需保存服务器返回的完整 @odata.deltaLink。窗口推进需重新建立范围。轮询是近实时尝试,受请求耗时和限流影响;遇到 429 应遵守 Retry-After 并退避。日历增量、Graph 限流处理

日历 delta 的 @removed 即使写着 reason=deleted,也可能来自窗口外事件的新增或更新,不能直接证明远端事件已删除。本项目对已归档事件设置 removedFromView=true、deleted=false,保留原有标题和正文,显示“从同步视图移除”;从未归档过的移除 tombstone 忽略,不生成空白日程。真正删除需要另外证据,当前没有把这一标记当作确认删除。日历 delta 响应语义

后续可以增加 Graph change notifications:单个聊天的 /chats/{chat-id}/messages 订阅支持 Chat.Read,但本地端口不能直接接收来自 Graph 的推送,需公网 HTTPS 回调、验证与续期机制。用户级 /users/{user-id}/chats/getAllMessages 的订阅指南示例目前使用 beta,不作为第一版依赖。消息订阅、Webhook 要求

消息订阅最长 3 天,rich notifications 最长不足 1 天;Teams 消息订阅有效期超过 1 小时还需 lifecycleNotificationUrl。官方列出的聊天消息通知平均延迟小于 10 秒、最大 1 分钟,因此推送同样不等于零延迟。订阅有效期和延迟

活动数据必须区分来源

截至核查日,官方 Teams Activity Feed 文档说明的是发送通知,没有找到读取用户完整活动 Feed 的公开 API。TeamsActivity.Send 不能用于读取。此结论是对现有官方文档的核查结果,不是对未来能力的断言。官方活动通知接口

项目保留两种明确区分的数据:

  • source=browser, kind=activity:可选、实验性的活动页面已观察条目;不代表完整 Feed。
  • source=graph, kind=activity, raw.derived=true:本地同步发现消息或日历记录变更后生成的变更日志;首次发现不等于刚刚发生,绝不是 Teams 活动通知。

优先验证聊天和日历链路,活动页选择器适配可以延后。真实验收应检查登录、账号切换、页面覆盖、编辑与重复采集、离线恢复;本调研没有执行真实账号登录或完成这些线上验证。