Bitzsoft.Integrations.MicrosoftGraph 1.0.0-alpha.10

Bitzsoft.Integrations.MicrosoftGraph

多租户 Microsoft Graph v1.0 transport、Microsoft Entra Directory、 Mail、Calendar、OneDrive/SharePoint 文件、Teams 频道读取与变更通知 连接器，目标框架为 net5.0;net8.0;net10.0。

安装与前置条件

dotnet add package Bitzsoft.Integrations.MicrosoftGraph

生产宿主必须提供按租户隔离的 IIntegrationCredentialResolver，并在 Entra 管理中心完成相应应用权限与管理员同意。

已实现

• 全球、美国政府 L4/L5、中国世纪互联隔离云端点；
• OAuth 2.0 client credentials，凭据按业务租户、region、environment、 profile 和 credential name 隔离并支持轮换；
• Graph 标准错误、request-id、Retry-After、429/5xx 与 410 delta 失效；
• 流式或完整正文读取，不设置应用层强制大小上限；
• Users 与 Groups 查询、服务端分页及类型化最小模型；
• Users 与 Groups delta baseline/incremental 同步、tombstone 和 checkpoint；
• delta 分页大小由 Graph 服务端控制，不向不支持 $top 的 delta 请求 注入本地 Sync PageSize；
• Mail 列表/读取、文件夹级 delta、MIME 流式读取及 JSON sendMail；
• Calendar 列表/读取、固定时间窗 calendarView delta 和带 transactionId 的事件创建；
• Users、Groups、Mail、Calendar 的 basic change notification 订阅 list/get/create/renew/reauthorize/delete 生命周期；
• notificationUrl challenge 的 URL 解码、text/plain 原样响应模型；
• Graph 批量 basic/lifecycle notification 的逐项 clientState 固定时间 验证、当前/上一版密钥轮换和共享 Webhook Inbox 接入；
• 一个 Graph HTTP 批次作为一个不可分割 Inbox envelope 持久化，验真后 可通过 MicrosoftGraphChangeNotificationBatch.Parse 拆分业务事件；
• Mail 与 Calendar 全部读取、增量游标和事件创建均请求 Outlook immutable ID，避免项目移动后本地主键失效；
• SharePoint site 按 ID 或 hostname/server-relative path 解析；
• 用户、Microsoft 365 Group 与 SharePoint site 的 drive/document library 枚举，drive 与 driveItem 安全类型化模型；
• root/指定文件夹 children 分页以及 drive 全层级 delta baseline、 tombstone 和 opaque checkpoint；
• 文件完整/Range 流式下载；Graph 的 OAuth 只发送到 Graph origin， 预认证内容 URL 逐跳执行 HTTPS host allow-list 校验并匿名访问；
• 新文件单请求安全创建（固定 If-None-Match: *）和按 item ID + ETag 替换；
• 大文件 upload session 创建、加密持久化恢复、缺口查询、顺序分片、 完成与取消生命周期；
• 租户 Team 分页枚举及 Team 完整读取；
• 团队承载 Channel 的分页枚举、类型化 membership filter、单频道与 primary channel 读取；
• 频道根消息、单消息、回复独立分页与单回复读取；不使用会把大量回复 隐式截在 200 条后的 $expand=replies；
• 完整保留 Teams 消息 body、attachment content、mention、reaction 和 system event detail，不设置应用层正文大小上限，也不在诊断字符串中 输出内容、身份、URL 或资源 ID；
• 指定频道消息的 basic change notification，包含 Teams 一小时 lifecycleNotificationUrl 规则与三天最大订阅周期的请求前校验；
• 重复设置目标状态保持幂等的账号启用/停用 PATCH，并携带 client-request-id，不做隐式写重试；
• 通用 Sync Engine page source。

凭据

宿主为 Productivity:microsoft-graph 注册：

• OAuthClientId
• OAuthClientSecret
• MicrosoftGraphWebhookClientState（16–128 字符，创建和当前验真）
• MicrosoftGraphPreviousWebhookClientState（可选，仅轮换窗口验真）

固定端点示例：

services.AddBitzsoftMicrosoftGraph(
    new MicrosoftGraphEndpoint(
        MicrosoftGraphCloud.Global,
        directoryTenantId: "00000000-0000-0000-0000-000000000000"));

只需要给旧接口兼容 Adapter 复用安全 HTTP、OAuth token cache 和类型化 客户端，而不希望注册 Graph Provider 或全局端点时：

services.AddBitzsoftMicrosoftGraphTransport();

随后可解析 IMicrosoftGraphClientFactory，用显式 MicrosoftGraphEndpoint 和专用 IIntegrationCredentialResolver 创建 端点隔离的 MicrosoftGraphClientSuite。该模式不会覆盖宿主已经注册的 Graph endpoint/credential resolver，主要用于 Microsoft365/AzureAD 旧包的渐进迁移。

生产环境应实现 IIntegrationCredentialResolver 并连接 Vault/KMS；内存 凭据 Store 只适用于开发、测试或宿主明确接受进程内 secret 驻留的场景。

Graph 返回的 upload session URL 本身是短期 bearer secret。 MicrosoftGraphUploadSession.ToString() 不会输出它；只有显式调用 ExportUploadUrl() 才能取出，宿主必须使用 KMS/Vault 加密持久化并禁止 进入日志、遥测、异常或普通配置。

官方 OneDrive/SharePoint 文件域名已由 MicrosoftGraphTransferUrlPolicy 默认允许。私有代理或供应商返回自定义 文件域名时，必须在注册 Graph 前显式注册更严格的 IMicrosoftGraphTransferUrlPolicy；不要通过“允许任意 HTTPS”绕过 SSRF 边界。匿名文件请求不会携带 Graph Authorization、Cookie 或业务 correlation header，也不会自动重定向。

权限与限制

读取 users 通常需要应用权限 User.Read.All，读取 groups 通常需要 Group.Read.All；Mail 读取通常需要 Mail.ReadBasic.All 或 Mail.Read， 发送需要 Mail.Send；Calendar 读取通常需要 Calendars.Read，创建需要 Calendars.ReadWrite。启用/停用账号需要 Microsoft 当前文档规定的 User.EnableDisableAccount.All 与 User.Read.All 组合。应按实际启用 能力授予最小权限，并在客户租户重新核对管理员同意和许可证条件。

文件/drive 读取的应用权限通常从 Files.Read.All 起，SharePoint 场景可 使用 Sites.Read.All；单请求上传通常需要 Files.ReadWrite.All 或 Sites.ReadWrite.All。Microsoft 当前文档对应用身份创建 upload session 列出的权限是 Sites.ReadWrite.All。应优先使用 Sites.Selected 等更小 站点边界并完成客户租户 live sandbox 认证，不能因 SDK 能发出请求就推断 权限已受支持。

租户 Team 枚举通常使用应用权限 Team.ReadBasic.All；频道读取可使用 resource-specific consent 的 ChannelSettings.Read.Group，或租户级 Channel.ReadBasic.All；频道消息读取可使用 ChannelMessage.Read.Group，或租户级 ChannelMessage.Read.All。 RSC 和租户级权限是不同授权模型，必须按部署方式选其一，不能把 Group.Read.All 这类仅为兼容保留的宽权限作为默认方案。

单请求上传遵循 Microsoft 的 250 MB 上游限制。更大文件使用 upload session：每片必须小于 60 MiB，非末片必须是 320 KiB 的整数倍，并按顺序 上传；建议片大小为 5–10 MiB。写请求和分片均不做隐式重试。网络结果 不确定时先查询 upload session 的 nextExpectedRanges，收到 404 则从头 创建会话。下载正文没有应用层强制大小上限；Range 只发送到预认证内容 URL，服务端仍可能忽略 Range 并返回完整 200。

drive delta 是建立一致本地文件索引的首选方式。必须读完所有 nextLink 页面后再应用一批变化；同一 item ID 多次出现时采用最后一次，删除文件夹 前确认应用整批变化后文件夹为空。token=latest 只适合“不需要历史 基线、仅观察未来变化”的场景。410 表示 checkpoint 失效并要求新基线。

Team/Channel/message 读取在四类 Graph 国家云均有官方 v1.0 路由，但 应用身份读取 federated channel 时必须从 channel owner 所在租户发起。 频道消息没有对应的 channel delta feed：首次同步必须枚举完 Team、 Channel、根消息和每个根消息的全部 replies；之后使用逐频道 basic change notification，并周期性完整 reconcile。消息订阅超过一小时必须 提供 lifecycleNotificationUrl，最大生命周期为三天，需在到期前续订。 若收到 missed 或 subscriptionRemoved，应重新读取受影响频道而不是 假定事件连续。

本实现刻意不暴露普通应用身份发帖：Graph 的 application Teamwork.Migrate.All 只支持迁移，不是业务机器人或后台服务的通用 ChannelMessage.Send。组织级 getAllMessages export、聊天、会议、成员、 应用安装和 hosted content bytes 也不在本切片；attachment/hosted content URL 是不透明数据，不得直接交给不受约束的 HTTP 客户端下载。

sendMail 是非幂等操作，不做自动重试；202 Accepted 也不证明完成 投递。Calendar create 强制 transactionId 以降低重复创建风险，但 强端到端幂等仍需宿主 operation ledger；创建请求会提前校验最多 500 名参与者以及全天事件的同一时区午夜边界。Mail delta 仅按文件夹 工作，且 Microsoft 当前文档标记中国世纪互联不可用。

本切片不声明 delegated authorization、beta API、Teams chat/meeting/ membership/app-installation、普通应用身份发帖、文件 sharing/permissions、 rich notifications、附件/hosted content bytes 上传下载或 JSON batch。 不同国家云的 API 可用性并不完全一致，必须逐能力核对并进行 live sandbox 认证。

订阅创建只实现不携带加密 resource data 的 basic notification；每个 批次内所有项目的 clientState 必须匹配当前或上一版租户密钥，否则 整批拒绝。协议层和 Inbox 不截断正文，也不设置强制大小上限。宿主应在 Graph 的 10 秒验证期限内直接处理 validationToken challenge；普通 通知在验真并持久化后尽快返回 202。missed 需触发完整/delta 基线 恢复，subscriptionRemoved 需重建订阅并同步；收到 reauthorizationRequired 时不要在十分钟内同时调用 reauthorize 与 PATCH renewal，因为 PATCH renewal 已包含 reauthorization。订阅创建 和其他写操作不做隐式重试，宿主应使用 operation ledger 协调 409 重复订阅和不确定网络结果。

官方参考：

• National cloud deployments
• List users
• List groups
• Delta query overview
• List messages
• Message delta
• sendMail
• List events
• Calendar view delta
• Create event
• Outlook immutable identifiers
• Create subscription
• Update subscription
• Webhook delivery
• Lifecycle notifications
• Get a SharePoint site
• List drives
• List folder children
• Drive item delta
• Download content
• Upload small files
• Create upload session
• List teams
• Get team
• List channels
• List channel messages
• List message replies
• Teams message change notifications
• Teams change notification overview
• Graph throttling guidance