用户资料与身份关联
读取登录用户资料，或在明确授权下查询组织用户信息，用于账号绑定、通讯录与内部协作。
接入要求/me 只支持委托身份，读取自己最小权限 User.Read；应用身份读取指定用户用 /users/{id} 并按端点要求申请 User.Read.All 等权限，需管理员同意。
读取登录用户的基本资料站内调用手册 · 参数、代码与排错办公协作 / Microsoft Graph API
Microsoft Graph
Microsoft Graph 是 Microsoft 云数据的统一 API 入口，可连接 Entra 用户资料、Outlook 日历邮件以及 OneDrive 文件等资源。适合日程、个人工作台和组织协作工具；每个资源的许可、权限与账号类型分别生效，本条目聚焦 v1.0 常用接口。
01 / CAPABILITIES
开放功能
核心接口调用手册
2 个场景覆盖委托身份读取登录用户资料与日历基本事件两个 v1.0 场景。明确 /me 的身份要求、最小权限、分页和周期事件边界；示例从已取得的 Graph access token 开始，不实现完整 OAuth 登录站点。
Outlook 日历事件
读取用户日历中的事件及时间信息，组合成日程工作台；完整时间窗与周期实例需按相应日历视图接口设计。
接入要求基本事件读取可用委托 Calendars.ReadBasic，正文或附件等需要更高权限；应用身份日历读取需专门应用权限、管理员同意与目标邮箱范围。
读取个人日历的基本事件站内调用手册 · 参数、代码与排错Outlook 邮件列表
查询邮箱或指定文件夹邮件，按字段选择减少返回量，适合邮件工作台和待办关联。
接入要求基本列表委托权限 Mail.ReadBasic，应用权限 Mail.ReadBasic.All；正文、附件和写入权限另核对，账号必须有可访问的邮箱服务。
OneDrive 文件与目录
列出文件夹内子项、识别文件或目录类型，连接个人文件工作台与云文件索引。
接入要求读取登录用户文件最小委托权限 Files.Read；应用身份列目录最小 Files.Read.All，并须管理员同意。SharePoint Embedded 还有容器权限要求。
02 / REQUIREMENTS
接入条件
- 适用主体
- 企业办公集成团队、个人效率工具开发者、面向组织的 SaaS 开发者
- 接入方式
- OAuth 2.0 委托访问，使用用户登录后的 access token / 应用身份访问，客户端凭证流程配合应用权限与管理员同意 / 公开客户端用支持的 OAuth 流程，不能在前端保存客户端密钥
- 申请概况
- 先在 Microsoft Entra 注册应用；委托访问需用户登录同意，应用身份访问需组织管理员同意且使用支持该身份的端点。
- 准备 Microsoft Entra 租户与有权注册应用的账号，在 App registrations 创建应用并选择单租户、多租户或支持个人 Microsoft 账号；目标接口是否支持个人账号需逐项确认。
- 委托模式配置正确的 Redirect URI，用授权码流程及适当 PKCE 配置取得 access token；申请的是 Microsoft Graph scopes，ID token 不能代替 API access token。
- 按资源分别申请权限。User.Read 不包含 Calendars.ReadBasic、Mail.ReadBasic 或 Files.Read，管理员策略也可能阻止用户自行同意。
- 后台守护进程使用应用权限及管理员同意，妥善配置证书、联合身份或服务端凭证；/me 没有登录用户，因此不能用于应用身份。
- 确认目标用户已具有相应邮箱、OneDrive 或 Microsoft 365 服务许可；Graph 权限不会自动创建服务或补足订阅。
- 本条目示例使用全球服务 graph.microsoft.com。中国由世纪互联运营的服务有独立注册、登录及 Graph 根地址，令牌不能跨云混用。
03 / GET STARTED
开通步骤
- 01
选账号类型和服务
列出要读的用户、日历、邮件或文件，确认全球服务或国家云及目标账号已有对应服务。
- 02
注册应用并配置授权
在 Entra 记录 Client ID，设置重定向地址和委托或应用权限，完成需要的管理员同意。
- 03
从登录用户读取开始
使用委托 access token 调用 /me，再按需增加日历等最小权限；不会因为注册成功就自动拥有组织数据。
- 04
处理分页与令牌生命周期
按 @odata.nextLink 翻页，处理令牌过期、权限撤销和 Retry-After；正式接入再评估批量与同步方案。
04 / COSTS & LIMITS
费用、边界与测试方式
费用概况
把服务许可、标准调用和计量接口分开核算。
- Microsoft 官方把大多数常规增删改查归为标准 API，在许可所包含的资源和合理使用阈值内，不额外收标准 API 调用费；本条目核心示例为用户资料和日历读取。
- 组织使用 Outlook/Exchange、OneDrive 等仍需相应服务许可；Microsoft 365 商业套餐按用户、账单周期和所含服务计费，Graph 不替代席位与存储费用。
- 高容量、批量或高级 API 可能按请求、返回对象或其他计量单位另收费。使用计量服务时需关联有效 Azure 订阅，应逐端点核对计量单位，不能把标准 API 条件扩展为全站免费。
- 应用后端、数据库和额外云资源另计费；限流阈值及权限不会因付费套餐自动取消。
使用范围与限制
- /me 仅用于有登录用户的委托访问。应用身份必须使用支持应用权限的资源路径，不能把客户端凭证 token 直接套入 /me 示例。
- 委托权限取应用授权和用户自身权限的交集；应用权限一般需要管理员同意，且受资源范围与组织策略限制。
- 本条目不把 Teams、Copilot、安全和批量导出等全部 Graph 能力视为同一套餐或同一组权限；具体接口可能单独许可或计量。
- 日历 events 列表包含单次事件和周期主项，不等于指定时间范围内已展开的全部周期实例。
- v1.0 与 beta 的稳定性承诺不同；本条目核心示例固定 v1.0。各类资源有不同限流，不存在覆盖所有 Graph 端点的统一每分钟额度。
- 全球服务与国家云的服务可用性、账号类型、根地址和 token 发行方不同；本条目的全球示例不能仅替换一个域名就假定兼容。
如何进行开发测试
- 全球服务的稳定接口使用 https://graph.microsoft.com/v1.0；本条目代码只覆盖这一环境。
- 开发可在 Graph Explorer 查看请求与同意权限，登录后访问的仍是自己的真实数据；示例租户数据不代表个人账号已获权限。
- 中国世纪互联运营和美国政府云使用独立的服务端点与令牌；按官方部署文档选环境。
- 本次未注册应用、登录授权、读取邮箱文件或调用任何真实 Graph API。
接入前再确认
- 按 v1.0 端点和权限参考交叉核对；日历基本权限委托名 Calendars.ReadBasic，应用名 Calendars.ReadBasic.All，二者不可混用。
- 未创建租户或购买许可，未确认具体组织管理员同意、条件访问和邮箱准备状态。
05 / OFFICIAL SOURCES
官方资料
以下资料用于核对本页内容。申请与使用时，请以对应接口的最新规则为准。
- 01Microsoft Graph 能力总览已核对官方资料 · 2026-10-15
- 02身份与委托／应用访问已核对官方资料 · 2026-10-15
- 03Microsoft Entra 应用注册已核对官方资料 · 2026-10-15
- 04代表用户获取访问令牌已核对官方资料 · 2026-10-15
- 05Get user 与 /me 委托权限已核对官方资料 · 2026-10-15
- 06列出用户日历事件已核对官方资料 · 2026-10-15
- 07列出 OneDrive 文件夹内容已核对官方资料 · 2026-10-15
- 08读取邮件列表已核对官方资料 · 2026-10-15
- 09Microsoft Graph 权限参考已核对官方资料 · 2026-10-15
- 10标准 API 与计量 API 费用边界已核对官方资料 · 2026-10-15
- 11Microsoft 365 商业套餐与包含服务已核对官方资料 · 2026-10-15
- 12Microsoft Graph 限流与退避已核对官方资料 · 2026-10-15
- 13Microsoft Graph 错误响应已核对官方资料 · 2026-10-15
- 14不同云环境的认证与 API 根地址已核对官方资料 · 2026-10-15
- 15Microsoft Entra 管理中心官方入口 · 细则待复核 · 2026-10-15
- 16Microsoft Graph Explorer官方入口 · 细则待复核 · 2026-10-15
官方文档核对，未进行接口实测
最近核验 2026-10-15 · 查看核验说明
最近核验 2026-10-15 · 查看核验说明
