# Microsoft Teams 数据采集调研 核查日期:2026-09-08。结论依据微软官方文档;DOM 覆盖度、路线取舍属于工程判断,尚未通过用户的真实 Teams 账号验证。 ## 后续实际抓包验证 用户随后明确要求通过网页抓包,在关闭 Teams 网页后直接使用 API。当前已改变下面「第一版选择」中的私有接口取舍:完成真实 Teams 消息 GET、聊天增量列表 GET、REST 日历 GET、OWA GetCalendarView/GetCalendarEvent 只读 POST 的重放与 SQLite 入库。接口适配以用户提供的本地 HAR 为证据,不根据名称猜测任意接口或发送未知请求。详见 [抓包 API 实现与限制](NETWORK-CAPTURE.md)。 HAR 中保留的会话凭证可支持网页关闭后的请求,但本次没有取得与当前采集会话匹配的完整刷新流程,因此没有承诺无交互长期续期。第一版下文中的「不读取认证头、不重放私有请求」仅描述原 DOM 路线,不再代表用户授权后的抓包模式。 0.3.0 进一步加入工具发起的临时微软登录窗口:Playwright 使用独立持久配置目录,捕获通过已有验证器的业务读取请求,保存会话并关闭窗口;Node 进程接管后无需浏览器常驻。登录页仍由微软处理 SSO/MFA,这属于 Teams 网页自身登录,不把微软第一方 client ID 伪装为本工具。是否能通过组织设备/登录策略需要实际认证验证。[Playwright 持久配置与关闭行为](https://playwright.dev/docs/api/class-browsertype#browser-type-launch-persistent-context) 历史分页已实测 `startTime=0` 及响应 `backwardLink`,消息范围可向前补采。聊天目录仍是已观察/增量发现范围;删除已捕获列表请求的同步头返回 400,没有将该猜测实现为全量目录。刷新令牌绑定用户与客户端、并不绑定单一资源;本次没有验证合法跨资源刷新流程,不能从返回资源不匹配推断其绝对不可行,也不能据此假定可长期自动续期。[微软刷新令牌说明](https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens) ## 第一版选择 以 **Teams 网页 + 浏览器扩展 + 本地 SQLite** 为主路线。用户不具备注册 Entra 应用的条件,因此无需先配置 Graph,也可在微软网页完成登录并尝试采集已呈现的数据。聊天、日历为首要目标;活动页捕获为可选实验能力,无法稳定识别时不影响其他数据采集。 | 路线 | 适用范围 | 前置条件和边界 | 本项目取舍 | | --- | --- | --- | --- | | 网页扩展 | 当前已加载、可见的聊天/消息、日历条目,实验性活动条目 | 用户正常登录 Teams 网页并启用扩展;关闭页面、未加载的历史和虚拟列表外内容无法保证采集 | 默认路线 | | Microsoft Graph | 登录用户参与的聊天消息、用户日历 | 需要自有 Entra 应用注册和 delegated 授权;聊天接口不支持个人 Microsoft 账号 | 可选模块,默认约 30 秒轮询 | | Teams 桌面客户端 | 后续可研究受支持的系统集成或 UI 观察 | 未找到向外部采集器开放的稳定客户端数据读取接口 | 后续研究,不作为本版依赖 | | Teams 私有网页请求 | 可能涉及网页内部数据结构 | 未文档化接口没有可依赖的版本契约 | 不重放私有请求,不提取会话令牌 | Edge 扩展通过限定 URL 的 host permissions 和 content-script 匹配访问页面,企业策略可能限制安装。新 Teams 客户端基于持续更新的 WebView2;这不意味着外部扩展可以直接安装进 Teams 客户端。[扩展匹配规则](https://learn.microsoft.com/en-us/microsoft-edge/extensions/developer-guide/match-patterns)、[企业扩展管理](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-manage-extensions)、[新 Teams 客户端说明](https://learn.microsoft.com/en-us/microsoftteams/platform/resources/teams-updates) ## 网页登录与覆盖度 扩展打开 `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`,不需要写聊天或写日历权限。[聊天列表](https://learn.microsoft.com/en-us/graph/api/chat-list?view=graph-rest-1.0)、[聊天消息](https://learn.microsoft.com/en-us/graph/api/chat-list-messages?view=graph-rest-1.0)、[日历视图](https://learn.microsoft.com/en-us/graph/api/calendar-list-calendarview?view=graph-rest-1.0)、[用户资料](https://learn.microsoft.com/en-us/graph/api/user-get?view=graph-rest-1.0) `Chat.Read` 和 `Calendars.Read` delegated 权限本身不强制管理员同意,但租户仍能限制用户同意和应用注册;已有 Teams 登录不能替代自有 Graph 应用授权。[权限表](https://learn.microsoft.com/en-us/graph/permissions-reference)、[用户同意策略](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/configure-user-consent) Graph 模块采用 MSAL Node public-client 授权码流程:浏览器授权 URL → 本地回调校验 `state` 和有效期 → 使用 PKCE verifier 交换令牌 → 后续静默续期。默认回调为 `http://localhost:4318/auth/callback`,必须与应用注册匹配,不使用 client secret。令牌只保存在服务内存中,服务重启后重新登录。[MSAL Node 授权流程](https://learn.microsoft.com/en-us/entra/msal/javascript/node/acquire-token-requests)、[OAuth 授权码与 PKCE](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow) ## 增量同步与推送边界 消息接口最大 `$top=50`。按修改时间增量读取时,应同时使用 `$orderby=lastModifiedDateTime desc` 和 `$filter=lastModifiedDateTime gt ...`;两者属性不一致会使过滤失效。必须遍历 `@odata.nextLink` 后再更新水位,并使用重叠窗口与幂等写入处理边界重复。不能仅看消息创建时间,否则会漏掉较早消息的编辑。[消息查询规则](https://learn.microsoft.com/en-us/graph/api/chat-list-messages?view=graph-rest-1.0) 消息 ID 只在所属聊天内保证唯一,不同聊天可能重复。Graph adapter 将编码后的聊天 ID 与消息 ID 组合为 `externalId`,保留 `parentId` 和 `raw.id`,防止跨聊天归档覆盖。[消息 ID 的作用域](https://learn.microsoft.com/en-us/graph/api/resources/chatmessage?view=graph-rest-1.0) 日历 `calendarView/delta` 可跟踪指定时间窗口的变化;需保存服务器返回的完整 `@odata.deltaLink`。窗口推进需重新建立范围。轮询是近实时尝试,受请求耗时和限流影响;遇到 429 应遵守 `Retry-After` 并退避。[日历增量](https://learn.microsoft.com/en-us/graph/delta-query-events)、[Graph 限流处理](https://learn.microsoft.com/en-us/graph/throttling) 日历 delta 的 `@removed` 即使写着 `reason=deleted`,也可能来自窗口外事件的新增或更新,不能直接证明远端事件已删除。本项目对已归档事件设置 `removedFromView=true`、`deleted=false`,保留原有标题和正文,显示“从同步视图移除”;从未归档过的移除 tombstone 忽略,不生成空白日程。真正删除需要另外证据,当前没有把这一标记当作确认删除。[日历 delta 响应语义](https://learn.microsoft.com/en-us/graph/api/event-delta?view=graph-rest-1.0) 后续可以增加 Graph change notifications:单个聊天的 `/chats/{chat-id}/messages` 订阅支持 `Chat.Read`,但本地端口不能直接接收来自 Graph 的推送,需公网 HTTPS 回调、验证与续期机制。用户级 `/users/{user-id}/chats/getAllMessages` 的订阅指南示例目前使用 beta,不作为第一版依赖。[消息订阅](https://learn.microsoft.com/en-us/graph/teams-changenotifications-chatmessage)、[Webhook 要求](https://learn.microsoft.com/en-us/graph/change-notifications-delivery-webhooks) 消息订阅最长 3 天,rich notifications 最长不足 1 天;Teams 消息订阅有效期超过 1 小时还需 `lifecycleNotificationUrl`。官方列出的聊天消息通知平均延迟小于 10 秒、最大 1 分钟,因此推送同样不等于零延迟。[订阅有效期和延迟](https://learn.microsoft.com/en-us/graph/api/resources/subscription?view=graph-rest-1.0) ## 活动数据必须区分来源 截至核查日,官方 Teams Activity Feed 文档说明的是发送通知,没有找到读取用户完整活动 Feed 的公开 API。`TeamsActivity.Send` 不能用于读取。此结论是对现有官方文档的核查结果,不是对未来能力的断言。[官方活动通知接口](https://learn.microsoft.com/en-us/graph/teams-send-activityfeednotifications) 项目保留两种明确区分的数据: - `source=browser, kind=activity`:可选、实验性的活动页面已观察条目;不代表完整 Feed。 - `source=graph, kind=activity, raw.derived=true`:本地同步发现消息或日历记录变更后生成的变更日志;首次发现不等于刚刚发生,绝不是 Teams 活动通知。 优先验证聊天和日历链路,活动页选择器适配可以延后。真实验收应检查登录、账号切换、页面覆盖、编辑与重复采集、离线恢复;本调研没有执行真实账号登录或完成这些线上验证。