列出用户
本文内容
命名空间: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
和 $top
OData 查询参数 来帮助自定义响应。 不支持 $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
// 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.GetAsync();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
users, err := graphClient.Users().Get(context.Background(), nil)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
const options = {
authProvider,
};
const client = Client.init(options);
let users = await client.api('/users')
.get();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
<?php
use Microsoft\Graph\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$result = $graphServiceClient->users()->get()->wait();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
from msgraph import GraphServiceClient
graph_client = GraphServiceClient(credentials, scopes)
result = await graph_client.users.get()
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
响应
以下示例显示了相应的响应。
注意: 为了提高可读性,可能缩短了此处显示的响应对象。
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')
// 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.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "displayName","id" };
requestConfiguration.QueryParameters.Filter = "identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')";
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')" --select "displayName,id"
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestFilter := "identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')"
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Select: [] string {"displayName","id"},
Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
users, err := graphClient.Users().Get(context.Background(), configuration)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"displayName", "id"};
requestConfiguration.queryParameters.filter = "identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')";
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
const options = {
authProvider,
};
const client = Client.init(options);
let users = await client.api('/users')
.filter('identities/any(c:c/issuerAssignedId eq \'j.smith@yahoo.com\' and c/issuer eq \'My B2C tenant\')')
.select('displayName,id')
.get();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["displayName","id"];
$queryParameters->filter = "identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')";
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->users()->get($requestConfiguration)->wait();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
Import-Module Microsoft.Graph.Users
Get-MgUser -Property "displayName,id" -Filter "identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')"
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
select = ["displayName","id"],
filter = "identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')",
)
request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.get(request_configuration = request_configuration)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
响应
以下示例显示了相应的响应。
注意: 为了提高可读性,可能缩短了此处显示的响应对象。
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
// 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
await graphClient.Users.Count.GetAsync((requestConfiguration) =>
{
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users count get --consistency-level "eventual"
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")
configuration := &graphusers.Users$countRequestBuilderGetRequestConfiguration{
Headers: headers,
}
graphClient.Users().Count().Get(context.Background(), configuration)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
graphClient.users().count().get(requestConfiguration -> {
requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
const options = {
authProvider,
};
const client = Client.init(options);
let int32 = await client.api('/users/$count')
.header('ConsistencyLevel','eventual')
.get();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\$count\CountRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new CountRequestBuilderGetRequestConfiguration();
$headers = [
'ConsistencyLevel' => 'eventual',
];
$requestConfiguration->headers = $headers;
$graphServiceClient->users()->count()->get($requestConfiguration)->wait();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
from msgraph import GraphServiceClient
from msgraph.generated.users.$count.count_request_builder import CountRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
request_configuration = CountRequestBuilder.CountRequestBuilderGetRequestConfiguration()
request_configuration.headers.add("ConsistencyLevel", "eventual")
await graph_client.users.count.get(request_configuration = request_configuration)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
响应
以下示例显示了相应的响应。
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"
}
]
}
请求
以下示例显示了一个请求。 此请求需要将 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
// 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.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Filter = "endswith(mail,'a@contoso.com')";
requestConfiguration.QueryParameters.Orderby = new string []{ "userPrincipalName" };
requestConfiguration.QueryParameters.Count = true;
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "endswith(mail,'a@contoso.com')" --count "true" --orderby "userPrincipalName" --consistency-level "eventual"
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")
requestFilter := "endswith(mail,'a@contoso.com')"
requestCount := true
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Filter: &requestFilter,
Orderby: [] string {"userPrincipalName"},
Count: &requestCount,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
Headers: headers,
QueryParameters: requestParameters,
}
users, err := graphClient.Users().Get(context.Background(), configuration)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.filter = "endswith(mail,'a@contoso.com')";
requestConfiguration.queryParameters.orderby = new String []{"userPrincipalName"};
requestConfiguration.queryParameters.count = true;
requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
const options = {
authProvider,
};
const client = Client.init(options);
let users = await client.api('/users')
.header('ConsistencyLevel','eventual')
.filter('endswith(mail,\'a@contoso.com\')')
.orderby('userPrincipalName')
.get();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$headers = [
'ConsistencyLevel' => 'eventual',
];
$requestConfiguration->headers = $headers;
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "endswith(mail,'a@contoso.com')";
$queryParameters->orderby = ["userPrincipalName"];
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->users()->get($requestConfiguration)->wait();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
Import-Module Microsoft.Graph.Users
Get-MgUser -Filter "endswith(mail,'a@contoso.com')" -Sort "userPrincipalName" -CountVariable CountVar -ConsistencyLevel eventual
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
filter = "endswith(mail,'a@contoso.com')",
orderby = ["userPrincipalName"],
count = True,
)
request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")
result = await graph_client.users.get(request_configuration = request_configuration)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
响应
以下示例显示了相应的响应。
注意: 为了提高可读性,可能缩短了此处显示的响应对象。
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
// 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.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Search = "\"displayName:wa\"";
requestConfiguration.QueryParameters.Orderby = new string []{ "displayName" };
requestConfiguration.QueryParameters.Count = true;
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --search ""displayName:wa"" --count "true" --orderby "displayName" --consistency-level "eventual"
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")
requestSearch := "\"displayName:wa\""
requestCount := true
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Search: &requestSearch,
Orderby: [] string {"displayName"},
Count: &requestCount,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
Headers: headers,
QueryParameters: requestParameters,
}
users, err := graphClient.Users().Get(context.Background(), configuration)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.search = "\"displayName:wa\"";
requestConfiguration.queryParameters.orderby = new String []{"displayName"};
requestConfiguration.queryParameters.count = true;
requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
const options = {
authProvider,
};
const client = Client.init(options);
let users = await client.api('/users')
.header('ConsistencyLevel','eventual')
.search('displayName:wa')
.orderby('displayName')
.get();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$headers = [
'ConsistencyLevel' => 'eventual',
];
$requestConfiguration->headers = $headers;
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->search = "\"displayName:wa\"";
$queryParameters->orderby = ["displayName"];
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->users()->get($requestConfiguration)->wait();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
Import-Module Microsoft.Graph.Users
Get-MgUser -Search '"displayName:wa"' -Sort "displayName" -CountVariable CountVar -ConsistencyLevel eventual
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
search = "\"displayName:wa\"",
orderby = ["displayName"],
count = True,
)
request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")
result = await graph_client.users.get(request_configuration = request_configuration)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
响应
以下示例显示了相应的响应。
注意: 为了提高可读性,可能缩短了此处显示的响应对象。
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
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --search ""displayName:wa" OR "displayName:ad"" --count "true" --consistency-level "eventual"
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
Import-Module Microsoft.Graph.Users
Get-MgUser -Search '"displayName:wa" OR "displayName:ad"' -Orderbydisplayname = -CountVariable CountVar -ConsistencyLevel eventual
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
响应
以下示例显示了相应的响应。
注意: 为了提高可读性,可能缩短了此处显示的响应对象。
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
// 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.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "id","displayName","mail","identities" };
requestConfiguration.QueryParameters.Filter = "endsWith(userPrincipalName,'";
requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "endsWith(userPrincipalName,'" --select "id,displayName,mail,identities" --consistency-level "eventual"
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")
requestFilter := "endsWith(userPrincipalName,'"
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Select: [] string {"id","displayName","mail","identities"},
Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
Headers: headers,
QueryParameters: requestParameters,
}
users, err := graphClient.Users().Get(context.Background(), configuration)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"id", "displayName", "mail", "identities"};
requestConfiguration.queryParameters.filter = "endsWith(userPrincipalName,'";
requestConfiguration.headers.add("ConsistencyLevel", "eventual");
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$headers = [
'ConsistencyLevel' => 'eventual',
];
$requestConfiguration->headers = $headers;
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["id","displayName","mail","identities"];
$queryParameters->filter = "endsWith(userPrincipalName,'";
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->users()->get($requestConfiguration)->wait();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
Import-Module Microsoft.Graph.Users
Get-MgUser -Property "id,displayName,mail,identities" -Filter "endsWith(userPrincipalName,'" -ConsistencyLevel eventual
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
select = ["id","displayName","mail","identities"],
filter = "endsWith(userPrincipalName,'",
)
request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")
result = await graph_client.users.get(request_configuration = request_configuration)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
响应
以下示例显示了相应的响应。
注意: 为了提高可读性,可能缩短了此处显示的响应对象。
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
// 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.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "ext55gb1l09_msLearnCourses" };
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --select "ext55gb1l09_msLearnCourses"
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Select: [] string {"ext55gb1l09_msLearnCourses"},
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
users, err := graphClient.Users().Get(context.Background(), configuration)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"ext55gb1l09_msLearnCourses"};
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
const options = {
authProvider,
};
const client = Client.init(options);
let users = await client.api('/users')
.select('ext55gb1l09_msLearnCourses')
.get();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["ext55gb1l09_msLearnCourses"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->users()->get($requestConfiguration)->wait();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
Import-Module Microsoft.Graph.Users
Get-MgUser -Property "ext55gb1l09_msLearnCourses"
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
select = ["ext55gb1l09_msLearnCourses"],
)
request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.get(request_configuration = request_configuration)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
响应
在以下响应中,在两个用户对象未分配架构扩展属性 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
、、 le
not
ge
) 但 不支持任何其他可筛选属性。
GET https://graph.microsoft.com/v1.0/users?$select=displayName,userPrincipalName,signInActivity
// 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.GetAsync((requestConfiguration) =>
{
requestConfiguration.QueryParameters.Select = new string []{ "displayName","userPrincipalName","signInActivity" };
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --select "displayName,userPrincipalName,signInActivity"
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
)
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
Select: [] string {"displayName","userPrincipalName","signInActivity"},
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
}
users, err := graphClient.Users().Get(context.Background(), configuration)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
UserCollectionResponse result = graphClient.users().get(requestConfiguration -> {
requestConfiguration.queryParameters.select = new String []{"displayName", "userPrincipalName", "signInActivity"};
});
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
const options = {
authProvider,
};
const client = Client.init(options);
let users = await client.api('/users')
.select('displayName,userPrincipalName,signInActivity')
.get();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["displayName","userPrincipalName","signInActivity"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->users()->get($requestConfiguration)->wait();
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
Import-Module Microsoft.Graph.Users
Get-MgUser -Property "displayName,userPrincipalName,signInActivity"
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder
graph_client = GraphServiceClient(credentials, scopes)
query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
select = ["displayName","userPrincipalName","signInActivity"],
)
request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
result = await graph_client.users.get(request_configuration = request_configuration)
有关如何将 SDK 添加 到项目并创建 authProvider 实例的详细信息,请参阅 SDK 文档 。
响应
以下示例显示了相应的响应。
注意: 为了提高可读性,可能缩短了此处显示的响应对象。
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"
}
}
]
}