microsoft-graph

Microsoft Graph API 编排技能

Microsoft Graph 是一个统一的 REST API 终结点，可用于访问 Microsoft 365、Windows 和 Enterprise Mobility + Security 中的 Microsoft Cloud 资源。基 URL：https://graph.microsoft.com/{version}/{resource}

API 版本： v1.0（生产）或 beta（预览）
身份验证： 通过 Azure AD 使用 OAuth 2.0
数据格式： JSON

何时加载哪种资源

任务	服务	加载资源
设置身份验证、注册应用、管理凭据	应用与身份验证	resources/authentication-apps.md
管理用户、组、组织和目录	标识与访问	resources/identity-access.md
电子邮件、文件夹、附件、规则和签名	邮件操作	resources/mail-operations.md
日历、事件、日程安排、会议、空闲/忙碌状态	日历与日程安排	resources/calendar-scheduling.md
上传文件、文件夹、共享、OneDrive、SharePoint	文件与存储	resources/files-storage.md
Teams、频道、聊天、状态、在线会议	Teams 与通信	resources/teams-communications.md
Planner 任务、To Do 列表、OneNote 笔记本	规划与笔记	resources/planning-notes.md
安全警报、合规性、设备管理、报告	安全与治理	resources/security-governance.md

编排协议

阶段 1：分析任务

回答以下问题，确定所需的服务领域：

• 什么资源？（用户、文件、消息、事件等）
• 执行什么操作？（读取、创建、更新、删除）
• 由谁操作？（已登录用户或服务帐户）
• 需要哪些权限？（委托权限或应用程序权限）

阶段 2：加载正确的资源

使用上方的决策表找到对应的资源文件。每个资源都包括：

• 含基路径的完整终结点参考
• 所有 CRUD 操作的请求/响应示例
• 查询参数和筛选选项
• 所需权限（委托权限和应用程序权限）
• 错误处理模式和最佳实践
• 常见工作流和模式

阶段 3：放心实施

每个资源都提供针对你使用场景的实用示例，可直接复制粘贴。

通用 Graph 概念

标准查询参数：

$select=prop1,prop2              Choose properties to return
$filter=startsWith(name,'A')     Filter results by condition
$orderby=name desc               Sort results (asc or desc)
$top=25                          Limit to 25 results (default 20)
$skip=50                         Skip first 50 results
$expand=members                  Include related/nested data
$count=true                      Include total count in response
$search="keyword"                Full-text search across content

标准 CRUD 操作：

GET /me/messages?$select=subject&$top=10        # Read
POST /me/events {"subject": "Meeting", ...}     # Create
PATCH /users/{id} {"jobTitle": "Manager"}       # Update
DELETE /me/messages/{id}                        # Delete

分页： 始终根据响应中的 @odata.nextLink 获取完整数据集

批量请求： 使用 POST /$batch 将 1-20 个操作合并为单个调用

增量查询： 使用 GET /users/delta，通过 @odata.deltaLink 跟踪自上次查询以来的更改

错误响应格式：

{"error": {"code": "Code", "message": "Description"}}

常见状态码：

• 200/201/204：成功
• 400：请求无效
• 401：需要身份验证
• 403：权限不足
• 404：未找到资源
• 429：请求受限（检查 Retry-After 标头）
• 500-503：服务器错误（实施指数退避）

资源文件索引

文件	重点	行数
authentication-apps.md	应用注册、OAuth、凭据	350+
identity-access.md	用户、组、组织、目录	350+
mail-operations.md	电子邮件、文件夹、附件、规则	400+
calendar-scheduling.md	事件、定期活动、会议、空闲/忙碌状态	350+
files-storage.md	OneDrive、SharePoint、上传、共享	400+
teams-communications.md	Teams、频道、聊天、状态	350+
planning-notes.md	Planner、To Do、OneNote	350+
security-governance.md	安全、合规、设备、报告	400+

最佳实践

性能： 使用 $select 获取指定属性，实现分页，缓存令牌，批量操作时使用批处理，在同步场景中应用增量查询

安全： 安全存储令牌（切勿将其写入代码），申请最小权限，Azure 中使用托管身份，每 90 天轮换凭据，验证所有响应

开发： 先在 beta 终结点中测试，关注弃用通知，实现指数退避重试，遵守速率限制，检查 Graph 健康状态

故障排查：

• 401 Unauthorized → 检查令牌有效性和作用域
• 403 Forbidden → 确认已在 Azure AD 中配置权限
• 404 Not Found → 确认资源 ID 正确且资源存在
• 429 Too Many Requests → 实现指数退避重试

工具和 SDK 资源

交互式测试： Graph Explorer：https://developer.microsoft.com/graph/graph-explorer

SDK：

• .NET：Microsoft.Graph NuGet
• JavaScript/TypeScript：@microsoft/microsoft-graph-client npm
• Python：msgraph-sdk-python pip

文档：

• API 参考：https://docs.microsoft.com/graph/api/overview
• 权限参考：https://docs.microsoft.com/graph/permissions-reference
• 更新日志：https://docs.microsoft.com/graph/changelog

---

技能版本： 2.1 | API 版本： v1.0（正式版），beta（预览版） | 更新日期： 2025 年 12 月