msgraph-sdk

Microsoft Graph SDK

当在应用程序中集成 Microsoft Graph 以访问 Microsoft 365 数据和服务时，请使用此技能。

始终以目标语言当前的 Microsoft Graph SDK 文档和 SDK 版本作为实现依据，而不要仅凭记忆。

先确定目标语言

1. 当项目包含 .cs、.csproj 或 .sln 文件，或用户请求 C# 指导时，使用 .NET 工作流。请遵循 references/dotnet.md。
2. 当项目包含 package.json、.ts 或 .js 文件，或用户请求 Node.js / 浏览器相关指导时，使用 TypeScript / JavaScript 工作流。请遵循 references/typescript.md。
3. 当项目包含 .py、pyproject.toml 或 requirements.txt，或用户请求 Python 指导时，使用 Python 工作流。请遵循 references/python.md。
4. 如果存在多种语言，请与正在编辑的文件所用语言保持一致，或询问用户。

始终查阅最新文档

• Microsoft Graph 概述：https://learn.microsoft.com/graph/overview
• Graph Explorer（在线试用调用）：https://developer.microsoft.com/graph/graph-explorer
• Graph 权限参考：https://learn.microsoft.com/graph/permissions-reference
• 在可用时使用 Microsoft Docs MCP 工具来获取最新的 API 结构和 SDK 示例。

身份验证 — 选择正确的模式

选择错误的身份验证流程是最常见的 Graph 集成错误。在编写任何身份验证代码之前，请先应用此决策树：

场景	使用的流程
无用户的后台服务 / 守护程序	客户端凭据（仅应用）
Agent 或 API 代表已登录用户执行操作	代理流（OBO）
在 Azure 中运行的应用（Function、Container App、VM）	托管标识（优先于机密）
命令行工具或本地开发脚本	设备代码或交互式浏览器
单页应用（仅浏览器）	授权代码 + PKCE

• 在需要用户上下文时，切勿使用客户端凭据 — Graph 会在权限级别（应用程序与委派）强制实施此要求。
• 在 Azure 托管的应用中优先使用 DefaultAzureCredential；它会先尝试托管标识，并在本地开发时优雅降级。
• 切勿硬编码机密。请使用环境变量、Azure Key Vault 或 Secret Manager。

SDK 核心使用模式

构建客户端

始终只构造一次 GraphServiceClient 并重复使用它（它在内部管理令牌缓存）。

传入 Azure Identity 库中的凭据 — 切勿手动构建原始 HTTP 客户端。

发起调用

• 使用流式构建器 API：client.Users[userId].Messages.GetAsync(...)。
• 始终对异步调用使用 await。
• 指定 $select 以限制返回的字段 — Graph 默认返回的负载很大。
• 在服务端使用 $filter，而不是在内存中筛选返回的集合。
• 当关系较小时，使用 $expand 在单次调用中获取相关资源。

分页

Graph 会对集合进行分页。切勿假定所有项都在一个响应中返回：

• 检查响应中的 @odata.nextLink。
• 使用 SDK 的 PageIterator 辅助工具（三个 SDK 中均可用）自动遍历各页。
• 设置 $top 以控制页面大小（最大值因资源而异，通常为 999）。

高级模式

批量请求

使用 $batch 端点将最多 20 个独立的 Graph 调用合并为单个 HTTP 请求。在以下情况下使用批处理：

• 为仪表板或 Agent 初始化数据，且需要预先获取多个资源。
• 在调用次数较多的操作中降低延迟。

批量响应返回的顺序是乱的 — 请通过你为每个请求分配的 id 字段进行匹配。

增量查询

使用增量查询来增量同步更改，而不是轮询完整集合：

• 首次调用：GET /users/delta 返回所有条目 + 一个 @odata.deltaLink。
• 后续调用：使用 deltaLink 仅接收自上次同步以来发生更改的内容。
• 支持范围：用户、组、邮件、日历事件、Teams 频道等。
• 在两次同步运行之间持久存储 deltaLink（数据库、Blob）。

更改通知（webhook）

通过 POST /subscriptions 订阅资源更改：

• Graph 将更改事件投递到你的 HTTPS 通知 URL。
• 订阅会过期——请在 expirationDateTime 之前续订（最大值因资源而异；邮件/日历通常为 1–3 天，用户/组最长可达 4230 分钟）。
• 验证订阅握手：创建时 Graph 会发送一个 validationToken 查询参数——将其以纯文本形式回显，并返回 HTTP 200。
• 使用生命周期通知（notificationUrl + lifecycleNotificationUrl）来处理错过的事件和重新授权。
• 对于高吞吐量场景，优先使用带资源数据的更改通知（需要额外的加密设置）。

限流

Graph 会积极限流。务必处理 HTTP 429：

• 读取 Retry-After 头——它指定了确切的等待秒数，而不是固定的退避时间。
• SDK 内置的重试中间件在配置后会自动处理 429；请显式启用它。
• 避免使用向 Graph 发起数百个并行请求的扇出模式；改用批处理或队列。

权限

在编写认证代码之前先正确设置权限——错误的作用域会导致 403 错误，之后很难调试。

• 应用程序权限在没有用户的情况下运行（守护程序 / 服务）。需要管理员同意。
• 委派权限在已登录用户的上下文中运行。部分需要管理员同意。
• 请求所需的最低权限。Graph 的权限参考列出了每个操作的最小权限选项。
• 在编码之前，使用 Graph Explorer 测试某个调用实际需要哪些权限。
• 在 Azure 应用注册中：授予 API 权限 → Microsoft Graph → 选择类型（应用程序或委派）→ 在需要时授予管理员同意。

常见 Graph 资源——快速参考

目标	资源路径
获取已登录用户的个人资料	GET /me
列出用户的邮箱邮件	GET /me/messages
发送电子邮件	POST /me/sendMail
列出日历事件	GET /me/events
获取用户的 OneDrive 根目录	GET /me/drive/root/children
列出用户所在的 Teams	GET /me/joinedTeams
发布 Teams 频道消息	POST /teams/{id}/channels/{id}/messages
列出 SharePoint 网站列表	GET /sites/{siteId}/lists
在 M365 中搜索	POST /search/query
列出租户中的所有用户（仅应用）	GET /users
获取组成员	GET /groups/{id}/members

以类似方式，使用 SDK 的流畅 API 在代码中导航到这些资源。

工作流

1. 确定目标语言并阅读匹配的参考文件。
2. 识别认证场景，并从上面的表格中选择正确的流程。
3. 在做出实现选择之前，获取最新的 SDK 文档和 Graph Explorer 示例。
4. 应用最小权限——在 Graph 权限参考中确认。
5. 从一开始就实现分页——不要假设响应只有单页。
6. 从第一天起就为限流启用重试中间件。
7. 对于同步场景，优先使用增量查询而不是轮询。
8. 使用所选参考文件中的语言特定包名、认证提供程序设置和代码模式。

完成标准

• 认证流程与场景匹配（不会在用户上下文的调用中默认使用客户端凭据）。
• GraphServiceClient 只构造一次并复用。
• 所有集合读取都处理分页。
• 限流（429）通过重试中间件或显式的 Retry-After 逻辑处理。
• 权限范围限定为所需的最小权限。
• 不硬编码任何密钥或凭据。
• 代码符合所选语言的当前 SDK 版本模式。