获取用户

命名空间:microsoft.graph

检索 用户 对象的属性和关系。

默认情况下,此操作仅返回每位用户较常用属性中的一部分。 这些默认属性将记录在属性部分中。 要获取默认返回的属性,请对用户执行 GET 操作,并在 $select OData 查询选项中指定这些属性。 由于用户资源支持扩展,因此也可使用 GET 操作获取用户实例中的自定义属性和扩展数据。

通过客户Microsoft Entra ID客户还可以使用此 API 操作来检索其详细信息。

此 API 可用于以下国家级云部署

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时,才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息,请参阅权限类型。 要了解有关这些权限的详细信息,请参阅 权限参考

权限类型 最低特权权限 更高特权权限
委派(工作或学校帐户) User.Read User.ReadWrite、User.ReadBasic.All、User.Read.All、User.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.All
委派(个人 Microsoft 帐户) User.Read User.ReadWrite
应用程序 User.Read.All User.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.All

注意

  • 调用 /me 终结点需要已登录的用户,因此需要委派权限。 使用 /me 的终结点时不支持应用程序权限。
  • User.Read 权限允许应用读取配置文件,并仅发现组成员身份、报表和经理等已登录用户的关系。
  • 读取 employeeLeaveDateTime 属性:
    • 在委派方案中,管理员至少需要以下Microsoft Entra角色之一:生命周期工作流管理员 (最低特权) 全局读取者;必须向应用授予 User-LifeCycleInfo.Read.All 委托权限。
    • 在具有 Microsoft Graph 权限的仅限应用方案中,必须向应用授予 User-LifeCycleInfo.Read.All 权限。
  • 读取 customSecurityAttributes 属性:
    • 在委派方案中,必须为管理员分配 属性分配管理员 角色,并且应用被授予 CustomSecAttributeAssignment.Read.All 权限。
    • 在具有 Microsoft Graph 权限的仅限应用方案中,必须向应用授予 CustomSecAttributeAssignment.Read.All 权限。

HTTP 请求

对于特定用户:

GET /me
GET /users/{id | userPrincipalName}

提示

  • userPrincipalName$ 字符开头时,GET 请求 URL 语法 /users/$x@y.com 失败,并出现 400 Bad Request 错误代码。 这是因为此请求 URL 违反了 OData URL 约定,该约定要求只有系统查询选项才能以 $ 字符作为前缀。 删除 /users 后面的斜杠 (/),并将 userPrincipalName 括在圆括号和单引号中,如下所示:/users('$x@y.com')。 例如,/users('$AdeleVance@contoso.com')
  • 要使用 userPrincipalName 查询 B2B 用户,请对哈希 (#) 字符进行编码。 也就是说,将 # 符号替换为 %23。 例如,/users/AdeleVance_adatum.com%23EXT%23@contoso.com

对于登录用户:

GET /me

可选的查询参数

此方法支持 $selectOData 查询参数 来检索特定用户属性,包括默认情况下不返回的属性。

默认情况下,仅返回一组有限的属性(businessPhones、displayName、givenName、id、jobTitle、mail、mobilePhone、officeLocation、preferredLanguage、surname、userPrincipalName)。

若要返回其他属性,必须使用 OData $select 查询参数指定所需的一组 user 属性。 例如,若要返回 displayNamegivenNamepostalCode,请将以下表达式添加到查询 $select=displayName,givenName,postalCode

扩展属性还支持查询参数,如下所示:

扩展类型 备注
onPremisesExtensionAttributes 1-15 仅与 $select 一起返回。
架构扩展 仅通过 $select 返回。
开放扩展 仅通过 获取开放扩展 操作返回。
目录扩展 仅与 $select 一起返回。

请求标头

标头
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权

请求正文

请勿提供此方法的请求正文。

响应

如果成功,此方法在响应正文中返回 200 OK 响应代码和 user 对象。 除非使用 $select 指定特定属性,否则返回默认属性。 当成功处理请求时,此方法会返回 202 Accepted,但服务器需要更多时间来完成相关的后台操作。

如果 ID 为的用户不存在,此方法将 404 Not Found 返回错误代码。

示例

示例 1:标准用户请求

请求

默认情况下,仅返回一组有限的属性(businessPhones、displayName、givenName、id、jobTitle、mail、mobilePhone、officeLocation、preferredLanguage、surname、userPrincipalName)。 此示例展示了默认请求和响应。

GET https://graph.microsoft.com/v1.0/users/87d349ed-44d7-43e1-9a83-5f2406dee5bd

响应

HTTP/1.1 200 OK
Content-type: application/json

{
  "businessPhones": [
       "+1 425 555 0109"
   ],
   "displayName": "Adele Vance",
   "givenName": "Adele",
   "jobTitle": "Retail Manager",
   "mail": "AdeleV@contoso.com",
   "mobilePhone": "+1 425 555 0109",
   "officeLocation": "18/2111",
   "preferredLanguage": "en-US",
   "surname": "Vance",
   "userPrincipalName": "AdeleV@contoso.com",
   "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
}

示例 2:登录用户请求

可以将 /users/{id | userPrincipalName} 替换为 /me,获取登录用户的用户信息。

请求

GET https://graph.microsoft.com/v1.0/me

响应

HTTP/1.1 200 OK
Content-type: application/json

{
  "businessPhones": [
       "+1 425 555 0109"
   ],
   "displayName": "Adele Vance",
   "givenName": "Adele",
   "jobTitle": "Retail Manager",
   "mail": "AdeleV@contoso.com",
   "mobilePhone": "+1 425 555 0109",
   "officeLocation": "18/2111",
   "preferredLanguage": "en-US",
   "surname": "Vance",
   "userPrincipalName": "AdeleV@contoso.com",
   "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
}

示例 3:使用 $select 检索用户的特定属性

若要检索特定属性,请使用 OData $select 查询参数。 例如,若要返回 displayNamegivenNamepostalCodeidentities,则需要将以下内容添加到查询 $select=displayName,givenName,postalCode,identities

请求

GET https://graph.microsoft.com/v1.0/users/87d349ed-44d7-43e1-9a83-5f2406dee5bd?$select=displayName,givenName,postalCode,identities

响应

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(displayName,givenName,postalCode,identities)/$entity",
    "displayName": "Adele Vance",
    "givenName": "Adele",
    "postalCode": "98004",
    "identities": [
        {
            "signInType": "userPrincipalName",
            "issuer": "contoso.com",
            "issuerAssignedId": "AdeleV@contoso.com"
        }
    ]
}

示例 4:获取用户的架构扩展值

在此示例中,架构扩展 ID 为 ext55gb1l09_msLearnCourses

请求

GET https://graph.microsoft.com/v1.0/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e?$select=ext55gb1l09_msLearnCourses

响应

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(ext55gb1l09_msLearnCourses)/$entity",
    "ext55gb1l09_msLearnCourses": {
        "@odata.type": "#microsoft.graph.ComplexExtensionValue",
        "courseType": "Developer",
        "courseName": "Introduction to Microsoft Graph",
        "courseId": 1
    }
}

示例 5:获取用户的自定义安全属性分配

以下示例演示如何获取用户的自定义安全属性分配。

属性 #1

  • 属性集:Engineering
  • 属性:Project
  • 属性数据类型:字符串集合
  • 属性值:["Baker","Cascade"]

属性 #2

  • 属性集:Engineering
  • 属性:CostCenter
  • 属性数据类型:整数集合
  • 属性值:[1001]

属性 #3

  • 属性集:Engineering
  • 属性:Certification
  • 属性数据类型:布尔
  • 属性值:true

属性 #4

  • 属性集:Marketing
  • 属性:EmployeeId
  • 属性数据类型:字符串
  • 属性值:"QN26904"

若要获取自定义安全属性分配,必须为调用主体分配“属性分配读取者”或“属性分配管理员”角色,并且必须被授予 CustomSecAttributeAssignment.Read.AllCustomSecAttributeAssignment.ReadWrite.All 权限。

有关自定义安全属性分配的更多示例,请参阅示例:使用Microsoft 图形 API分配、更新、列出或删除自定义安全属性分配

请求

GET https://graph.microsoft.com/v1.0/users/{id}?$select=customSecurityAttributes

响应

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": {
        "Marketing": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "EmployeeId": "QN26904"
        },
        "Engineering": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "Project@odata.type": "#Collection(String)",
            "Project": [
                "Baker",
                "Cascade"
            ],
            "CostCenter@odata.type": "#Collection(Int32)",
            "CostCenter": [
                1001
            ],
            "Certification": true
        }
    }
}

如果没有向用户分配自定义安全属性,或者调用主体没有访问权限,则响应如下:

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": null
}