# Microsoft Graph 代理技能搜索、查找和调用 27,700 多个 Microsoft Graph API 中的任何一个 - 全部在本地进行，无需网络调用。使用三个搜索命令查找正确的端点，检查权限和参数，然后选择直接执行调用或移交给 Graph MCP 服务器。 ## 包含什么 Microsoft Graph API 有 **27,700 多个端点**，每周更新 — 远远超过了 LLM 培训截止日期。此技能将完整的 API 表面捆绑为本地索引，您无需网络调用即可立即搜索。索引 |计数 |它包含什么 ---|---|--- OpenAPI 端点 | 27,700+ |路径、方法、摘要、描述、权限范围端点文档 | 6,200+ |权限（委托/应用程序）、查询参数、所需标头、默认属性与仅“$select”属性资源模式| 4,200+ |所有具有类型的属性、支持的“$filter”运算符、默认/仅选择标志社区样本|成长|手工验证的查询将自然语言任务映射到精确的 API 调用 ## 如何运行 “msgraph” CLI 与此技能捆绑在一起。通过此技能目录中的启动器脚本运行所有命令： * **macOS / Linux** : `bash <此技能的路径>/scripts/run.sh <命令> [参数...]` * **Windows** ：`powershell <此技能的路径>/scripts/run.ps1 <命令> [参数...]` 例如，要在 macOS 上搜索与邮件相关的 API： bash /home/user/.opencode/skills/msgraph/scripts/run.sh openapi-search --query“发送邮件” 在下面的所有示例中，“msgraph”是完整启动器调用的简写。 ## 寻找正确的 API 这是该技能的主要目的。遵循这种渐进式查找策略 - 每个级别都会添加细节： 1. **您自己的知识** - 首先尝试众所周知的端点（`/me`、`/users`、`/groups`）。 2. **`样本搜索`** — 精心策划的、手工验证的样本。最高品质。用于常见任务和多步骤工作流程。 3. **`api-docs-search`** — 每个端点权限、支持的查询参数、必需的标头、默认属性与仅“$select”属性以及带有过滤器运算符的资源属性详细信息。 4. **`openapi-search`** — 27,700 个图形 API 的完整目录。当您无法通过其他方式找到端点时使用。 5. **参考文件** — 有关查询参数、高级查询、分页、批处理、限制、错误和最佳实践的概念文档。仅当您需要具体指导时才阅读。该命令是指导——根据任务进行调整。例如，如果您已经知道端点但需要其权限，请直接跳转到“api-docs-search”。 ### 样本搜索搜索将自然语言任务映射到精确的 Microsoft Graph API 查询的精选社区示例： msgraph 示例搜索 --query“条件访问策略” msgraph 示例搜索 --product entra msgraph 示例搜索 --query "托管设备" --product intune 旗帜|描述 ---|--- `--查询` |自由文本搜索（搜索意图和查询字段） `--产品` |按产品过滤：“entra”、“intune”、“exchange”、“teams”、“sharepoint”、“security”、“general” `--限制` |最大结果（默认 10）至少需要“--query”或“--product”之一。结果包括多步骤工作流程。 ### api 文档搜索查找特定端点或资源类型的详细文档： msgraph api-docs-search --endpoint /users --method GET msgraph api-docs-search --资源用户 msgraph api-docs-search --query“ConsistencyLevel” 旗帜|描述 ---|--- `--端点` |按端点路径搜索（例如“/users”、“/me/messages”） `--资源` |按资源类型名称搜索（例如“用户”、“组”、“消息”） `--方法` |按 HTTP 方法过滤：`GET`、`POST`、`PUT`、`PATCH` `--查询` |跨所有领域的自由文本搜索 `--限制` |最大结果（默认 10）至少需要“--endpoint”、“--resource”或“--query”之一。 **端点结果**包括：所需的权限（委派的工作/学校、委派的个人、应用程序）、支持的 OData 查询参数、所需的标头、默认属性和端点特定的注释。 **资源结果**包括：所有具有类型的属性、支持的 `$filter` 运算符（eq、ne、startsWith 等），以及每个属性是否默认返回或需要 `$select`。 ### openapi-搜索搜索包含 27,700 个 Microsoft Graph API 的完整 OpenAPI 目录： msgraph openapi-search --query“发送邮件” msgraph openapi-search --资源消息 --method GET 旗帜|描述 ---|--- `--查询` |自由文本搜索（搜索路径、摘要、描述） `--资源` |按资源名称过滤（例如“用户”、“组”、“消息”） `--方法` |按 HTTP 方法过滤 `--限制` |最大结果（默认 20）至少需要 `--query`、`--resource` 或 `--method` 之一。 ## 与 MCP 服务器一起使用如果代理有权访问 Microsoft Graph MCP 服务器（例如 [lokka.dev]() 或任何其他 Microsoft Graph MCP 服务器），请使用上面的搜索工具查找正确的终结点、权限和请求语法，然后将这些信息与 MCP 服务器一起使用来执行。在此模式下，**不需要通过此技能进行身份验证**。该技能纯粹充当知识层——MCP 服务器处理身份验证和 API 执行。 ## 直接 Microsoft Graph API 执行当没有可用的 Graph MCP 服务器时，此技能可以向 Microsoft 365 进行身份验证并直接执行 Microsoft Graph API 调用。 ### 身份验证该工具支持**委托（用户）**和**仅应用程序（应用程序）**身份验证，从环境变量中自动检测。 **快速启动：** msgraph auth status # 检查是否登录 msgraph auth signin # 登录（打开浏览器）- 推荐 msgraph auth signin --device-code # 通过设备代码登录（无头） msgraph auth signout # 清除会话 * **委派身份验证**（默认）：交互式浏览器登录，为无头环境提供设备代码回退。支持增量同意 - 在 403 上，该工具会使用所需的范围重新进行身份验证并自动重试。 * **仅应用程序身份验证**：设置“MSGRAPH_CLIENT_SECRET”、“MSGRAPH_CLIENT_CERTIFICATE_PATH”、“MSGRAPH_FEDERATED_TOKEN_FILE”或“MSGRAPH_AUTH_METHOD=托管身份”时自动检测。需要“MSGRAPH_TENANT_ID”。有关详细的身份验证配置，包括证书、托管身份、工作负载身份联合和所有环境变量，请参阅 [references/docs/authentication.md]()。 ### 进行图形 API 调用 **重要**：在会话中第一个“graph-call”之前运行“msgraph auth status”以验证身份验证。 msgraph graph-call <方法> [标志] #### 读操作 msgraph 图形调用 GET /me msgraph graph-call GET /users --select "displayName,mail" --top 10 msgraph graph-call GET /me/messages --filter "isRead eq false" --top 5 --select "subject,from,receivedDateTime" msgraph graph-call GET /users --filter "startsWith(displayName,'John')" #### 写操作 **重要**：在进行任何写入操作之前，您必须要求用户确认。写操作需要“--allow-writes”标志。 msgraph graph-call POST /me/sendMail --body '{"message":{"subject":"Hello","body":{"content":"Hi"},"toRecipients":[{"emailAddress":{"address":"user@example.com"}}]}}' --allow-writes msgraph graph-call PATCH /me --body '{"jobTitle":"Engineer"}' --allow-writes **删除始终被阻止**，无论标志如何。 #### 图形调用标志旗帜|描述 |示例 ---|---|--- `--选择` | OData $选择| `--选择“显示名称，邮件”` `--过滤器` | OData $过滤器| `--filter "isRead eq false"` `--顶部` | OData $top（限制结果）| `--前10名` `--展开` | OData $展开 | `--展开“成员”` `--orderby` | OData $orderby | OData `--orderby "displayName desc"` `--api-版本` | `v1.0` 或 `beta` （默认：beta） | `--api-版本 v1.0` `--范围` |请求额外的权限范围 | `--范围“Mail.Read”` `--headers` |自定义 HTTP 标头 | `--headers "ConsistencyLevel:eventual"` `--body` |请求正文 (JSON) | `--body '{"key":"value"}'` `--输出` | `json` （默认）或 `raw` | `--输出原始数据` `--允许写入` |允许 POST/PUT/PATCH（需要用户确认）| ## 关键规则 ### 始终（搜索和知识） 1. **永远不要猜测或伪造 Microsoft Graph 端点** - 在调用之前始终通过搜索进行验证。这项技能的存在是因为智能体会产生端点幻觉。使用它。 2. **使用渐进式查找策略** — 从您所知道的开始，然后根据需要进行示例搜索、api-docs-search、openapi-search。 3. **使用`--select`**来减少响应大小——仅请求您需要的字段。 4. **使用`--top`**来限制结果——避免获取数千条记录。 5. **ConsistencyLevel 标头** 对于目录对象（用户、组等）上的 `$count` 和 `$search` 是必需的。使用 `--headers "ConsistencyLevel:eventual"`。 6. **默认 API 版本是 beta** — 使用 `--api-version v1.0` 作为生产稳定端点。 ### 使用直接执行（图形调用）时 7. **在会话中的第一个“图形调用”之前检查身份验证状态**。 8. **GET 是默认设置** — 不需要特殊标志。 9. **写操作需要`--allow-writes`** — 您必须首先与用户确认。 10. **DELETE 始终被阻止** — 通知用户不支持此操作。 11. **403 触发自动重新身份验证** — 该工具请求额外的范围并重试（仅限委托身份验证）。 12. **所有输出均为 JSON** — 解析响应中的 `statusCode` 和 `body` 字段。 ## 错误处理状态 |意义|行动 ---|---|--- 401 | 401令牌已过期 |再次运行“msgraph auth Signin” 403 | 403权限不足|工具在增量同意的情况下自动重试。如果仍然失败，用户需要管理员同意。 404 | 404找不到资源 |验证端点路径 429 | 429限价|等待重试-持续一段时间后，然后重试 ## 环境变量变量|描述 |默认 ---|---|--- `MSGRAPH_CLIENT_ID` |自定义 Entra ID 应用程序客户端 ID | Microsoft Graph CLI 工具应用程序 `MSGRAPH_TENANT_ID` |目标租户 ID（仅应用程序需要）| `常见` `MSGRAPH_API_VERSION` |默认API版本| `测试版` `MSGRAPH_INDEX_DB_PATH` | OpenAPI 索引数据库路径 |自动检测 `MSGRAPH_SAMPLES_DB_PATH` |样本索引数据库的路径 |自动检测 `MSGRAPH_API_DOCS_DB_PATH` | API 文档索引数据库的路径 |自动检测 `MSGRAPH_NO_TOKEN_CACHE` |禁用持久令牌缓存（仅限内存中）| `假` 有关身份验证环境变量的完整列表，请参阅 [references/docs/authentication.md]()。 ## 兼容性搜索工具完全离线运行，无需网络访问。直接 API 执行需要网络访问“login.microsoftonline.com”和“graph.microsoft.com”。使用系统浏览器进行交互式验证；在无头环境中回退到设备代码流。 ## 参考文件当您需要具体指导时，按需加载这些内容。不要抢先加载它们。文件|何时阅读 |尺寸 ---|---|--- [参考文献/REFERENCE.md]() |常见资源路径、OData 模式、权限范围 |约 230 行 [references/docs/authentication.md]() |详细的身份验证配置：证书、托管身份、工作负载身份、所有环境变量 |约 200 行 [references/docs/query-parameters.md]() | OData $select、$filter、$expand、$top、$orderby、$search 语法和陷阱 |约 300 行 [references/docs/advanced-queries.md]() |目录对象上的 ConsistencyLevel 标头、$count、$search、ne/not/endsWith ~190 行 [references/docs/paging.md]() | @odata.nextLink 分页，服务器端与客户端分页 |约 50 行 [references/docs/batching.md]() | $batch 端点，组合多个请求，取决于排序 |约 280 行 [references/docs/throtdling.md]() | 429 处理、Retry-After、退避策略 | ~90 行 [references/docs/errors.md]() | HTTP状态码、错误响应格式、错误代码 | ~105 行 [references/docs/best-practices.md]() | $select 用于性能、分页、增量查询、批处理 |约 155 行

图形图表

包含技能