Microsoft Graph调用手册
读取登录用户的基本资料
用 User.Read 委托权限调用 /me,确认用户标识和基础资料,避免把应用身份 token 用到登录用户路径。
← 返回平台功能接入准备
- 注册应用并配置适合客户端的登录与 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 的终端。按调用步骤保存代码文件,再在同一终端执行。
调用步骤
- 01
进入 Microsoft Entra 管理中心 → App registrations,创建应用并选择自己需要的账号类型;配置与客户端匹配的 Redirect URI。
- 02
在 API permissions → Microsoft Graph → Delegated permissions 添加本场景权限;组织要求时请管理员同意。通过授权码流程让用户登录并同意,取得 Microsoft Graph access token。
- 03
把 access token 设置为 MS_GRAPH_ACCESS_TOKEN,在本机或服务器运行示例;令牌过期后用自己的授权流程刷新或重新登录。
- 04
运行 /me 请求,保存 id 作为当前租户或账号体系内的用户标识;不要把可为空的 mail 字段当作所有账号都有的主键。
调用 01
读取当前用户指定字段
用 $select 只返回需要的字段;全球服务使用 graph.microsoft.com/v1.0。
GET
https://graph.microsoft.com/v1.0/me?$select=id,displayName,userPrincipalName,mail请求头
AuthorizationBearer ${MS_GRAPH_ACCESS_TOKEN}Acceptapplication/json
参数说明
参数表可左右滑动,查看完整说明。
| 字段 / 位置 | 类型 / 必填 | 说明 |
|---|---|---|
$selectQuery | string可选 | 逗号分隔所需字段,本例 id,displayName,userPrincipalName,mail,减少无关个人信息。 |
调用代码
替换示例 ID 与请求体内容后运行。cURL 会报 HTTP 错误,业务状态还需按下方返回示例核对。
# 执行后核对返回 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"
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 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 与用户显示名称用途不同。 以下为结构示意,非本站实测结果。
{
"@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、令牌刷新和退出撤销等流程。
核验来源
本站按官方资料整理本场景的必要调用步骤与代码,覆盖范围以本页列出的接口为准。官方资料用于追溯规范及查看变更。
- 01身份与委托/应用访问核验日期 2026-10-15
- 02Microsoft Entra 应用注册核验日期 2026-10-15
- 03代表用户获取访问令牌核验日期 2026-10-15
- 04标准 API 与计量 API 费用边界核验日期 2026-10-15
- 05Get user 与 /me 委托权限核验日期 2026-10-15
- 06Microsoft Graph 错误响应核验日期 2026-10-15