Microsoft Graph调用手册

读取登录用户的基本资料

用 User.Read 委托权限调用 /me,确认用户标识和基础资料,避免把应用身份 token 用到登录用户路径。

官方资料核对 2026-10-15示例代码,未进行真实接口实测
← 返回平台功能

接入准备

  • 注册应用并配置适合客户端的登录与 Redirect URI;申请 Microsoft Graph 委托权限 User.Read。
  • 用户已经登录并同意,取得面向 Microsoft Graph 的 access token;本例不使用应用权限和客户端凭证流程。

准备环境变量

示例值需要替换为自己的凭证或资源 ID。代码在本机或服务端运行;密钥不应放进公开网页。

MS_GRAPH_ACCESS_TOKEN
用户登录并同意本场景 Microsoft Graph 委托权限后取得的 access token;不是 ID token,也不是客户端凭证模式 token。
终端
export MS_GRAPH_ACCESS_TOKEN='replace_with_delegated_graph_access_token'

以上 export 适用于 macOS / Linux 的终端。按调用步骤保存代码文件,再在同一终端执行。

调用步骤

  1. 01

    进入 Microsoft Entra 管理中心 → App registrations,创建应用并选择自己需要的账号类型;配置与客户端匹配的 Redirect URI。

  2. 02

    在 API permissions → Microsoft Graph → Delegated permissions 添加本场景权限;组织要求时请管理员同意。通过授权码流程让用户登录并同意,取得 Microsoft Graph access token。

  3. 03

    把 access token 设置为 MS_GRAPH_ACCESS_TOKEN,在本机或服务器运行示例;令牌过期后用自己的授权流程刷新或重新登录。

  4. 04

    运行 /me 请求,保存 id 作为当前租户或账号体系内的用户标识;不要把可为空的 mail 字段当作所有账号都有的主键。

调用 01

读取当前用户指定字段

用 $select 只返回需要的字段;全球服务使用 graph.microsoft.com/v1.0。

GEThttps://graph.microsoft.com/v1.0/me?$select=id,displayName,userPrincipalName,mail

请求头

Authorization
Bearer ${MS_GRAPH_ACCESS_TOKEN}
Accept
application/json

参数说明

参数表可左右滑动,查看完整说明。

字段 / 位置类型 / 必填说明
$selectQuerystring可选逗号分隔所需字段,本例 id,displayName,userPrincipalName,mail,减少无关个人信息。

调用代码

替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误,业务状态还需按下方返回示例核对。

cURL
# 执行后核对返回 JSON 的业务状态;HTTP 200 仍可能包含业务错误。
curl --silent --show-error --fail-with-body \
  --request GET \
  --url "https://graph.microsoft.com/v1.0/me?\$select=id,displayName,userPrincipalName,mail" \
  --header "Authorization: Bearer ${MS_GRAPH_ACCESS_TOKEN}" \
  --header "Accept: application/json"
Python 3
import json
import os
import re
import urllib.request
import urllib.error

def expand(value):
    return re.sub(r"\$\{([A-Z][A-Z0-9_]*)\}",
                  lambda match: os.environ[match.group(1)], value)

url = expand("https://graph.microsoft.com/v1.0/me?$select=id,displayName,userPrincipalName,mail")
headers = {
    "Authorization": expand("Bearer ${MS_GRAPH_ACCESS_TOKEN}"),
    "Accept": expand("application/json"),
}
data = None
request = urllib.request.Request(url, data=data, headers=headers, method="GET")
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    print(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}")
    raise SystemExit(1)
print(json.dumps(result, ensure_ascii=False, indent=2))
Node.js
// Node.js 22+,保存为 request.mjs 后运行 node request.mjs
function expand(value) {
  return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (_, name) => {
    if (!process.env[name]) throw new Error(`缺少环境变量 ${name}`);
    return process.env[name];
  });
}

const url = expand("https://graph.microsoft.com/v1.0/me?$select=id,displayName,userPrincipalName,mail");
const headers = Object.fromEntries(
  Object.entries({
  "Authorization": "Bearer ${MS_GRAPH_ACCESS_TOKEN}",
  "Accept": "application/json"
}).map(([key, value]) => [key, expand(value)])
);
const response = await fetch(url, {
  method: "GET",
  headers,
  signal: AbortSignal.timeout(30000),
});
const text = await response.text();
if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
const result = JSON.parse(text);
console.log(JSON.stringify(result, null, 2));

返回示例

按官方属性整理的节选结构示意,姓名、邮箱及 ID 均为虚构。mail 可能为 null;id 与用户显示名称用途不同。 以下为结构示意,非本站实测结果。

JSON
{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,userPrincipalName,mail)/$entity",
  "id": "11111111-2222-3333-4444-555555555555",
  "displayName": "示例用户",
  "userPrincipalName": "example@contoso.com",
  "mail": null
}

常见错误与排查

HTTP 401 / InvalidAuthenticationToken访问令牌缺失、过期或不适用于 Graph。
从对应云环境重新获取 Graph access token;检查令牌用途和到期,不要使用 ID token。
HTTP 403 / ErrorAccessDenied缺少权限、许可或受组织策略限制。
检查令牌中已同意的 scope、资源服务许可和条件访问;需要时由管理员授权,扩大权限前先确认具体资源。
HTTP 429触发服务限流。
按 Retry-After 等待再重试;减少重复轮询。若响应无该头,使用指数退避。
HTTP 400 / BadRequest请求格式错误,或 /me 所用身份不符合要求。
检查查询参数与 access token 是否来自有登录用户的委托流程;应用身份应按官方要求改用 /users/{id},不能使用 /me。

调用注意

  • 读取自己使用 User.Read 委托权限;应用身份读取指定用户的权限和路径不同,不在本例中混用。
  • 示例没有创建或修改任何用户;不要把 User.Read 解释为可遍历组织完整资料的权限。

注意事项

  • 标准 API 在服务许可和使用阈值内无额外调用费,其他资源许可与计量接口分别核对。
  • 本页从已有令牌开始;完整产品需接好 OAuth state、PKCE、令牌刷新和退出撤销等流程。

核验来源

本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。

  1. 01
    身份与委托/应用访问核验日期 2026-10-15
  2. 02
    Microsoft Entra 应用注册核验日期 2026-10-15
  3. 03
    代表用户获取访问令牌核验日期 2026-10-15
  4. 04
  5. 05
    Get user 与 /me 委托权限核验日期 2026-10-15
  6. 06
    Microsoft Graph 错误响应核验日期 2026-10-15

Microsoft Graph的其他调用手册

← 返回Microsoft Graph的全部功能