获取用户

2024-12-24

命名空间：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

注意

权限 User.Read 允许应用读取配置文件，并仅发现组成员身份、报表和已登录用户的经理等关系。

特定方案的权限

读取 employeeLeaveDateTime 属性：
- 在委托方案中，登录用户至少需要以下Microsoft Entra角色之一：生命周期工作流管理员 (最低特权) 全局读取者;必须向应用授予 User-LifeCycleInfo.Read.All 委托权限。
- 在具有 Microsoft Graph 权限的仅限应用方案中，必须向应用授予 User-LifeCycleInfo.Read.All 权限。
读取 customSecurityAttributes 属性：
- 在委托方案中，必须为已登录用户分配 属性分配管理员 角色，并且应用被授予 CustomSecAttributeAssignment.Read.All 权限。
- 在具有 Microsoft Graph 权限的仅限应用方案中，必须向应用授予 CustomSecAttributeAssignment.Read.All 权限。
User-Mail.ReadWrite.All 是读取和写入 otherMails 属性的最低特权权限;还允许读取用户对象上的一些与标识符相关的属性。
User-PasswordProfile.ReadWrite.All 是读取和写入与密码重置相关的属性的最低特权权限;还允许读取用户对象上的一些与标识符相关的属性。
User-Phone.ReadWrite.All 是读取和写入 businessPhone 和 mobilePhone 属性的最低特权权限;还允许读取用户对象上的一些与标识符相关的属性。
User.EnableDisableAccount.All + User.Read.All 是读取和写入 accountEnabled 属性的权限的最低特权组合。

HTTP 请求

对于特定用户：

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

注意

调用 /me 终结点需要已登录的用户，因此需要委派权限。使用 /me 终结点时，不支持应用程序权限。

提示

当 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

注意

调用 /me 终结点需要已登录的用户，因此需要委派权限。使用 /me 终结点时，不支持应用程序权限。

可选的查询参数

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

默认情况下，仅返回一组有限的属性（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	持有者 {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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].GetAsync();



mgc users get --user-id {user-id}



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().ByUserId("user-id").Get(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

User result = graphClient.users().byUserId("{user-id}").get();


const options = {
	authProvider,
};

const client = Client.init(options);

let user = await client.api('/users/87d349ed-44d7-43e1-9a83-5f2406dee5bd')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->users()->byUserId('user-id')->get()->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -UserId $userId


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.users.by_user_id('user-id').get()

响应

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.GetAsync();



mgc users get --user-id {user-id}



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
me, err := graphClient.Me().Get(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

User result = graphClient.me().get();


const options = {
	authProvider,
};

const client = Client.init(options);

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


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->me()->get()->wait();


Import-Module Microsoft.Graph.Users

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


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.me.get()

响应

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 查询参数。例如，若要返回 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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","givenName","postalCode","identities" };
});



mgc users get --user-id {user-id} --select "displayName,givenName,postalCode,identities"



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

requestParameters := &graphusers.UserItemRequestBuilderGetQueryParameters{
	Select: [] string {"displayName","givenName","postalCode","identities"},
}
configuration := &graphusers.UserItemRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().ByUserId("user-id").Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

User result = graphClient.users().byUserId("{user-id}").get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"displayName", "givenName", "postalCode", "identities"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let user = await client.api('/users/87d349ed-44d7-43e1-9a83-5f2406dee5bd')
	.select('displayName,givenName,postalCode,identities')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\UserItemRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UserItemRequestBuilderGetRequestConfiguration();
$queryParameters = UserItemRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["displayName","givenName","postalCode","identities"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->byUserId('user-id')->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -UserId $userId -Property "displayName,givenName,postalCode,identities"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.user_item_request_builder import UserItemRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UserItemRequestBuilder.UserItemRequestBuilderGetQueryParameters(
		select = ["displayName","givenName","postalCode","identities"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.by_user_id('user-id').get(request_configuration = request_configuration)

响应

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "ext55gb1l09_msLearnCourses" };
});



mgc users get --user-id {user-id} --select "ext55gb1l09_msLearnCourses"



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

requestParameters := &graphusers.UserItemRequestBuilderGetQueryParameters{
	Select: [] string {"ext55gb1l09_msLearnCourses"},
}
configuration := &graphusers.UserItemRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().ByUserId("user-id").Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

User result = graphClient.users().byUserId("{user-id}").get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"ext55gb1l09_msLearnCourses"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

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


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\UserItemRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UserItemRequestBuilderGetRequestConfiguration();
$queryParameters = UserItemRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["ext55gb1l09_msLearnCourses"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->byUserId('user-id')->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -UserId $userId -Property "ext55gb1l09_msLearnCourses"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.user_item_request_builder import UserItemRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UserItemRequestBuilder.UserItemRequestBuilderGetQueryParameters(
		select = ["ext55gb1l09_msLearnCourses"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.by_user_id('user-id').get(request_configuration = request_configuration)

响应

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.All 或 CustomSecAttributeAssignment.ReadWrite.All 权限。

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

请求

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


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "customSecurityAttributes" };
});



mgc users get --user-id {user-id} --select "customSecurityAttributes"



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

requestParameters := &graphusers.UserItemRequestBuilderGetQueryParameters{
	Select: [] string {"customSecurityAttributes"},
}
configuration := &graphusers.UserItemRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
users, err := graphClient.Users().ByUserId("user-id").Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

User result = graphClient.users().byUserId("{user-id}").get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"customSecurityAttributes"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let user = await client.api('/users/{id}')
	.select('customSecurityAttributes')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\UserItemRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UserItemRequestBuilderGetRequestConfiguration();
$queryParameters = UserItemRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["customSecurityAttributes"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->byUserId('user-id')->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -UserId $userId -Property "customSecurityAttributes"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.user_item_request_builder import UserItemRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = UserItemRequestBuilder.UserItemRequestBuilderGetQueryParameters(
		select = ["customSecurityAttributes"],
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.by_user_id('user-id').get(request_configuration = request_configuration)

响应

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
}

通过