使用查询参数自定义响应

项目
03/21/2024

Microsoft Graph 支持可选的查询参数，可用于指定和控制响应中返回的数据量。对准确查询参数的支持因 API 操作不同而不同，并且可能会在 v1.0 和数据终结点之间不同，具体取决于 API。

提示

在 beta 终结点上，$ 前缀是可选的。例如，可使用 filter 来代替 $filter。在 v1 终结点上, $前缀仅对 API 的一个子集是可选的。为简单起见, 如果使用 v1 终结点, 请始终包含$。

查询参数可以是 OData 系统查询选项，也可以是其他查询参数。

OData 系统查询选项

Microsoft Graph API 操作可以支持以下一个或多个 OData 系统查询选项。这些查询选项与 OData V4 查询语言兼容，并且仅在 GET 操作中受支持。

单击示例可以在 Graph 浏览器中试调用它们。

名称	说明	示例
$count	检索匹配资源的总数。	`/me/messages?$top=2&$count=true`
$expand	检索相关资源。	`/groups?$expand=members`
$filter	筛选结果（行）。	`/users?$filter=startswith(givenName,'J')`
$format	返回指定媒体格式的结果。	`/users?$format=json`
$orderby	对结果进行排序。	`/users?$orderby=displayName desc`
$search	返回基于搜索条件的结果。	`/me/messages?$search=pizza`
$select	筛选属性（列）。	`/users?$select=givenName,surname`
$skip	结果集中的索引。此外，某些 API 也用于实现分页，并且可以与 `$top` 一起使用来手动对结果进行分页。	`/me/messages?$skip=11`
$top	设置结果的页面大小。	`/users?$top=2`

若要了解 API 及其属性支持的 OData 系统查询选项，请参阅资源页中的属性表，以及 API 的 LIST 和 GET 操作部分可选查询参数。

其他查询参数

名称	说明	示例
$skipToken	从跨多页的结果集中检索下一页结果。 (某些 API 改用 `$skip` 。)	`/users?$skiptoken=X%274453707402000100000017...`

其他 OData URL 功能

下列 OData 4.0 功能是 URL 区段，不是查询参数。

名称	说明	示例
$count	检索集合的整数总计。	`GET /users/$count` `GET /groups/{id}/members/$count`
$ref	更新实体成员身份至集合。	`POST /groups/{id}/members/$ref`
$value	检索或更新项的二进制值。	`GET /me/photo/$value`
$batch	将多个 HTTP 请求合并到批处理请求中。	`POST /$batch`

对查询参数进行编码

查询参数的值应按照 RFC 3986 进行百分比编码。例如，查询字符串中的所有保留字符都必须采用百分比编码。许多 HTTP 客户端、浏览器和工具（如 Graph 浏览器）将在这方面帮助你。如果查询失败，可能原因之一是未正确编码查询参数值。在某些情况下，可能需要对值进行双重编码。

注意

终结点表达式v1.0中的$search编码和 (&) 符号存在已知问题。有关此问题和建议的解决方法的详细信息，请参阅已知问题：目录对象的$search编码和和 (&) 字符失败。

例如，未编码的 URL 如下所示：

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName, 'J')


// 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 = "startswith(givenName, 'J')";
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "startswith(givenName, 'J')"



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 := "startswith(givenName, 'J')"

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().Get(context.Background(), configuration)


// 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 = "startswith(givenName, 'J')";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('startswith(givenName, \'J\')')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "startswith(givenName, 'J')";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "startswith(givenName, 'J')"


from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "startswith(givenName, 'J')",
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

正确百分比编码的 URL 如下所示：

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(givenName%2C+'J')


// 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 = "startswith(givenName, 'J')";
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "startswith(givenName, 'J')"



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 := "startswith(givenName, 'J')"

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().Get(context.Background(), configuration)


// 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 = "startswith(givenName, 'J')";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('startswith(givenName, \'J\')')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "startswith(givenName, 'J')";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "startswith(givenName, 'J')"


from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "startswith(givenName, 'J')",
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

双重编码的 URL 如下所示：

GET https://graph.microsoft.com/v1.0/users?$filter=startswith%28givenName%2C%20%27J%27%29


// 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 = "startswith(givenName, 'J')";
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "startswith(givenName, 'J')"



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 := "startswith(givenName, 'J')"

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().Get(context.Background(), configuration)


// 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 = "startswith(givenName, 'J')";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('startswith(givenName, \'J\')')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "startswith(givenName, 'J')";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "startswith(givenName, 'J')"


from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "startswith(givenName, 'J')",
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

转义单引号

对于使用单引号的请求，如果任何参数值也包含单引号，则必须进行双转义；否则，由于语法无效，请求将失败。在示例中，字符串值 let''s meet for lunch? 进行了单引号转义。

GET https://graph.microsoft.com/v1.0/me/messages?$filter=subject eq 'let''s meet for lunch?'


// 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.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "subject eq 'let''s meet for lunch?'";
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users messages list --user-id {user-id} --filter "subject eq 'let''s meet for lunch?'"



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 := "subject eq 'let''s meet for lunch?'"

requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
	requestConfiguration.queryParameters.filter = "subject eq 'let''s meet for lunch?'";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.filter('subject eq \'let\'\'s meet for lunch?\'')
	.get();


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


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

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "subject eq 'let''s meet for lunch?'";
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Filter "subject eq 'let''s meet for lunch?'"


from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		filter = "subject eq 'let''s meet for lunch?'",
)

request_configuration = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.messages.get(request_configuration = request_configuration)

count 参数

使用 $count 查询参数检索集合中的项总数或与表达式匹配的项总数。可以通过以下方式使用 $count：

作为查询字符串参数，其语法 $count=true 包括集合中项总数的计数以及从 Microsoft Graph 返回的数据值页。例如，users?$count=true。
作为 URL 段，仅检索集合的整数总计。例如，users/$count。
在具有等式运算符的 $filter 表达式中，检索筛选属性为空集合的数据集合。请参阅使用 $filter 查询参数筛选对象的集合。

注意

在派生自 directoryObject 的资源上，仅在高级查询中支持 $count。请参阅目录对象的高级查询功能。
Azure AD B2C 租户不支持使用$count。

例如，下面的请求返回当前用户的 contact 集合，以及 @odata.count 属性中 contact 集合内的项数。

GET  https://graph.microsoft.com/v1.0/me/contacts?$count=true


// 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.Contacts.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Count = true;
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users contacts list --user-id {user-id} --count "true"



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestCount := true

requestParameters := &graphusers.ItemContactsRequestBuilderGetQueryParameters{
	Count: &requestCount,
}
configuration := &graphusers.ItemContactsRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

contacts, err := graphClient.Me().Contacts().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ContactCollectionResponse result = graphClient.me().contacts().get(requestConfiguration -> {
	requestConfiguration.queryParameters.count = true;
});


const options = {
	authProvider,
};

const client = Client.init(options);

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


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


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

$requestConfiguration = new ContactsRequestBuilderGetRequestConfiguration();
$queryParameters = ContactsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.PersonalContacts

# A UPN can also be used as -UserId.
Get-MgUserContact -UserId $userId -CountVariable CountVar


from msgraph import GraphServiceClient
from msgraph.generated.users.item.contacts.contacts_request_builder import ContactsRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = ContactsRequestBuilder.ContactsRequestBuilderGetQueryParameters(
		count = True,
)

request_configuration = ContactsRequestBuilder.ContactsRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.contacts.get(request_configuration = request_configuration)

$count查询参数支持以下常用资源集合和派生自directoryObject的关系，而且仅在高级查询中支持：

expand 参数

许多 Microsoft Graph 资源都会公开资源的已声明属性以及与其他资源的关系。这些关系也称为引用属性或导航属性，它们可以引用单个资源或资源集合。例如，用户的邮件文件夹、管理者和直接下属都将作为关系公开。

通常情况下，可以在单个请求中查询资源属性或其关系之一，但不能同时查询。可以使用 $expand 查询字符串参数以包含结果中单个关系（导航属性）引用的扩展资源或集合。在单个请求中只能扩展一个关系。

以下示例在驱动器中获取根驱动器信息以及顶级子项：

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children


// 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.Drives["{drive-id}"].Root.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Expand = new string []{ "children" };
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc drives root get --drive-id {drive-id} --expand "children"



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphdrives.DriveItemRootRequestBuilderGetQueryParameters{
	Expand: [] string {"children"},
}
configuration := &graphdrives.DriveItemRootRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

root, err := graphClient.Drives().ByDriveId("drive-id").Root().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

DriveItem result = graphClient.drives().byDriveId("{drive-id}").root().get(requestConfiguration -> {
	requestConfiguration.queryParameters.expand = new String []{"children"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let driveItem = await client.api('/me/drive/root')
	.expand('children')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Root\RootRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new RootRequestBuilderGetRequestConfiguration();
$queryParameters = RootRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->expand = ["children"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->drives()->byDriveId('drive-id')->root()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Files

Get-MgDriveRoot -DriveId $driveId -ExpandProperty "children"


from msgraph import GraphServiceClient
from msgraph.generated.drives.item.root.root_request_builder import RootRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = RootRequestBuilder.RootRequestBuilderGetQueryParameters(
		expand = ["children"],
)

request_configuration = RootRequestBuilder.RootRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.drives.by_drive_id('drive-id').root.get(request_configuration = request_configuration)

对于某些资源集合，还可以通过添加 $select 参数来指定要在扩展的资源中返回的属性。以下示例执行与上一示例相同的查询，但使用语句 $select 将为展开的子项返回的属性限制为 id 和名称属性。

GET https://graph.microsoft.com/v1.0/me/drive/root?$expand=children($select=id,name)


// 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.Drives["{drive-id}"].Root.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Expand = new string []{ "children($select=id,name)" };
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc drives root get --drive-id {drive-id} --expand "children(\$select=id,name)"



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphdrives.DriveItemRootRequestBuilderGetQueryParameters{
	Expand: [] string {"children($select=id,name)"},
}
configuration := &graphdrives.DriveItemRootRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

root, err := graphClient.Drives().ByDriveId("drive-id").Root().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

DriveItem result = graphClient.drives().byDriveId("{drive-id}").root().get(requestConfiguration -> {
	requestConfiguration.queryParameters.expand = new String []{"children($select=id,name)"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let driveItem = await client.api('/me/drive/root')
	.expand('children($select=id,name)')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Drives\Item\Root\RootRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new RootRequestBuilderGetRequestConfiguration();
$queryParameters = RootRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->expand = ["children(\$select=id,name)"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->drives()->byDriveId('drive-id')->root()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Files

Get-MgDriveRoot -DriveId $driveId -ExpandProperty "children(`$select=id,name)"


from msgraph import GraphServiceClient
from msgraph.generated.drives.item.root.root_request_builder import RootRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = RootRequestBuilder.RootRequestBuilderGetQueryParameters(
		expand = ["children($select=id,name)"],
)

request_configuration = RootRequestBuilder.RootRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.drives.by_drive_id('drive-id').root.get(request_configuration = request_configuration)

注意

并不是所有关系和资源都支持 $expand 查询参数。例如，可以展开一个用户的 directReports、 manager和 memberOf 关系，但不能展开其 events、 messages或 photos 关系。并非所有资源或关系都支持在扩展项上使用 $select。
使用Microsoft Entra派生自 directoryObject 的资源（如用户和组$expand），通常最多返回 20 个扩展关系的项，并且没有@odata.nextLink。有关详细信息，请参阅查询参数限制。
高级查询当前不支持$expand。

filter 参数

使用 $filter 查询参数，以仅检索集合的子集。有关使用 $filter的指导，请参阅使用 $filter 查询参数筛选对象的集合。

format 参数

使用 $format 查询参数，指定 Microsoft Graph 返回的项的媒体格式。

例如，下面的请求以 json 格式返回组织中的用户：

GET https://graph.microsoft.com/v1.0/users?$format=json


// 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.Format = "json";
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestFormat := "json"

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Format: &requestFormat,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().Get(context.Background(), configuration)


// 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.format = "json";
});


const options = {
	authProvider,
};

const client = Client.init(options);

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


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->format = "json";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -Format "json"


from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		format = "json",
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

注意

$format 查询参数支持许多格式（例如，atom、xml 和 json），但可能无法返回所有格式的结果。

orderby 参数

使用 $orderby 查询参数指定从 Microsoft Graph 返回的项的排序顺序。默认顺序为升序。

例如，以下请求返回按用户显示名称进行排序的组织中的用户：

GET https://graph.microsoft.com/v1.0/users?$orderby=displayName


// 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.Orderby = new string []{ "displayName" };
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --orderby "displayName"



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{
	Orderby: [] string {"displayName"},
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().Get(context.Background(), configuration)


// 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.orderby = new String []{"displayName"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.orderby('displayName')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\UsersRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->orderby = ["displayName"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Users

Get-MgUser -Sort "displayName"


from msgraph import GraphServiceClient
from msgraph.generated.users.users_request_builder import UsersRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		orderby = ["displayName"],
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

你还可以按复杂的类型实体进行排序。以下请求获取邮件，并按 from 属性的地址字段（属于复杂类型 emailAddress）对其进行排序：

GET https://graph.microsoft.com/v1.0/me/messages?$orderby=from/emailAddress/address


// 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.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Orderby = new string []{ "from/emailAddress/address" };
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users messages list --user-id {user-id} --orderby "from/emailAddress/address"



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.ItemMessagesRequestBuilderGetQueryParameters{
	Orderby: [] string {"from/emailAddress/address"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
	requestConfiguration.queryParameters.orderby = new String []{"from/emailAddress/address"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.orderby('from/emailAddress/address')
	.get();


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


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

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->orderby = ["from/emailAddress/address"];
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Sort "from/emailAddress/address"


from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		orderby = ["from/emailAddress/address"],
)

request_configuration = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.messages.get(request_configuration = request_configuration)

若要以升序或降序对结果进行排序，请向字段名称追加 asc 或 desc，并用空格隔开。例如，?$orderby=name%20desc。如果未指定排序顺序，则推断默认值(升序)。

通过一些 API，可以对多个属性的结果进行排序。例如，以下请求首先按发件人名称以降序（Z 到 A）排序用户收件箱中的邮件，然后按主题以升序（默认）排序邮件。

GET https://graph.microsoft.com/v1.0/me/mailFolders/Inbox/messages?$orderby=from/emailAddress/name desc,subject


// 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.MailFolders["{mailFolder-id}"].Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Orderby = new string []{ "from/emailAddress/name desc","subject" };
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users mail-folders messages list --user-id {user-id} --mail-folder-id {mailFolder-id} --orderby "from/emailAddress/name desc,subject"



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.ItemMailFolderItemMessagesRequestBuilderGetQueryParameters{
	Orderby: [] string {"from/emailAddress/name desc","subject"},
}
configuration := &graphusers.ItemMailFolderItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

messages, err := graphClient.Me().MailFolders().ByMailFolderId("mailFolder-id").Messages().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

MessageCollectionResponse result = graphClient.me().mailFolders().byMailFolderId("{mailFolder-id}").messages().get(requestConfiguration -> {
	requestConfiguration.queryParameters.orderby = new String []{"from/emailAddress/name desc", "subject"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/mailFolders/Inbox/messages')
	.orderby('from/emailAddress/name desc,subject')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\MailFolders\Item\Messages\MessagesRequestBuilderGetRequestConfiguration;


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

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->orderby = ["from/emailAddress/name desc","subject"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->me()->mailFolders()->byMailFolderId('mailFolder-id')->messages()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMailFolderMessage -UserId $userId -MailFolderId $mailFolderId -Sort "from/emailAddress/name desc,subject"


from msgraph import GraphServiceClient
from msgraph.generated.users.item.mailFolders.item.messages.messages_request_builder import MessagesRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		orderby = ["from/emailAddress/name desc","subject"],
)

request_configuration = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.mail_folders.by_mail_folder_id('mailFolder-id').messages.get(request_configuration = request_configuration)

注意

指定 $filter 服务器将推断结果的排序顺序。如果同时使用 $orderby 和 $filter 获取消息，因为服务器始终会推断 $filter 结果的排序顺序，必须以特定的方式指定属性。

下面的示例展示了如何按 subject 和 importance 属性筛选查询，再按 subject、importance 和 receivedDateTime 属性进行降序排序。

GET https://graph.microsoft.com/v1.0/me/messages?$filter=Subject eq 'welcome' and importance eq 'normal'&$orderby=subject,importance,receivedDateTime desc


// 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.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "Subject eq 'welcome' and importance eq 'normal'";
	requestConfiguration.QueryParameters.Orderby = new string []{ "subject","importance","receivedDateTime desc" };
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users messages list --user-id {user-id} --filter "Subject eq 'welcome' and importance eq 'normal'" --orderby "subject,importance,receivedDateTime desc"



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 := "Subject eq 'welcome' and importance eq 'normal'"

requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
	Orderby: [] string {"subject","importance","receivedDateTime desc"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
	requestConfiguration.queryParameters.filter = "Subject eq 'welcome' and importance eq 'normal'";
	requestConfiguration.queryParameters.orderby = new String []{"subject", "importance", "receivedDateTime desc"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.filter('Subject eq \'welcome\' and importance eq \'normal\'')
	.orderby('subject,importance,receivedDateTime desc')
	.get();


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


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

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "Subject eq 'welcome' and importance eq 'normal'";
$queryParameters->orderby = ["subject","importance","receivedDateTime desc"];
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Filter "Subject eq 'welcome' and importance eq 'normal'" -Sort "subject,importance,receivedDateTime desc"


from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		filter = "Subject eq 'welcome' and importance eq 'normal'",
		orderby = ["subject","importance","receivedDateTime desc"],
)

request_configuration = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.messages.get(request_configuration = request_configuration)

注意

目录对象支持组合 $orderby 和 $filter 查询参数。请参阅目录对象中的高级查询功能。

search 参数

使用 $search 查询参数限制与搜索条件匹配的请求结果。它的语法和行为因 API 操作而异。若要查看不同资源之间 $search 的语法，请参阅使用$search查询参数匹配搜索条件。

select 参数

使用 $select 查询参数返回一组不同于单个资源的默认集或资源集合的属性。使用 $select，可以指定默认属性的子集或超集。

在不使用来限制属性数据量的情况下 $select 发出 GET 请求时，Microsoft Graph 会包含 一个 @microsoft.graph.tips 属性，该属性提供了使用 $select 类似以下消息的最佳做法建议：

"@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET groups?$select=appMetadata,assignedLabels",

例如，检索登录用户的邮件时，可以指定仅返回 from 和 subject 属性：

GET https://graph.microsoft.com/v1.0/me/messages?$select=from,subject


// 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.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "from","subject" };
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users messages list --user-id {user-id} --select "from,subject"



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.ItemMessagesRequestBuilderGetQueryParameters{
	Select: [] string {"from","subject"},
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"from", "subject"};
});


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.select('from,subject')
	.get();


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


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

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["from","subject"];
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Property "from,subject"


from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		select = ["from","subject"],
)

request_configuration = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.messages.get(request_configuration = request_configuration)

重要

一般来说，建议使用 $select 将查询返回的属性限制为应用所需的属性。这对于可能返回大型结果集的查询尤为有用。限制每行返回的属性将减少网络负载并帮助提升应用的性能。

在中v1.0，某些 Microsoft Entra派生自 directoryObject 的资源（如用户和组）在读取时返回有限的默认属性子集。对于这些资源，必须使用 $select 返回默认集之外的属性。

skip 参数

$skip使用查询参数可设置集合开始时要跳过的项数。例如，以下请求返回按创建日期排序的用户的事件，从集合中的第 21 个事件开始：

GET  https://graph.microsoft.com/v1.0/me/events?$orderby=createdDateTime&$skip=20


// 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.Events.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Orderby = new string []{ "createdDateTime" };
	requestConfiguration.QueryParameters.Skip = 20;
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users events list --user-id {user-id} --skip "20" --orderby "createdDateTime"



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestSkip := int32(20)

requestParameters := &graphusers.ItemEventsRequestBuilderGetQueryParameters{
	Orderby: [] string {"createdDateTime"},
	Skip: &requestSkip,
}
configuration := &graphusers.ItemEventsRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

events, err := graphClient.Me().Events().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

EventCollectionResponse result = graphClient.me().events().get(requestConfiguration -> {
	requestConfiguration.queryParameters.orderby = new String []{"createdDateTime"};
	requestConfiguration.queryParameters.skip = 20;
});


const options = {
	authProvider,
};

const client = Client.init(options);

let events = await client.api('/me/events')
	.orderby('createdDateTime')
	.skip(20)
	.get();


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


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

$requestConfiguration = new EventsRequestBuilderGetRequestConfiguration();
$queryParameters = EventsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->orderby = ["createdDateTime"];
$queryParameters->skip = 20;
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Calendar

# A UPN can also be used as -UserId.
Get-MgUserEvent -UserId $userId -Sort "createdDateTime" -Skip 20


from msgraph import GraphServiceClient
from msgraph.generated.users.item.events.events_request_builder import EventsRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = EventsRequestBuilder.EventsRequestBuilderGetQueryParameters(
		orderby = ["createdDateTime"],
		skip = 20,
)

request_configuration = EventsRequestBuilder.EventsRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.events.get(request_configuration = request_configuration)

某些Microsoft Graph API, 如 Outlook 邮件和日历（邮件、事件和日历）使用 $skip 实现分页。当查询结果跨多个页面时，这些 API 会返回 @odata:nextLink 属性，具有包含 $skip 参数的 URL。可以使用此 URL 返回下一页结果。若要了解详细信息，请参阅分页。

用户、组和应用程序等目录对象不支持 $skip。

skipToken 参数

由于服务器端分页或由于使用 $top 参数来限制响应的页面大小，致使一些请求返回多页数据。许多 Microsoft Graph API 使用 skipToken 查询参数来引用结果的后续页面。
$skiptoken 参数包含引用下一页结果的不透明令牌，并在响应的 @odata.nextLink 属性中提供的 URL 中返回。若要了解详细信息，请参阅分页。

注意

如果对目录对象的查询使用 OData Count（在查询字符串中添加 $count=true ），则 @odata.count 属性仅在第一页中显示。

默认情况下，针对目录对象的高级查询所需的 ConsistencyLevel 标头不包含在后续页面请求中。必须在后续页面中显式设置它。

top 参数

$top使用查询参数指定要包含在结果中的项数。

如果结果集中还剩余多个项目，则响应正文将包含 @odata.nextLink 参数。此参数包含可用于获取下一页结果的 URL。若要了解详细信息，请参阅分页。

最小值为 $top 1，最大值取决于相应的 API。

例如，以下列表请求返回用户邮箱中的前五条消息：

GET https://graph.microsoft.com/v1.0/me/messages?$top=5


// 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.Messages.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Top = 5;
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users messages list --user-id {user-id} --top "5"



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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestTop := int32(5)

requestParameters := &graphusers.ItemMessagesRequestBuilderGetQueryParameters{
	Top: &requestTop,
}
configuration := &graphusers.ItemMessagesRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

messages, err := graphClient.Me().Messages().Get(context.Background(), configuration)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

MessageCollectionResponse result = graphClient.me().messages().get(requestConfiguration -> {
	requestConfiguration.queryParameters.top = 5;
});


const options = {
	authProvider,
};

const client = Client.init(options);

let messages = await client.api('/me/messages')
	.top(5)
	.get();


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


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

$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->top = 5;
$requestConfiguration->queryParameters = $queryParameters;


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


Import-Module Microsoft.Graph.Mail

# A UPN can also be used as -UserId.
Get-MgUserMessage -UserId $userId -Top 5


from msgraph import GraphServiceClient
from msgraph.generated.users.item.messages.messages_request_builder import MessagesRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = MessagesRequestBuilder.MessagesRequestBuilderGetQueryParameters(
		top = 5,
)

request_configuration = MessagesRequestBuilder.MessagesRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.me.messages.get(request_configuration = request_configuration)

注意

默认情况下，针对目录对象的高级查询所需的 ConsistencyLevel 标头不包含在后续页面请求中。必须在后续页面中显式设置它。

查询参数的错误处理

如果不支持指定的查询参数，某些请求将返回错误消息。例如，不能对user/photo关系使用 $expand 。

https://graph.microsoft.com/v1.0/me?$expand=photo

{
    "error":{
        "code":"ExpandNotSupported",
        "message":"Expand is not allowed for property 'Photo' according to the entity schema.",
        "innerError":{
            "request-id":"1653fefd-bc31-484b-bb10-8dc33cb853ec",
            "date":"2017-07-31T20:55:01"
        }
    }
}

但是，值得注意的是请求中指定的查询参数可能会自行失败。不支持的查询参数以及不支持的查询参数组合的情况就是如此。在这些情况下，应检查请求返回的数据，以确定指定的查询参数是否具有所需的效果。

使用查询参数自定义响应

OData 系统查询选项

其他查询参数

其他 OData URL 功能

对查询参数进行编码

转义单引号

count 参数

expand 参数

filter 参数

format 参数

orderby 参数

search 参数

select 参数

skip 参数

skipToken 参数

top 参数

查询参数的错误处理

反馈

反馈

其他资源

使用查询参数自定义响应

OData 系统查询选项

其他查询参数

其他 OData URL 功能

对查询参数进行编码

转义单引号

count 参数

expand 参数

filter 参数

format 参数

orderby 参数

search 参数

select 参数

skip 参数

skipToken 参数

top 参数

查询参数的错误处理

相关内容

反馈

反馈

其他资源