列出用户List users

命名空间:microsoft.graphNamespace: microsoft.graph

检索 user 对象列表。Retrieve a list of user objects.

PermissionsPermissions

要调用此 API,需要以下权限之一。要了解详细信息,包括如何选择权限的信息,请参阅权限One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

权限类型Permission type 权限(从最低特权到最高特权)Permissions (from least to most privileged)
委派(工作或学校帐户)Delegated (work or school account) User.ReadBasic.All、User.Read.All、User.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.All、Directory.AccessAsUser.AllUser.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All, Directory.AccessAsUser.All
委派(个人 Microsoft 帐户)Delegated (personal Microsoft account) 不支持。Not supported.
应用程序Application User.Read.All、User.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.AllUser.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

HTTP 请求HTTP request

GET /users

可选的查询参数Optional query parameters

此方法支持 OData 查询参数 来帮助自定义响应。This method supports the OData Query Parameters to help customize the response.

默认情况下,仅返回一组有限的属性(businessPhonesdisplayNamegivenNameidjobTitlemailmobilePhoneofficeLocationpreferredLanguagesurnameuserPrincipalName)。By default, only a limited set of properties are returned (businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, and userPrincipalName).

若要返回其他属性,请使用 OData $select 查询参数指定所需的一组 user 属性。To return an alternative property set, specify the desired set of user properties using the OData $select query parameter. 例如,若要返回 displayNamegivenNamepostalCode,请将以下项添加到查询 $select=displayName,givenName,postalCodeFor example, to return displayName, givenName, and postalCode, add the following to your query $select=displayName,givenName,postalCode.

某些属性无法在用户集合中返回。Certain properties cannot be returned within a user collection. 以下属性仅在检索单个用户时受支持:aboutMebirthdayhireDateinterestsmySitepastProjectspreferredNameresponsibilitiesschoolsskillsmailboxSettingsThe following properties are only supported when retrieving an single user: aboutMe, birthday, hireDate, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills, mailboxSettings.

请求标头Request headers

标头Header Value
AuthorizationAuthorization Bearer {token}(必需)Bearer {token} (required)

请求正文Request body

请勿提供此方法的请求正文。Do not supply a request body for this method.

响应Response

如果成功,此方法在响应正文中返回 200 OK 响应代码和 user 对象集合。If successful, this method returns a 200 OK response code and collection of user objects in the response body. 如果返回大的用户集,则可以在应用中使用分页If a large user collection is returned, you can use paging in your app.

示例Examples

示例 1:标准用户请求Example 1: Standard users request

默认情况下,仅返回一组有限的属性(businessPhonesdisplayNamegivenNameidjobTitlemailmobilePhoneofficeLocationpreferredLanguagesurnameuserPrincipalName)。By default, only a limited set of properties are returned (businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, userPrincipalName). 此示例展示了默认请求和响应。This example illustrates the default request and response.

请求Request
GET https://graph.microsoft.com/v1.0/users
响应Response
HTTP/1.1 200 OK
Content-type: application/json
Content-length: 608

{
  "value": [
    {
      "businessPhones": [
        "businessPhones-value"
      ],
      "displayName": "displayName-value",
      "givenName": "givenName-value",
      "jobTitle": "jobTitle-value",
      "mail": "mail-value",
      "mobilePhone": "mobilePhone-value",
      "officeLocation": "officeLocation-value",
      "preferredLanguage": "preferredLanguage-value",
      "surname": "surname-value",
      "userPrincipalName": "userPrincipalName-value",
      "id": "id-value"
    }
  ]
}

示例 2:使用 $select 的用户请求Example 2: Users request using $select

如果需要其他属性集,可以使用 OData $select 查询参数。If you need a different property set, you can use the OData $select query parameter. 例如,若要返回 displayNamegivenName、和 postalCode,则需要将以下项添加到查询 $select=displayName,givenName,postalCodeFor example, to return displayName, givenName, and postalCode, you would use the add the following to your query $select=displayName,givenName,postalCode.

请求Request
GET https://graph.microsoft.com/v1.0/users?$select=displayName,givenName,postalCode
响应Response

注意:为简洁起见,可能会截断此处显示的响应对象。Note: The response object shown here may be truncated for brevity.

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

{
  "value": [
    {
      "displayName": "displayName-value",
      "givenName": "givenName-value",
      "postalCode": "postalCode-value"
    }
  ]
}

示例 3:使用登录名查找用户帐户Example 3: Find a user account using a sign-in name

使用登录名(也称为本地帐户)在 B2C 租户中查找用户帐户。Find a user account in a B2C tenant, using a sign-in name (also known as a local account). 此请求可由技术支持人员用于在 B2C 租户中查找客户的用户帐户(此示例中,B2C 租户是 contoso.onmicrosoft.com)。This request can be used by a helpdesk to find a customer's user account, in a B2C tenant (in this example the B2C tenant is contoso.onmicrosoft.com).

备注

根据 identities 进行筛选时,必须同时提供 issuerissuerAssignedIdWhen filtering on identities, you must supply both issuer and issuerAssignedId.

请求Request

下面展示了示例请求。The following is an example of the request.

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 'contoso.onmicrosoft.com')

响应Response

下面展示了示例响应。The following is an example of the response.

注意: 为了提高可读性,可能缩短了此处显示的响应对象。所有属性都将通过实际调用返回。Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

{
  "value": [
    {
      "displayName": "John Smith",
      "id": "4c7be08b-361f-41a8-b1ef-1712f7a3dfb2"
    }
  ]
}