获取用户

  • 项目

命名空间：microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。

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

默认情况下，此操作仅返回每位用户较常用属性中的一部分。 这些默认属性将记录在属性部分中。 要获取非默认返回的属性，请对用户执行 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

提示

  1. 调用 /me 终结点需要已登录的用户，因此需要委派权限。 使用 /me 的终结点时不支持应用程序权限。
  2. User.Read 权限允许应用读取配置文件，并仅发现组成员身份、报表和经理等已登录用户的关系。

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 查询参数 来检索特定的用户属性，包括默认情况下不返回的属性。 扩展属性还支持查询参数，如下所示：

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

请求标头

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

请求正文

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

响应

如果成功，此方法在响应正文中返回 200 OK 响应代码和 user 对象。 除非使用 $select 指定特定属性，否则返回默认属性。

当成功处理请求时，此方法会返回 202 Accepted，但服务器需要更多时间来完成相关的后台操作。

示例

示例 1：获取已登录用户的属性

请求

GET https://graph.microsoft.com/beta/me
响应

以下示例显示了相应的响应。 注意：为了提高可读性，可能缩短了此处显示的响应对象。

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

{
   "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：获取指定用户的属性

请求

以下示例显示了一个请求。

GET https://graph.microsoft.com/beta/users/{id}

响应

以下示例显示了相应的响应。

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

{
      "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 查询参数。 例如，若要返回 displayName、givenName、postalCode 和 identities，则需要将以下内容添加到查询 $select=displayName,givenName,postalCode,identities。

请求

GET https://graph.microsoft.com/v1.0/users/{id | userPrincipalName}?$select=displayName,givenName,postalCode,identities

响应

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$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：获取用户的自定义安全属性分配

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

属性 #1

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

属性 #2

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

属性 #3

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

属性 #4

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

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

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

请求

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

响应

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$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/beta/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": null
}

示例 5：获取用户的架构扩展值

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

请求

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

响应

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

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

相关内容