microsoft-graph

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Microsoft Graph API Orchestration Skill

Microsoft Graph API编排技能

Microsoft Graph is a unified REST API endpoint for accessing Microsoft Cloud resources across Microsoft 365, Windows, and Enterprise Mobility + Security. Base URL:

https://graph.microsoft.com/{version}/{resource}

API Versions:

v1.0

(production) or

beta

(preview)
Authentication: OAuth 2.0 via Azure AD
Data Format: JSON

Microsoft Graph是一个统一的REST API端点，用于访问Microsoft 365、Windows和Enterprise Mobility + Security中的微软云资源。基础URL：

https://graph.microsoft.com/{version}/{resource}

API版本：

v1.0

（正式版）或

beta

（预览版）
身份验证： 通过Azure AD使用OAuth 2.0
数据格式： JSON

When to Load Which Resource

何时加载对应资源

Task	Service	Load Resource
Setup auth, register apps, manage credentials	Applications & Auth	resources/authentication-apps.md
Manage users, groups, organization, directory	Identity & Access	resources/identity-access.md
Email, folders, attachments, rules, signatures	Mail Operations	resources/mail-operations.md
Calendar, events, scheduling, meetings, free/busy	Calendar & Scheduling	resources/calendar-scheduling.md
Upload files, folders, share, OneDrive, SharePoint	Files & Storage	resources/files-storage.md
Teams, channels, chats, presence, online meetings	Teams & Communications	resources/teams-communications.md
Planner tasks, To Do lists, OneNote notebooks	Planning & Notes	resources/planning-notes.md
Security alerts, compliance, device management, reports	Security & Governance	resources/security-governance.md

任务	服务	加载资源
设置身份验证、注册应用、管理凭据	应用与身份验证	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任务、待办事项列表、OneNote笔记本	规划与笔记	resources/planning-notes.md
安全警报、合规性、设备管理、报告	安全与治理	resources/security-governance.md

Orchestration Protocol

编排流程

Phase 1: Analyze Your Task

阶段1：分析你的任务

Identify which service area you need by answering:

What resource? (users, files, messages, events, etc.)
What action? (read, create, update, delete)
Who? (signed-in user or service account)
Permissions? (delegated or application)

通过回答以下问题确定你需要的服务领域：

需要什么资源？（用户、文件、消息、事件等）
执行什么操作？（读取、创建、更新、删除）
操作主体是谁？（已登录用户或服务账户）
需要什么权限？（委托权限或应用权限）

Phase 2: Load the Right Resource

阶段2：加载正确的资源

Use the decision table above to find your resource file. Each resource includes:

Complete endpoint reference with base paths
Request/response examples for all CRUD operations
Query parameters and filter options
Required permissions (delegated and application)
Error handling patterns and best practices
Common workflows and patterns

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

带基础路径的完整端点参考
所有CRUD操作的请求/响应示例
查询参数与过滤选项
所需权限（委托权限与应用权限）
错误处理模式与最佳实践
常见工作流与模式

Phase 3: Implement with Confidence

阶段3：放心实现

Each resource shows practical, copy-paste-ready examples for your use case.

每个资源文件都提供了适用于你的场景的实用、可直接复制粘贴的示例。

Universal Graph Concepts

Graph通用概念

Standard Query Parameters:

$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

Standard CRUD Operations:

http

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

Pagination: Always follow

@odata.nextLink

in responses for complete data sets

Batch Requests: Use

POST /$batch

to combine 1-20 operations into single call

Delta Queries: Use

GET /users/delta

to track changes since last query via

@odata.deltaLink

Error Response Format:

json

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

Common Status Codes:

200/201/204: Success
400: Invalid request
401: Authentication required
403: Insufficient permissions
404: Resource not found
429: Rate limited (check Retry-After header)
500-503: Server error (implement exponential backoff)

标准查询参数：

$select=prop1,prop2              选择要返回的属性
$filter=startsWith(name,'A')     按条件过滤结果
$orderby=name desc               对结果排序（升序或降序）
$top=25                          限制返回25条结果（默认20条）
$skip=50                         跳过前50条结果
$expand=members                  包含关联/嵌套数据
$count=true                      在响应中包含总计数
$search="keyword"                对内容进行全文搜索

标准CRUD操作：

http

GET /me/messages?$select=subject&$top=10        # 读取
POST /me/events {"subject": "Meeting", ...}     # 创建
PATCH /users/{id} {"jobTitle": "Manager"}       # 更新
DELETE /me/messages/{id}                        # 删除

分页： 始终遵循响应中的

@odata.nextLink

以获取完整数据集

批量请求： 使用

POST /$batch

将1-20个操作合并为单个调用

增量查询： 使用

GET /users/delta

通过

@odata.deltaLink

跟踪自上次查询以来的变更

错误响应格式：

json

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

常见状态码：

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

Resource File Index

资源文件索引

File	Focus	Lines
authentication-apps.md	App registration, OAuth, credentials	350+
identity-access.md	Users, groups, organization, directory	350+
mail-operations.md	Email, folders, attachments, rules	400+
calendar-scheduling.md	Events, recurring, meetings, free/busy	350+
files-storage.md	OneDrive, SharePoint, uploads, sharing	400+
teams-communications.md	Teams, channels, chats, presence	350+
planning-notes.md	Planner, To Do, OneNote	350+
security-governance.md	Security, compliance, devices, reports	400+

文件	重点	行数
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、待办事项、OneNote	350+
security-governance.md	安全、合规性、设备、报告	400+

Best Practices

最佳实践

Performance: Use

$select

for specific properties, implement pagination, cache tokens, use batch for bulk ops, apply delta queries for sync scenarios

Security: Store tokens securely (never in code), request least-privilege permissions, use managed identities for Azure, rotate credentials every 90 days, validate all responses

Development: Test in

beta

endpoint first, monitor deprecation notices, implement exponential backoff for retries, respect rate limiting, check Graph health status

Troubleshooting:

401 Unauthorized → Check token validity and scopes
403 Forbidden → Verify permissions are configured in Azure AD
404 Not Found → Verify resource ID and that resource exists
429 Too Many Requests → Implement retry with exponential backoff

性能： 使用

$select

获取特定属性，实现分页，缓存令牌，使用批量处理进行批量操作，在同步场景中使用增量查询

安全： 安全存储令牌（绝不要存放在代码中），请求最小权限，为Azure使用托管标识，每90天轮换凭据，验证所有响应

开发： 先在

beta

端点测试，监控弃用通知，实现指数退避重试，遵守速率限制，检查Graph健康状态

故障排除：

401 未授权 → 检查令牌有效性和范围
403 禁止访问 → 验证Azure AD中是否配置了权限
404 未找到 → 验证资源ID和资源是否存在
429 请求过多 → 实现带指数退避的重试

Tools & SDK Resources

工具与SDK资源

Interactive Testing: Graph Explorer at https://developer.microsoft.com/graph/graph-explorer

SDKs:

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

Documentation:

API Reference: https://docs.microsoft.com/graph/api/overview
Permissions Reference: https://docs.microsoft.com/graph/permissions-reference
Changelog: https://docs.microsoft.com/graph/changelog

Skill Version: 2.1 | API Versions: v1.0 (production), beta (preview) | Updated: December 2025

交互式测试： 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月