列出用户

  • 项目

命名空间：microsoft.graph

检索 user 对象列表。

注意： 此请求可能对最近创建、更新或删除的用户具有复制延迟。

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

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

权限

要调用此 API，需要以下权限之一。 若要了解详细信息，包括如何选择权限的信息，请参阅权限。

权限类型 权限（从最低特权到最高特权）
委派（工作或学校帐户） User.ReadBasic.All、User.Read.All、User.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.All
委派（个人 Microsoft 帐户） 不支持。
应用程序 User.Read.All、User.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.All

来宾无法调用此 API。 有关成员和来宾的权限的详细信息，请参阅 Microsoft Entra ID 中的默认用户权限是什么？

HTTP 请求

GET /users

可选的查询参数

此方法支持 $count、、$expand、$filter、$orderby$search、 $select和 $topOData 查询参数来帮助自定义响应。 不支持 $skip。 列出用户时必须指定 $select=signInActivity 或 $filter=signInActivity ，因为默认情况下不会返回 signInActivity 属性。

只有将 ConsistencyLevel 标头设置为 eventual 和 $count 时，才支持某些查询。 有关详细信息，请参阅 目录对象的高级查询功能。 $count 和 $search 参数当前在 Azure AD B2C 租户中不可用。

默认情况下，仅返回一组有限的属性（businessPhones、displayName、givenName、id、jobTitle、mail、mobilePhone、officeLocation、preferredLanguage、surname 和 userPrincipalName）。要返回备用属性集，请使用 OData $select 查询参数指定所需的一组 用户属性。 例如，若要返回 displayName、givenName 和 postalCode，请将以下项添加到查询 $select=displayName,givenName,postalCode。

扩展属性还支持查询参数，如下所示：

扩展类型 备注
onPremisesExtensionAttributes 1-15 仅通过 $select 返回。 支持 $filter（eq、ne 和 null 值上的 eq）。
架构扩展 仅通过 $select 返回。 支持 $filter（eq、ne 和 null 值上的 eq）。
开放扩展 仅通过 $expand 返回，即 users?$expand=extensions。
目录扩展 仅通过 $select 返回。 支持 $filter（eq、ne 和 null 值上的 eq）。

某些属性不能在用户集合中返回。 仅 当检索单个用户时，才支持以下属性： aboutMe、 生日、 hireDate、 interests、 mySite、 pastProjects、 preferredName、 责任、 学校、 技能、 mailboxSettings。

以下属性在个人 Microsoft 帐户中不受支持，将为 null： aboutMe、 生日、 interests、 mySite、 pastProjects、 preferredName、 责任、 学校、 技能、 streetAddress。

请求标头

标头 值
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。
ConsistencyLevel 最终。 当使用 $search 或 $filter 的特定用法时，需要此标头和 $count。 有关使用 ConsistencyLevel 和 $count的详细信息，请参阅 目录对象的高级查询功能。

请求正文

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

响应

如果成功，此方法在响应正文中返回 200 OK 响应代码和 user 对象集合。 如果返回大的用户集，则可以在应用中使用分页。

例如，如果尝试 $select 在集合上使用 /users 来检索用户集合中无法返回的属性 (，请求 ../users?$select=aboutMe) 将返回 501 Not Implemented 错误代码。

示例

示例 1：列出所有用户

请求

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

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

响应

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

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
    "value": [
        {
            "businessPhones": [],
            "displayName": "Conf Room Adams",
            "givenName": null,
            "jobTitle": null,
            "mail": "Adams@contoso.com",
            "mobilePhone": null,
            "officeLocation": null,
            "preferredLanguage": null,
            "surname": null,
            "userPrincipalName": "Adams@contoso.com",
            "id": "6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0"
        },
        {
            "businessPhones": [
                "425-555-0100"
            ],
            "displayName": "MOD Administrator",
            "givenName": "MOD",
            "jobTitle": null,
            "mail": null,
            "mobilePhone": "425-555-0101",
            "officeLocation": null,
            "preferredLanguage": "en-US",
            "surname": "Administrator",
            "userPrincipalName": "admin@contoso.com",
            "id": "4562bcc8-c436-4f95-b7c0-4f8ce89dca5e"
        }
    ]
}

示例 2：使用登录名创建用户帐户

请求

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

注意： 筛选 issuerAssignedId时，必须同时提供 颁发者 和 issuerAssignedId。 但是，在某些情况下将忽略 颁发者 值。 有关对标识进行筛选的详细信息，请参阅 objectIdentity 资源类型

GET https://graph.microsoft.com/v1.0/users?$select=displayName,id&$filter=identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')

响应

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

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

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

{
  "value": [
    {
      "displayName": "John Smith",
      "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
    }
  ]
}

示例 3：仅获取用户数量

请求

以下示例显示了一个请求。 此请求要求将 ConsistencyLevel 标头设置为 eventual，因为在请求中有 $count。 有关使用 ConsistencyLevel 和 $count的详细信息，请参阅 目录对象的高级查询功能。

注意：$count和$search 查询参数当前在 Azure AD B2C 租户中不可用。

GET https://graph.microsoft.com/v1.0/users/$count
ConsistencyLevel: eventual

响应

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

HTTP/1.1 200 OK
Content-type: text/plain

893

示例 4：使用 $filter 和 $top 获取显示名称以“a”开头（包括返回的对象数）的用户。

请求

以下示例显示了一个请求。 此请求需要将 ConsistencyLevel 标头设置为 eventual 和 $count=true 查询字符串，因为请求同时具有 $orderby 和 $filter 查询参数。 有关使用 ConsistencyLevel 和 $count的详细信息，请参阅 目录对象的高级查询功能。

注意：$count和$search 查询参数当前在 Azure AD B2C 租户中不可用。

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(displayName,'a')&$orderby=displayName&$count=true&$top=1
ConsistencyLevel: eventual

响应

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

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

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.count":1,
  "value":[
    {
      "displayName":"a",
      "mail":"a@contoso.com",
      "mailNickname":"a_contoso.com#EXT#",
      "userPrincipalName":"a_contoso.com#EXT#@contoso.com"
    }
  ]
}

示例 5：使用 $filter 获取以“”a@contoso.com结尾的邮件的所有用户，包括返回的对象计数，结果按 userPrincipalName 排序

请求

以下示例显示了一个请求。 此请求需要将 ConsistencyLevel 标头设置为 eventual 和 $count=true 查询字符串，因为请求同时具有 $orderby 和 $filter 查询参数，并且还使用 endsWith 运算符。 有关使用 ConsistencyLevel 和 $count的详细信息，请参阅 目录对象的高级查询功能。

注意：$count和$search 查询参数当前在 Azure AD B2C 租户中不可用。

GET https://graph.microsoft.com/v1.0/users?$filter=endswith(mail,'a@contoso.com')&$orderby=userPrincipalName&$count=true
ConsistencyLevel: eventual

响应

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

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

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.count": 1,
  "value": [
    {
      "displayName": "Grady Archie",
      "givenName": "Grady",
      "jobTitle": "Designer",
      "mail": "GradyA@contoso.com",
      "userPrincipalName": "GradyA@contoso.com",
      "id": "e8b753b5-4117-464e-9a08-713e1ff266b3"
      }
    ]
}

示例 6：使用 $search 获取显示名称中包含字母“wa”或“to”（包括返回的对象数）的用户。

请求

以下示例显示了一个请求。 此请求要求将 ConsistencyLevel 标头设置为 eventual，因为在请求中有 $search。 有关使用 ConsistencyLevel 和 $count的详细信息，请参阅 目录对象的高级查询功能。

注意：$count和$search 查询参数当前在 Azure AD B2C 租户中不可用。

GET https://graph.microsoft.com/v1.0/users?$search="displayName:wa"&$orderby=displayName&$count=true
ConsistencyLevel: eventual

响应

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

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

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.count":7,
  "value":[
    {
      "displayName":"Oscar Ward",
      "givenName":"Oscar",
      "mail":"oscarward@contoso.com",
      "userPrincipalName":"oscarward@contoso.com"
    }
  ]
}

示例 7：使用 $search 获取显示名称中包含字母"wa"或字母"ad"（包括返回的对象计数）的用户

请求

以下示例显示了一个请求。 此请求要求将 ConsistencyLevel 标头设置为 eventual，因为在请求中有 $search。 有关使用 ConsistencyLevel 和 $count的详细信息，请参阅 目录对象的高级查询功能。

注意：$count和$search 查询参数当前在 Azure AD B2C 租户中不可用。

GET https://graph.microsoft.com/v1.0/users?$search="displayName:wa" OR "displayName:ad"&$orderbydisplayName&$count=true
ConsistencyLevel: eventual

响应

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

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

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.count":7,
  "value":[
    {
      "displayName":"Oscar Ward",
      "givenName":"Oscar",
      "mail":"oscarward@contoso.com",
      "userPrincipalName":"oscarward@contoso.com"
    },
    {
      "displayName":"contosoAdmin1",
      "givenName":"Contoso Administrator",
      "mail":"'contosoadmin1@fabrikam.com",
      "userPrincipalName":"contosoadmin1_fabrikam.com#EXT#@contoso.com"
    }
  ]
}

示例 8：通过 userPrincipalName 从特定租户或域获取来宾 (B2B) 用户

请求

以下示例显示了一个请求。 来宾 (B2B 协作的 userPrincipalName 值) 用户始终包含“#EXT#”标识符。 例如，其主租户中用户的 userPrincipalName 为 AdeleV@adatum.com。 邀请用户在租户中协作时， contoso.com 租户中的 userPrincipalName 为“AdeleV_adatum.com#EXT#@contoso.com”。

此请求需要 将 ConsistencyLevel 标头设置为 eventual 和 $count=true 查询字符串，因为请求包含 endsWith 运算符。 有关使用 ConsistencyLevel 和 $count的详细信息，请参阅 目录对象的高级查询功能。

注意： 必须在请求 URL 中将 userPrincipalName 值中的保留字符“#”编码为“%23”。 有关详细信息，请参阅 编码特殊字符。

GET https://graph.microsoft.com/v1.0/users?$select=id,displayName,mail,identities&$filter=endsWith(userPrincipalName,'%23EXT%23@contoso.com')&$count=true
ConsistencyLevel: eventual

响应

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

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,mail,identities)",
    "@odata.count": 2,
    "value": [
        {
            "id": "39807bd1-3dde-48f3-8165-81ddd4e46de0",
            "displayName": "Adele Vance",
            "mail": "AdeleV@adatum.com",
            "identities": [
                {
                    "signInType": "userPrincipalName",
                    "issuer": "contoso.com",
                    "issuerAssignedId": "AdeleV_adatum.com#EXT#@cntoso.com"
                }
            ]
        }
    ]
}

示例 9：使用 $filter 获取分配有特定许可证的用户

请求

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

GET https://graph.microsoft.com/v1.0/users?$select=id,mail,assignedLicenses&$filter=assignedLicenses/any(u:u/skuId eq cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46)

响应

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

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,mail,assignedLicenses)",
  "value": [
    {
      "id": "cb4954e8-467f-4a6d-a8c8-28b9034fadbc",
      "mail": "admin@contoso.com",
      "assignedLicenses": [
        {
          "disabledPlans": [],
          "skuId": "cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46"
        }
      ]
    },
    {
      "id": "81a133c2-bdf2-4e67-8755-7264366b04ee",
      "mail": "DebraB@contoso.com",
      "assignedLicenses": [
        {
          "disabledPlans": [],
          "skuId": "cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46"
        }
      ]
    }
  ]
}

示例 10：获取所有用户的架构扩展的值

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

请求

GET https://graph.microsoft.com/v1.0/users?$select=ext55gb1l09_msLearnCourses

响应

在以下响应中，在两个用户对象未分配架构扩展属性 ext55gb1l09_msLearnCourses。

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

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

请注意: 还可以对架构扩展属性应用 $filter 以检索集合中属性与指定值匹配的对象。 语法为 /users?$filter={schemaPropertyID}/{propertyName} eq 'value'。 例如，GET /users?$select=ext55gb1l09_msLearnCourses&$filter=ext55gb1l09_msLearnCourses/courseType eq 'Developer'。 支持 eq 和 not 运算符。

示例 11：获取用户，包括其上次登录时间

请求

以下示例显示了一个请求。 signInActivity 属性的详细信息需要Microsoft Entra ID P1 或 P2 许可证以及 AuditLog.Read.All 权限。

注意： 在列出用户时指定 $select=signInActivity 或 $filter=signInActivity 时，的最大页面大小 $top 为 120。 $top设置为高于 120 的请求将返回最多 120 个用户的页面。 signInActivity 支持 $filter (eq、ne、、 lenotge) 但不支持任何其他可筛选属性。

GET https://graph.microsoft.com/v1.0/users?$select=displayName,userPrincipalName,signInActivity

响应

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

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

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(displayName,userPrincipalName,signInActivity)",
  "value": [
    {
      "displayName": "Adele Vance",
      "userPrincipalName": "AdeleV@contoso.com",
      "id": "1aecaf40-dc3a-461f-88a8-d06994e12898",
      "signInActivity": {
        "lastSignInDateTime": "2021-06-17T16:41:33Z",
        "lastSignInRequestId": "d4d31c40-4c36-4775-ad59-7d1e6a171f00",
        "lastNonInteractiveSignInDateTime": "0001-01-01T00:00:00Z",
        "lastNonInteractiveSignInRequestId": ""
      }
    },
    {
      "displayName": "Alex Wilber",
      "userPrincipalName": "AlexW@contoso.com",
      "id": "f0662ee5-84b1-43d6-8338-769cce1bc141",
      "signInActivity": {
        "lastSignInDateTime": "2021-07-29T15:53:27Z",
        "lastSignInRequestId": "f3149ee1-e347-4181-b45b-99a1f82b1c00",
        "lastNonInteractiveSignInDateTime": "2021-07-29T17:53:42Z",
        "lastNonInteractiveSignInRequestId": "868efa6a-b2e9-40e9-9b1c-0aaea5b50200"
      }
    }
  ]
}