获取用户

项目
07/18/2022

命名空间：microsoft.graph

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

权限

要调用此 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 权限允许应用读取配置文件，并仅发现组成员身份、报表和经理等已登录用户的关系。

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

可选的查询参数

此方法支持 $select OData 查询参数检索特定用户属性，包括默认情况下未返回的属性。

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

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

检索扩展和关联数据

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

请求标头

标头	值
Authorization	Bearer {token}。必需。
Content-Type	application/json

请求正文

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

响应

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

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

示例

示例 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.onmicrosoft.com",
   "mobilePhone": "+1 425 555 0109",
   "officeLocation": "18/2111",
   "preferredLanguage": "en-US",
   "surname": "Vance",
   "userPrincipalName": "AdeleV@contoso.onmicrosoft.com",
   "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
}

示例 2：登录用户请求

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

请求

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


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var user = await graphClient.Me
    .Request()
    .GetAsync();


const options = {
    authProvider,
};

const client = Client.init(options);

let user = await client.api('/me')
    .get();


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/me"]]];
[urlRequest setHTTPMethod:@"GET"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        MSGraphUser *user = [[MSGraphUser alloc] initWithData:data error:&nserror];

}];

[meDataTask execute];


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

User user = graphClient.me()
    .buildRequest()
    .get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

result, err := graphClient.Me().Get()


Import-Module Microsoft.Graph.Users

# A UPN can also be used as -UserId.
Get-MgUser -UserId $userId

响应

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.onmicrosoft.com",
   "mobilePhone": "+1 425 555 0109",
   "officeLocation": "18/2111",
   "preferredLanguage": "en-US",
   "surname": "Vance",
   "userPrincipalName": "AdeleV@contoso.onmicrosoft.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/87d349ed-44d7-43e1-9a83-5f2406dee5bd?$select=displayName,givenName,postalCode,identities


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var user = await graphClient.Users["{user-id}"]
    .Request()
    .Select("displayName,givenName,postalCode,identities")
    .GetAsync();


const options = {
    authProvider,
};

const client = Client.init(options);

let user = await client.api('/users/{id | userPrincipalName}')
    .select('displayName,givenName,postalCode,identities')
    .get();


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/users/{id | userPrincipalName}?$select=displayName,givenName,postalCode,identities"]]];
[urlRequest setHTTPMethod:@"GET"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        MSGraphUser *user = [[MSGraphUser alloc] initWithData:data error:&nserror];

}];

[meDataTask execute];


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

User user = graphClient.users("{id | userPrincipalName}")
    .buildRequest()
    .select("displayName,givenName,postalCode,identities")
    .get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &msgraphsdk.UserRequestBuilderGetQueryParameters{
    Select: "displayName,givenName,postalCode,identities",
}
options := &msgraphsdk.UserRequestBuilderGetRequestConfiguration{
    QueryParameters: requestParameters,
}
userId := "user-id"
result, err := graphClient.UsersById(&userId).GetWithRequestConfigurationAndResponseHandler(options, nil)


Import-Module Microsoft.Graph.Users

Get-MgUser -UserId $userId -Property "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


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var user = await graphClient.Users["{user-id}"]
    .Request()
    .Select("ext55gb1l09_msLearnCourses")
    .GetAsync();


const options = {
    authProvider,
};

const client = Client.init(options);

let user = await client.api('/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e')
    .select('ext55gb1l09_msLearnCourses')
    .get();


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/schemaExtensions/graphlearn_test"]]];
[urlRequest setHTTPMethod:@"GET"];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        MSGraphSchemaExtension *schemaExtension = [[MSGraphSchemaExtension alloc] initWithData:data error:&nserror];

}];

[meDataTask execute];


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

User user = graphClient.users("4562bcc8-c436-4f95-b7c0-4f8ce89dca5e")
    .buildRequest()
    .select("ext55gb1l09_msLearnCourses")
    .get();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestParameters := &msgraphsdk.UserRequestBuilderGetQueryParameters{
    Select: "ext55gb1l09_msLearnCourses",
}
options := &msgraphsdk.UserRequestBuilderGetRequestConfiguration{
    QueryParameters: requestParameters,
}
userId := "user-id"
result, err := graphClient.UsersById(&userId).GetWithRequestConfigurationAndResponseHandler(options, nil)


Import-Module Microsoft.Graph.Users

Get-MgUser -UserId $userId -Property "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
    }
}