1. 为什么 Microsoft Graph Explorer 值得每个 Azure 开发者花时间掌握做 Microsoft 365 或 Azure 相关开发的朋友大概率都经历过这样的场景想调一个 Graph API 拿用户列表结果卡在权限配置上或者 Token 拿到了但请求发出去返回 401完全不知道是 Scope 不对还是 Consent 没做。更让人头疼的是有时候只是想快速验证一个接口返回的数据结构长什么样却要写一堆认证代码、配 App Registration、处理 Token 刷新折腾半小时就为了看一眼 JSON 响应。Microsoft Graph Explorer 就是来解决这类问题的。它是一个基于浏览器的交互式工具让你不需要写任何代码就能直接对 Microsoft Graph API 发起请求、查看响应、调试权限。你可以把它理解成 Postman 的 Graph 专用版——但比 Postman 更懂 Graph 的认证体系和权限模型因为它本身就是微软官方提供的。这篇文章适合三类人看第一类是刚接触 Microsoft Graph 的开发者想快速理解 Graph API 的调用方式和权限机制第二类是已经在用 Graph API 但调试效率不高的工程师想找一个更顺手的调试工具第三类是做 Azure AD / Entra ID 集成方案的架构师需要快速验证各种 API 场景的可行性。不管你属于哪一类下面这些内容都是我实际用下来觉得最有价值的部分。2. Microsoft Graph Explorer 到底是什么它能帮你解决哪些实际问题2.1 一句话说清楚它的定位Microsoft Graph Explorer 是微软官方提供的一个 Web 端工具地址是 developer.microsoft.com/graph/graph-explorer。打开浏览器就能用不需要安装任何东西。它的核心能力是让你用当前登录的账号身份直接向 Microsoft Graph API 发送 HTTP 请求并实时查看返回结果。听起来好像很简单但它的价值远不止“发请求看响应”这么表面。它内置了几个非常关键的能力自动处理 OAuth 2.0 认证流程、可视化展示所需权限Scopes、提供大量预置的示例查询、支持切换 HTTP 方法GET/POST/PATCH/DELETE、支持自定义请求头和请求体。这些能力组合在一起就构成了一个完整的 Graph API 调试环境。2.2 它和 Postman、curl 的本质区别在哪很多人会问我用 Postman 也能调 Graph API为什么要用 Graph Explorer这个问题我一开始也想过但实际用下来发现差异很大。Postman 调 Graph API 的流程是你得先去 Azure Portal 注册一个 App、配置 API 权限、生成 Client Secret、用各种方式获取 Token、把 Token 粘贴到 Postman 的 Authorization 头里、然后才能发请求。Token 过期了还得重新获取。整个过程繁琐且容易出错。Graph Explorer 的流程是打开网页、登录账号、点一下“同意权限”、直接发请求。它帮你把 OAuth 流程全部封装好了你不需要关心 Token 是怎么来的、怎么刷新的。更重要的是它会根据你要调的 API 自动告诉你需要哪些权限并且引导你完成管理员同意Admin Consent流程。还有一个关键差异Graph Explorer 内置了权限不足时的提示和修复引导。比如你调/users接口返回 403它会直接告诉你缺少User.Read.All权限并提供一个按钮让你去同意这个权限。Postman 不会给你这些提示你只能自己去查文档。2.3 典型使用场景盘点我整理了几个自己最常用的场景基本上覆盖了日常开发中 80% 的调试需求快速验证 API 返回结构在写代码之前先用 Graph Explorer 调一下接口看看返回的 JSON 字段名、嵌套结构、分页方式这样写代码时心里有底。调试权限问题当代码里调用 Graph API 报 403 时用 Graph Explorer 用同样的账号调同一个接口如果也报 403说明是权限配置问题如果不报错说明是代码里的认证流程有问题。测试批量操作比如批量创建用户、批量添加组成员可以先用 Graph Explorer 测试请求体格式是否正确。验证筛选和查询参数Graph API 支持$filter、$select、$expand、$search等 OData 查询参数用 Graph Explorer 可以快速测试各种参数组合的效果。学习和探索 APIGraph Explorer 提供了大量示例查询按场景分类用户、组、邮件、日历、Teams 等是学习 Graph API 最好的入口之一。注意Graph Explorer 默认使用的是微软提供的演示租户数据但你也可以切换到自己的租户。演示租户的数据是只读的适合学习和测试查询要测试写操作POST/PATCH/DELETE必须登录自己的租户。3. 核心功能拆解与实操要点3.1 界面布局与关键区域说明第一次打开 Graph Explorer界面看起来元素不少但核心区域就几个顶部栏左侧是 Microsoft Graph Explorer 的 Logo右侧显示当前登录的账号信息。如果你没登录会显示“Sign in to Graph Explorer”按钮。左侧面板分为两个 Tab——“Sample queries”和“Resources”。Sample queries 是预置的示例查询按场景分类Resources 是 API 文档的快捷入口。中间请求区这是最核心的区域。包含 HTTP 方法选择器GET/POST/PATCH/DELETE、URL 输入框、请求头编辑区Request headers、请求体编辑区Request body仅 POST/PATCH 时显示。右侧响应区显示 API 返回的响应。包含 Response preview格式化后的 JSON、Response headers响应头、HTTP status code状态码。权限面板在请求区上方有一个“Modify permissions”标签点开后会显示当前请求所需的权限列表以及你当前是否已经同意这些权限。3.2 认证机制它到底帮你做了什么Graph Explorer 的认证机制值得单独拿出来说因为这是它最核心的便利性来源。当你第一次登录 Graph Explorer 时它会引导你完成一次 OAuth 2.0 授权码流程。具体来说它使用的是一个微软预注册的公共客户端应用Public Client你登录后它会拿到一个 Access Token后续所有 API 请求都用这个 Token 来认证。关键点在于这个 Token 的权限范围Scopes是动态的。当你发起一个请求时Graph Explorer 会分析这个请求需要哪些权限然后检查你当前 Token 是否包含这些权限。如果不包含它会提示你去同意。你点击“Consent”按钮后会跳转到微软的权限同意页面同意后 Token 会被刷新包含新的权限。这个过程完全自动化你不需要手动构造授权 URL、不需要处理回调、不需要管理 Token 生命周期。对于调试来说这省掉了大量时间。实操心得Graph Explorer 拿到的 Token 默认有效期大约 1 小时。如果你调试时间较长Token 过期后会收到 401 错误此时刷新页面重新登录即可。另外如果你切换了登录账号之前同意的权限不会自动继承需要重新同意。3.3 示例查询的使用技巧Graph Explorer 的 Sample queries 是我用得最多的功能之一。它按类别组织包括类别典型示例适用场景Users获取我的信息、列出所有用户、创建用户用户管理开发Groups列出所有组、获取组成员、添加成员组管理开发Mail获取我的邮件、发送邮件、搜索邮件邮件集成开发Calendar获取我的日历事件、创建事件日历集成开发Teams列出所有团队、获取频道消息Teams 开发Security获取安全警报、条件访问策略安全合规开发每个示例查询都预填了 URL、HTTP 方法和请求体如果有的话。你只需要点击一下然后点“Run query”就能执行。执行后右侧会显示响应结果同时权限面板会显示这个查询需要哪些权限。我通常的做法是先找一个最接近我需求的示例查询运行一遍看看返回结构然后在此基础上修改 URL 参数或请求体逐步调整到我要的效果。这比从零开始构造请求快得多。3.4 权限管理与 Consent 流程权限是 Graph API 开发中最容易踩坑的地方Graph Explorer 在这方面提供了很好的支持。当你运行一个查询时如果当前 Token 缺少所需权限响应区会返回 403 Forbidden同时在权限面板中会高亮显示缺少的权限。你可以点击“Consent”按钮跳转到权限同意页面。同意后Graph Explorer 会重新获取 Token你再运行一次查询就能成功了。这里有一个很重要的细节有些权限需要管理员同意Admin Consent普通用户无法自行同意。比如User.Read.All这种读取所有用户信息的权限通常需要管理员在 Entra ID 中授予。如果你用普通账号登录点击 Consent 后可能会提示“需要管理员批准”。这种情况下你需要联系租户管理员让他在 Entra ID 的企业应用中找到 Graph Explorer 并授予相应权限。注意Graph Explorer 在生产租户中使用时它同意的权限是绑定到你的账号的。也就是说你通过 Graph Explorer 同意的权限不会影响其他用户也不会影响你自己的代码应用。它只是一个调试工具权限范围仅限于你在 Graph Explorer 中的操作。4. 完整实操流程从零开始调通一个 Graph API4.1 场景设定与准备工作假设我们现在有一个需求需要获取当前租户中所有用户的列表并且只返回每个用户的显示名称、邮箱和部门信息。这个需求在实际开发中很常见比如做员工目录同步、组织架构展示等。在开始之前你需要准备一个 Microsoft 365 开发者账号或企业账号如果没有可以申请 Microsoft 365 Developer Program 的免费沙箱一个浏览器Edge 或 Chrome 都可以确认你的账号有读取用户信息的权限普通用户默认可以读取自己的信息读取所有用户需要额外权限4.2 第一步登录并熟悉环境打开浏览器访问 Graph Explorer。点击右上角的“Sign in”按钮用你的 Microsoft 365 账号登录。登录成功后你会看到右上角显示你的账号名称。此时中间请求区默认已经填好了一个 GET 请求https://graph.microsoft.com/v1.0/me。这个接口返回当前登录用户的信息。直接点击“Run query”按钮右侧应该会返回你的用户信息 JSON。这一步的目的是确认认证流程正常。如果这一步就报错说明登录环节有问题需要检查账号状态或浏览器 Cookie 设置。4.3 第二步构造目标请求现在我们要获取所有用户列表。把 URL 从/me改成/usersHTTP 方法保持 GET。点击“Run query”。如果一切顺利你会看到返回了一个包含多个用户对象的 JSON 数组。但默认返回的字段很多包含 id、displayName、mail、department、jobTitle、officeLocation 等等。我们只需要 displayName、mail 和 department 三个字段。这时候就需要用到 OData 的$select参数。把 URL 改成https://graph.microsoft.com/v1.0/users?$selectdisplayName,mail,department再次运行返回的 JSON 中就只包含这三个字段了。响应体积会小很多对于大量数据的场景这个优化很有意义。4.4 第三步处理分页问题Graph API 对返回结果有分页限制默认每页最多返回 100 条记录不同接口可能不同。如果你的租户用户数超过 100返回的 JSON 中会包含一个odata.nextLink字段里面是下一页的 URL。在 Graph Explorer 中你可以直接复制这个 nextLink 的 URL粘贴到请求框中继续请求下一页。但更高效的方式是使用$top参数来控制每页数量或者使用$counttrue来获取总数。比如https://graph.microsoft.com/v1.0/users?$selectdisplayName,mail,department$top999$counttrue$top999表示每页最多返回 999 条实际最大值因接口而异$counttrue会在响应中额外返回一个odata.count字段告诉你总共有多少条记录。实操心得$top的值不是越大越好。设置过大的值可能导致请求超时特别是在网络状况不佳的情况下。我通常设置为 200-500 之间兼顾效率和稳定性。另外$counttrue需要额外的权限通常是User.Read.All如果报 403先去掉这个参数试试。4.5 第四步测试筛选和排序假设我们只想获取部门为“工程部”的用户可以使用$filter参数https://graph.microsoft.com/v1.0/users?$selectdisplayName,mail,department$filterdepartment eq 工程部如果想按显示名称排序https://graph.microsoft.com/v1.0/users?$selectdisplayName,mail,department$orderbydisplayName asc$filter和$orderby可以组合使用但要注意顺序$filter在前$orderby在后。另外不是所有字段都支持筛选和排序具体支持情况需要查阅 Microsoft Graph 的文档。Graph Explorer 的 Resources 面板可以直接跳转到对应接口的文档页面。4.6 第五步测试写操作前面都是 GET 请求现在测试一个 POST 请求。假设我们要创建一个新的用户。把 HTTP 方法改成 POSTURL 保持/users然后在 Request body 中填入{ accountEnabled: true, displayName: 测试用户, mailNickname: testuser, userPrincipalName: testuseryourtenant.onmicrosoft.com, passwordProfile: { forceChangePasswordNextSignIn: true, password: TempPassword123! } }点击“Run query”。如果权限足够会返回 201 Created 和创建成功的用户信息。如果权限不足会返回 403并在权限面板提示需要User.ReadWrite.All权限。这里有一个很重要的注意事项创建用户需要User.ReadWrite.All权限这个权限通常需要管理员同意。而且创建用户是一个写操作会在你的租户中产生真实数据。如果你只是测试记得创建后把用户删除避免留下垃圾数据。注意Graph Explorer 中的写操作是真实生效的不是模拟环境。所以在生产租户中操作时一定要谨慎建议先在测试租户中验证。5. 常见问题与排查技巧实录5.1 认证类问题问题一登录后仍然返回 401 Unauthorized这种情况通常有几个原因Token 过期、浏览器缓存问题、或者账号被限制。首先尝试刷新页面重新登录。如果还不行清除浏览器中 graph.microsoft.com 相关的 Cookie 和本地存储然后重新登录。如果问题依旧检查你的账号是否被条件访问策略限制比如要求 MFA 或特定网络环境。问题二Consent 后仍然返回 403 Forbidden可能的原因包括权限需要管理员同意但你用的是普通账号、权限同意有延迟、或者你请求的接口需要的是另一种权限。先检查权限面板中显示的所需权限是否已经全部打勾。如果有权限显示“Requires admin consent”你需要联系管理员。另外有些接口的权限要求比较特殊比如/users/{id}/messages需要Mail.Read或Mail.ReadBasic而不是User.Read.All。问题三切换账号后权限丢失Graph Explorer 的权限是绑定到账号的。切换账号后之前同意的权限不会自动转移。你需要用新账号重新执行 Consent 流程。这是预期行为不是 Bug。5.2 请求类问题问题四$filter 报错“Invalid filter clause”Graph API 的$filter语法遵循 OData 规范但有一些限制。常见错误包括字符串值没有用单引号包裹、使用了不支持的运算符、字段名拼写错误。比如department eq 工程部是正确的department 工程部是错误的Graph 用eq而不是。另外不是所有字段都支持$filter比如mail字段在某些接口中不支持筛选。问题五$expand 返回的数据不完整$expand用于展开导航属性比如获取用户的同时获取他的经理信息/users?$expandmanager。但$expand默认只返回展开对象的部分字段。如果需要指定字段可以使用嵌套的$select/users?$expandmanager($selectdisplayName,mail)。注意嵌套$select的语法括号和字段名之间不能有空格。问题六请求体格式正确但返回 400 Bad Request这种情况通常是请求体中的某个字段值不符合要求。比如创建用户时userPrincipalName必须包含域名、passwordProfile.password必须满足复杂度要求、mailNickname不能包含特殊字符。Graph Explorer 的响应区会返回详细的错误信息仔细阅读error.message字段通常能找到原因。5.3 性能与限制类问题问题七请求超时或响应很慢Graph API 对请求频率有限制Throttling。如果你短时间内发送大量请求会被限流返回 429 Too Many Requests。响应头中会包含Retry-After字段告诉你多少秒后可以重试。在 Graph Explorer 中调试时一般不会触发限流但如果你在批量测试需要注意控制频率。问题八返回的数据量太大浏览器卡顿当返回大量数据时Graph Explorer 的响应区可能会变得很卡。这时候可以使用$select减少返回字段或者使用$top限制返回数量。另外Graph Explorer 的响应区有“Formatted”和“Raw”两种视图切换到 Raw 视图可以减少渲染开销。5.4 常见问题速查表问题现象可能原因解决方法401 UnauthorizedToken 过期或未登录刷新页面重新登录403 Forbidden缺少权限或需要管理员同意检查权限面板联系管理员400 Bad Request请求体格式或字段值错误查看 error.message 详细信息429 Too Many Requests请求频率过高被限流等待 Retry-After 秒后重试$filter 报错语法错误或字段不支持检查 OData 语法和字段支持情况返回数据不完整分页限制使用 odata.nextLink 或 $top写操作无效果权限不足或请求体错误确认权限并检查请求体实操心得Graph Explorer 的响应区有一个很实用的功能——它会显示请求的完整 cURL 命令。点击响应区上方的“Code snippets”标签可以选择不同语言的代码片段C#、JavaScript、PowerShell 等。这个功能在你调试成功后需要把请求迁移到代码中时特别有用直接复制对应的代码片段就行省去了手动翻译请求的过程。6. 进阶技巧把 Graph Explorer 用到极致6.1 利用 Code Snippets 加速开发前面提到了 Code Snippets 功能这里展开说一下。当你在 Graph Explorer 中调通一个请求后点击“Code snippets”标签可以看到这个请求在不同语言中的实现代码。支持的代码片段包括C# (Microsoft Graph SDK)JavaScript (Microsoft Graph SDK)PowerShell (Microsoft Graph SDK)Java (Microsoft Graph SDK)Go (Microsoft Graph SDK)PHP (Microsoft Graph SDK)Python (Microsoft Graph SDK)cURL这些代码片段是自动生成的包含了认证配置和请求构造。你可以直接复制到项目中替换掉认证部分的配置比如 Client ID、Tenant ID就能直接运行。这个功能对于快速搭建项目原型特别有用。6.2 使用 Graph Explorer 的 API 文档联动Graph Explorer 的 Resources 面板提供了 Microsoft Graph API 的完整文档入口。当你在调试某个接口时可以直接点击 Resources 中的对应链接跳转到该接口的官方文档页面。文档中包含了详细的参数说明、权限要求、返回结构、示例代码等信息。我通常的做法是在 Graph Explorer 中调试接口的同时打开对应的文档页面对照着看。这样既能快速验证又能深入理解接口的细节。6.3 批量测试与自动化思路Graph Explorer 本身是一个手动工具不支持自动化脚本。但你可以用它来验证请求格式然后用 Postman 或代码来实现批量自动化。具体思路是在 Graph Explorer 中调通单个请求确认 URL、请求头、请求体格式正确。使用 Code Snippets 生成对应语言的代码。在代码中实现循环或批量逻辑替换掉单个请求的参数。在测试环境中运行批量脚本验证效果。这个流程结合了 Graph Explorer 的便利性和代码的灵活性是我在实际项目中最常用的方式。6.4 权限最小化原则的实践在 Graph Explorer 中调试时很容易养成“什么权限都同意”的习惯因为这样最省事。但在实际开发中权限最小化是一个重要的安全原则。你申请的应用权限应该只包含实际需要的范围而不是一股脑全要。Graph Explorer 可以帮助你实践这个原则当你调试一个接口时权限面板会精确显示所需的最小权限集。你可以记录下来在 Azure Portal 中注册应用时只申请这些权限。这样既能满足功能需求又能降低安全风险。注意Graph Explorer 本身使用的权限范围可能比你实际应用需要的更宽。因为它是通用调试工具需要覆盖各种场景。所以在参考它的权限时要结合自己的实际需求做裁剪。7. 我个人在实际使用中的几点体会用了这么久的 Graph Explorer有几个感受比较深。第一它最大的价值不是“能调 API”而是“能快速告诉你缺什么权限”。Graph API 的权限体系非常复杂同一个接口在不同场景下可能需要不同的权限组合。Graph Explorer 的权限面板和 Consent 引导基本上把这个问题可视化了省去了大量查文档和试错的时间。第二它的示例查询质量很高。微软的文档团队显然在这上面花了不少心思示例覆盖了大部分常用场景而且每个示例都配有说明和预期结果。对于刚接触 Graph API 的开发者来说从示例查询入手学习比直接看文档效率高得多。第三它也有局限性。比如不支持环境变量、不支持请求集合管理、不支持自动化测试。所以它适合做“单次调试”和“学习探索”不适合做“持续集成”和“批量测试”。在实际项目中我通常是 Graph Explorer 和 Postman 配合使用Graph Explorer 用来快速验证和探索Postman 用来管理请求集合和做批量测试。最后分享一个小技巧如果你经常需要调试同一组 API可以把常用的请求 URL 保存在浏览器书签中。Graph Explorer 的 URL 是支持直接拼接请求路径的比如https://developer.microsoft.com/graph/graph-explorer?request/usersmethodGETversionv1.0。这样打开书签就能直接加载对应的请求省去手动输入的麻烦。 
长河君 · 2026/9/24 12:58:50 · 阅读 1.2k Microsoft Graph Explorer：Azure 开发者必备的 Graph API 调试工具
1. 为什么 Microsoft Graph Explorer 值得每个 Azure 开发者花时间掌握做 Microsoft 365 或 Azure 相关开发的朋友大概率都经历过这样的场景想调一个 Graph API 拿用户列表结果卡在权限配置上或者 Token 拿到了但请求发出去返回 401完全不知道是 Scope 不对还是 Consent 没做。更让人头疼的是有时候只是想快速验证一个接口返回的数据结构长什么样却要写一堆认证代码、配 App Registration、处理 Token 刷新折腾半小时就为了看一眼 JSON 响应。Microsoft Graph Explorer 就是来解决这类问题的。它是一个基于浏览器的交互式工具让你不需要写任何代码就能直接对 Microsoft Graph API 发起请求、查看响应、调试权限。你可以把它理解成 Postman 的 Graph 专用版——但比 Postman 更懂 Graph 的认证体系和权限模型因为它本身就是微软官方提供的。这篇文章适合三类人看第一类是刚接触 Microsoft Graph 的开发者想快速理解 Graph API 的调用方式和权限机制第二类是已经在用 Graph API 但调试效率不高的工程师想找一个更顺手的调试工具第三类是做 Azure AD / Entra ID 集成方案的架构师需要快速验证各种 API 场景的可行性。不管你属于哪一类下面这些内容都是我实际用下来觉得最有价值的部分。2. Microsoft Graph Explorer 到底是什么它能帮你解决哪些实际问题2.1 一句话说清楚它的定位Microsoft Graph Explorer 是微软官方提供的一个 Web 端工具地址是 developer.microsoft.com/graph/graph-explorer。打开浏览器就能用不需要安装任何东西。它的核心能力是让你用当前登录的账号身份直接向 Microsoft Graph API 发送 HTTP 请求并实时查看返回结果。听起来好像很简单但它的价值远不止“发请求看响应”这么表面。它内置了几个非常关键的能力自动处理 OAuth 2.0 认证流程、可视化展示所需权限Scopes、提供大量预置的示例查询、支持切换 HTTP 方法GET/POST/PATCH/DELETE、支持自定义请求头和请求体。这些能力组合在一起就构成了一个完整的 Graph API 调试环境。2.2 它和 Postman、curl 的本质区别在哪很多人会问我用 Postman 也能调 Graph API为什么要用 Graph Explorer这个问题我一开始也想过但实际用下来发现差异很大。Postman 调 Graph API 的流程是你得先去 Azure Portal 注册一个 App、配置 API 权限、生成 Client Secret、用各种方式获取 Token、把 Token 粘贴到 Postman 的 Authorization 头里、然后才能发请求。Token 过期了还得重新获取。整个过程繁琐且容易出错。Graph Explorer 的流程是打开网页、登录账号、点一下“同意权限”、直接发请求。它帮你把 OAuth 流程全部封装好了你不需要关心 Token 是怎么来的、怎么刷新的。更重要的是它会根据你要调的 API 自动告诉你需要哪些权限并且引导你完成管理员同意Admin Consent流程。还有一个关键差异Graph Explorer 内置了权限不足时的提示和修复引导。比如你调/users接口返回 403它会直接告诉你缺少User.Read.All权限并提供一个按钮让你去同意这个权限。Postman 不会给你这些提示你只能自己去查文档。2.3 典型使用场景盘点我整理了几个自己最常用的场景基本上覆盖了日常开发中 80% 的调试需求快速验证 API 返回结构在写代码之前先用 Graph Explorer 调一下接口看看返回的 JSON 字段名、嵌套结构、分页方式这样写代码时心里有底。调试权限问题当代码里调用 Graph API 报 403 时用 Graph Explorer 用同样的账号调同一个接口如果也报 403说明是权限配置问题如果不报错说明是代码里的认证流程有问题。测试批量操作比如批量创建用户、批量添加组成员可以先用 Graph Explorer 测试请求体格式是否正确。验证筛选和查询参数Graph API 支持$filter、$select、$expand、$search等 OData 查询参数用 Graph Explorer 可以快速测试各种参数组合的效果。学习和探索 APIGraph Explorer 提供了大量示例查询按场景分类用户、组、邮件、日历、Teams 等是学习 Graph API 最好的入口之一。注意Graph Explorer 默认使用的是微软提供的演示租户数据但你也可以切换到自己的租户。演示租户的数据是只读的适合学习和测试查询要测试写操作POST/PATCH/DELETE必须登录自己的租户。3. 核心功能拆解与实操要点3.1 界面布局与关键区域说明第一次打开 Graph Explorer界面看起来元素不少但核心区域就几个顶部栏左侧是 Microsoft Graph Explorer 的 Logo右侧显示当前登录的账号信息。如果你没登录会显示“Sign in to Graph Explorer”按钮。左侧面板分为两个 Tab——“Sample queries”和“Resources”。Sample queries 是预置的示例查询按场景分类Resources 是 API 文档的快捷入口。中间请求区这是最核心的区域。包含 HTTP 方法选择器GET/POST/PATCH/DELETE、URL 输入框、请求头编辑区Request headers、请求体编辑区Request body仅 POST/PATCH 时显示。右侧响应区显示 API 返回的响应。包含 Response preview格式化后的 JSON、Response headers响应头、HTTP status code状态码。权限面板在请求区上方有一个“Modify permissions”标签点开后会显示当前请求所需的权限列表以及你当前是否已经同意这些权限。3.2 认证机制它到底帮你做了什么Graph Explorer 的认证机制值得单独拿出来说因为这是它最核心的便利性来源。当你第一次登录 Graph Explorer 时它会引导你完成一次 OAuth 2.0 授权码流程。具体来说它使用的是一个微软预注册的公共客户端应用Public Client你登录后它会拿到一个 Access Token后续所有 API 请求都用这个 Token 来认证。关键点在于这个 Token 的权限范围Scopes是动态的。当你发起一个请求时Graph Explorer 会分析这个请求需要哪些权限然后检查你当前 Token 是否包含这些权限。如果不包含它会提示你去同意。你点击“Consent”按钮后会跳转到微软的权限同意页面同意后 Token 会被刷新包含新的权限。这个过程完全自动化你不需要手动构造授权 URL、不需要处理回调、不需要管理 Token 生命周期。对于调试来说这省掉了大量时间。实操心得Graph Explorer 拿到的 Token 默认有效期大约 1 小时。如果你调试时间较长Token 过期后会收到 401 错误此时刷新页面重新登录即可。另外如果你切换了登录账号之前同意的权限不会自动继承需要重新同意。3.3 示例查询的使用技巧Graph Explorer 的 Sample queries 是我用得最多的功能之一。它按类别组织包括类别典型示例适用场景Users获取我的信息、列出所有用户、创建用户用户管理开发Groups列出所有组、获取组成员、添加成员组管理开发Mail获取我的邮件、发送邮件、搜索邮件邮件集成开发Calendar获取我的日历事件、创建事件日历集成开发Teams列出所有团队、获取频道消息Teams 开发Security获取安全警报、条件访问策略安全合规开发每个示例查询都预填了 URL、HTTP 方法和请求体如果有的话。你只需要点击一下然后点“Run query”就能执行。执行后右侧会显示响应结果同时权限面板会显示这个查询需要哪些权限。我通常的做法是先找一个最接近我需求的示例查询运行一遍看看返回结构然后在此基础上修改 URL 参数或请求体逐步调整到我要的效果。这比从零开始构造请求快得多。3.4 权限管理与 Consent 流程权限是 Graph API 开发中最容易踩坑的地方Graph Explorer 在这方面提供了很好的支持。当你运行一个查询时如果当前 Token 缺少所需权限响应区会返回 403 Forbidden同时在权限面板中会高亮显示缺少的权限。你可以点击“Consent”按钮跳转到权限同意页面。同意后Graph Explorer 会重新获取 Token你再运行一次查询就能成功了。这里有一个很重要的细节有些权限需要管理员同意Admin Consent普通用户无法自行同意。比如User.Read.All这种读取所有用户信息的权限通常需要管理员在 Entra ID 中授予。如果你用普通账号登录点击 Consent 后可能会提示“需要管理员批准”。这种情况下你需要联系租户管理员让他在 Entra ID 的企业应用中找到 Graph Explorer 并授予相应权限。注意Graph Explorer 在生产租户中使用时它同意的权限是绑定到你的账号的。也就是说你通过 Graph Explorer 同意的权限不会影响其他用户也不会影响你自己的代码应用。它只是一个调试工具权限范围仅限于你在 Graph Explorer 中的操作。4. 完整实操流程从零开始调通一个 Graph API4.1 场景设定与准备工作假设我们现在有一个需求需要获取当前租户中所有用户的列表并且只返回每个用户的显示名称、邮箱和部门信息。这个需求在实际开发中很常见比如做员工目录同步、组织架构展示等。在开始之前你需要准备一个 Microsoft 365 开发者账号或企业账号如果没有可以申请 Microsoft 365 Developer Program 的免费沙箱一个浏览器Edge 或 Chrome 都可以确认你的账号有读取用户信息的权限普通用户默认可以读取自己的信息读取所有用户需要额外权限4.2 第一步登录并熟悉环境打开浏览器访问 Graph Explorer。点击右上角的“Sign in”按钮用你的 Microsoft 365 账号登录。登录成功后你会看到右上角显示你的账号名称。此时中间请求区默认已经填好了一个 GET 请求https://graph.microsoft.com/v1.0/me。这个接口返回当前登录用户的信息。直接点击“Run query”按钮右侧应该会返回你的用户信息 JSON。这一步的目的是确认认证流程正常。如果这一步就报错说明登录环节有问题需要检查账号状态或浏览器 Cookie 设置。4.3 第二步构造目标请求现在我们要获取所有用户列表。把 URL 从/me改成/usersHTTP 方法保持 GET。点击“Run query”。如果一切顺利你会看到返回了一个包含多个用户对象的 JSON 数组。但默认返回的字段很多包含 id、displayName、mail、department、jobTitle、officeLocation 等等。我们只需要 displayName、mail 和 department 三个字段。这时候就需要用到 OData 的$select参数。把 URL 改成https://graph.microsoft.com/v1.0/users?$selectdisplayName,mail,department再次运行返回的 JSON 中就只包含这三个字段了。响应体积会小很多对于大量数据的场景这个优化很有意义。4.4 第三步处理分页问题Graph API 对返回结果有分页限制默认每页最多返回 100 条记录不同接口可能不同。如果你的租户用户数超过 100返回的 JSON 中会包含一个odata.nextLink字段里面是下一页的 URL。在 Graph Explorer 中你可以直接复制这个 nextLink 的 URL粘贴到请求框中继续请求下一页。但更高效的方式是使用$top参数来控制每页数量或者使用$counttrue来获取总数。比如https://graph.microsoft.com/v1.0/users?$selectdisplayName,mail,department$top999$counttrue$top999表示每页最多返回 999 条实际最大值因接口而异$counttrue会在响应中额外返回一个odata.count字段告诉你总共有多少条记录。实操心得$top的值不是越大越好。设置过大的值可能导致请求超时特别是在网络状况不佳的情况下。我通常设置为 200-500 之间兼顾效率和稳定性。另外$counttrue需要额外的权限通常是User.Read.All如果报 403先去掉这个参数试试。4.5 第四步测试筛选和排序假设我们只想获取部门为“工程部”的用户可以使用$filter参数https://graph.microsoft.com/v1.0/users?$selectdisplayName,mail,department$filterdepartment eq 工程部如果想按显示名称排序https://graph.microsoft.com/v1.0/users?$selectdisplayName,mail,department$orderbydisplayName asc$filter和$orderby可以组合使用但要注意顺序$filter在前$orderby在后。另外不是所有字段都支持筛选和排序具体支持情况需要查阅 Microsoft Graph 的文档。Graph Explorer 的 Resources 面板可以直接跳转到对应接口的文档页面。4.6 第五步测试写操作前面都是 GET 请求现在测试一个 POST 请求。假设我们要创建一个新的用户。把 HTTP 方法改成 POSTURL 保持/users然后在 Request body 中填入{ accountEnabled: true, displayName: 测试用户, mailNickname: testuser, userPrincipalName: testuseryourtenant.onmicrosoft.com, passwordProfile: { forceChangePasswordNextSignIn: true, password: TempPassword123! } }点击“Run query”。如果权限足够会返回 201 Created 和创建成功的用户信息。如果权限不足会返回 403并在权限面板提示需要User.ReadWrite.All权限。这里有一个很重要的注意事项创建用户需要User.ReadWrite.All权限这个权限通常需要管理员同意。而且创建用户是一个写操作会在你的租户中产生真实数据。如果你只是测试记得创建后把用户删除避免留下垃圾数据。注意Graph Explorer 中的写操作是真实生效的不是模拟环境。所以在生产租户中操作时一定要谨慎建议先在测试租户中验证。5. 常见问题与排查技巧实录5.1 认证类问题问题一登录后仍然返回 401 Unauthorized这种情况通常有几个原因Token 过期、浏览器缓存问题、或者账号被限制。首先尝试刷新页面重新登录。如果还不行清除浏览器中 graph.microsoft.com 相关的 Cookie 和本地存储然后重新登录。如果问题依旧检查你的账号是否被条件访问策略限制比如要求 MFA 或特定网络环境。问题二Consent 后仍然返回 403 Forbidden可能的原因包括权限需要管理员同意但你用的是普通账号、权限同意有延迟、或者你请求的接口需要的是另一种权限。先检查权限面板中显示的所需权限是否已经全部打勾。如果有权限显示“Requires admin consent”你需要联系管理员。另外有些接口的权限要求比较特殊比如/users/{id}/messages需要Mail.Read或Mail.ReadBasic而不是User.Read.All。问题三切换账号后权限丢失Graph Explorer 的权限是绑定到账号的。切换账号后之前同意的权限不会自动转移。你需要用新账号重新执行 Consent 流程。这是预期行为不是 Bug。5.2 请求类问题问题四$filter 报错“Invalid filter clause”Graph API 的$filter语法遵循 OData 规范但有一些限制。常见错误包括字符串值没有用单引号包裹、使用了不支持的运算符、字段名拼写错误。比如department eq 工程部是正确的department 工程部是错误的Graph 用eq而不是。另外不是所有字段都支持$filter比如mail字段在某些接口中不支持筛选。问题五$expand 返回的数据不完整$expand用于展开导航属性比如获取用户的同时获取他的经理信息/users?$expandmanager。但$expand默认只返回展开对象的部分字段。如果需要指定字段可以使用嵌套的$select/users?$expandmanager($selectdisplayName,mail)。注意嵌套$select的语法括号和字段名之间不能有空格。问题六请求体格式正确但返回 400 Bad Request这种情况通常是请求体中的某个字段值不符合要求。比如创建用户时userPrincipalName必须包含域名、passwordProfile.password必须满足复杂度要求、mailNickname不能包含特殊字符。Graph Explorer 的响应区会返回详细的错误信息仔细阅读error.message字段通常能找到原因。5.3 性能与限制类问题问题七请求超时或响应很慢Graph API 对请求频率有限制Throttling。如果你短时间内发送大量请求会被限流返回 429 Too Many Requests。响应头中会包含Retry-After字段告诉你多少秒后可以重试。在 Graph Explorer 中调试时一般不会触发限流但如果你在批量测试需要注意控制频率。问题八返回的数据量太大浏览器卡顿当返回大量数据时Graph Explorer 的响应区可能会变得很卡。这时候可以使用$select减少返回字段或者使用$top限制返回数量。另外Graph Explorer 的响应区有“Formatted”和“Raw”两种视图切换到 Raw 视图可以减少渲染开销。5.4 常见问题速查表问题现象可能原因解决方法401 UnauthorizedToken 过期或未登录刷新页面重新登录403 Forbidden缺少权限或需要管理员同意检查权限面板联系管理员400 Bad Request请求体格式或字段值错误查看 error.message 详细信息429 Too Many Requests请求频率过高被限流等待 Retry-After 秒后重试$filter 报错语法错误或字段不支持检查 OData 语法和字段支持情况返回数据不完整分页限制使用 odata.nextLink 或 $top写操作无效果权限不足或请求体错误确认权限并检查请求体实操心得Graph Explorer 的响应区有一个很实用的功能——它会显示请求的完整 cURL 命令。点击响应区上方的“Code snippets”标签可以选择不同语言的代码片段C#、JavaScript、PowerShell 等。这个功能在你调试成功后需要把请求迁移到代码中时特别有用直接复制对应的代码片段就行省去了手动翻译请求的过程。6. 进阶技巧把 Graph Explorer 用到极致6.1 利用 Code Snippets 加速开发前面提到了 Code Snippets 功能这里展开说一下。当你在 Graph Explorer 中调通一个请求后点击“Code snippets”标签可以看到这个请求在不同语言中的实现代码。支持的代码片段包括C# (Microsoft Graph SDK)JavaScript (Microsoft Graph SDK)PowerShell (Microsoft Graph SDK)Java (Microsoft Graph SDK)Go (Microsoft Graph SDK)PHP (Microsoft Graph SDK)Python (Microsoft Graph SDK)cURL这些代码片段是自动生成的包含了认证配置和请求构造。你可以直接复制到项目中替换掉认证部分的配置比如 Client ID、Tenant ID就能直接运行。这个功能对于快速搭建项目原型特别有用。6.2 使用 Graph Explorer 的 API 文档联动Graph Explorer 的 Resources 面板提供了 Microsoft Graph API 的完整文档入口。当你在调试某个接口时可以直接点击 Resources 中的对应链接跳转到该接口的官方文档页面。文档中包含了详细的参数说明、权限要求、返回结构、示例代码等信息。我通常的做法是在 Graph Explorer 中调试接口的同时打开对应的文档页面对照着看。这样既能快速验证又能深入理解接口的细节。6.3 批量测试与自动化思路Graph Explorer 本身是一个手动工具不支持自动化脚本。但你可以用它来验证请求格式然后用 Postman 或代码来实现批量自动化。具体思路是在 Graph Explorer 中调通单个请求确认 URL、请求头、请求体格式正确。使用 Code Snippets 生成对应语言的代码。在代码中实现循环或批量逻辑替换掉单个请求的参数。在测试环境中运行批量脚本验证效果。这个流程结合了 Graph Explorer 的便利性和代码的灵活性是我在实际项目中最常用的方式。6.4 权限最小化原则的实践在 Graph Explorer 中调试时很容易养成“什么权限都同意”的习惯因为这样最省事。但在实际开发中权限最小化是一个重要的安全原则。你申请的应用权限应该只包含实际需要的范围而不是一股脑全要。Graph Explorer 可以帮助你实践这个原则当你调试一个接口时权限面板会精确显示所需的最小权限集。你可以记录下来在 Azure Portal 中注册应用时只申请这些权限。这样既能满足功能需求又能降低安全风险。注意Graph Explorer 本身使用的权限范围可能比你实际应用需要的更宽。因为它是通用调试工具需要覆盖各种场景。所以在参考它的权限时要结合自己的实际需求做裁剪。7. 我个人在实际使用中的几点体会用了这么久的 Graph Explorer有几个感受比较深。第一它最大的价值不是“能调 API”而是“能快速告诉你缺什么权限”。Graph API 的权限体系非常复杂同一个接口在不同场景下可能需要不同的权限组合。Graph Explorer 的权限面板和 Consent 引导基本上把这个问题可视化了省去了大量查文档和试错的时间。第二它的示例查询质量很高。微软的文档团队显然在这上面花了不少心思示例覆盖了大部分常用场景而且每个示例都配有说明和预期结果。对于刚接触 Graph API 的开发者来说从示例查询入手学习比直接看文档效率高得多。第三它也有局限性。比如不支持环境变量、不支持请求集合管理、不支持自动化测试。所以它适合做“单次调试”和“学习探索”不适合做“持续集成”和“批量测试”。在实际项目中我通常是 Graph Explorer 和 Postman 配合使用Graph Explorer 用来快速验证和探索Postman 用来管理请求集合和做批量测试。最后分享一个小技巧如果你经常需要调试同一组 API可以把常用的请求 URL 保存在浏览器书签中。Graph Explorer 的 URL 是支持直接拼接请求路径的比如https://developer.microsoft.com/graph/graph-explorer?request/usersmethodGETversionv1.0。这样打开书签就能直接加载对应的请求省去手动输入的麻烦。