Microsoft Graph 支持可选的查询参数，可用于指定和控制响应中返回的数据量。 对准确查询参数的支持因 API 操作不同而不同，并且可能会在 v1.0 和数据终结点之间不同，具体取决于 API。
在 beta 终结点上，
$
前缀是可选的。 例如，可使用
filter
来代替
$filter
。
在 v1 终结点上,
$
前缀仅对 API 的一个子集是可选的。 为简单起见, 如果使用 v1 终结点, 请始终包含
$
。
查询参数可以是
OData 系统查询选项
，也可以是其他查询参数。
OData 系统查询选项
Microsoft Graph API 操作可以支持以下一个或多个 OData 系统查询选项。 这些查询选项与
OData V4 查询语言
兼容，并且仅在 GET 操作中受支持。
单击示例可以在
Graph 浏览器
中试调用它们。
对查询参数进行编码
查询参数的值应按照
RFC 3986
进行百分比编码。 例如，查询字符串中的所有保留字符都必须采用百分比编码。 许多 HTTP 客户端、浏览器和工具（如
Graph 浏览器
）将在这方面帮助你。 如果查询失败，可能原因之一是未正确编码查询参数值。 在某些情况下，可能需要对值进行双重编码。
例如，未编码的 URL 如下所示：
JavaScript
PowerShell
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
requestConfiguration.QueryParameters.Filter = "startswith(givenName,%20'J')";
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
UserCollectionPage users = graphClient.users()
.buildRequest()
.filter("startswith(givenName, 'J')")
.get();
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestFilter := "startswith(givenName,%20'J')"
requestParameters := &graphconfig.UsersRequestBuilderGetQueryParameters{
Filter: &requestFilter,
configuration := &graphconfig.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
result, err := graphClient.Users().Get(context.Background(), configuration)
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "startswith(givenName,%20'J')";
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->users()->get($requestConfiguration);
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
requestConfiguration.QueryParameters.Filter = "startswith(givenName,%20'J')";
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
UserCollectionPage users = graphClient.users()
.buildRequest()
.filter("startswith(givenName, 'J')")
.get();
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestFilter := "startswith(givenName,%20'J')"
requestParameters := &graphconfig.UsersRequestBuilderGetQueryParameters{
Filter: &requestFilter,
configuration := &graphconfig.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
result, err := graphClient.Users().Get(context.Background(), configuration)
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "startswith(givenName,%20'J')";
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->users()->get($requestConfiguration);
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
requestConfiguration.QueryParameters.Filter = "startswith(givenName,%20'J')";
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
UserCollectionPage users = graphClient.users()
.buildRequest()
.filter("startswith(givenName, 'J')")
.get();
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestFilter := "startswith(givenName,%20'J')"
requestParameters := &graphconfig.UsersRequestBuilderGetQueryParameters{
Filter: &requestFilter,
configuration := &graphconfig.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
result, err := graphClient.Users().Get(context.Background(), configuration)
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "startswith(givenName,%20'J')";
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->users()->get($requestConfiguration);
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
requestConfiguration.QueryParameters.Filter = "subject eq 'let''s meet for lunch?'";
let messages = await client.api('/me/messages')
.filter('subject eq \'let\'\'s meet for lunch?\'')
.get();
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
MessageCollectionPage messages = graphClient.me().messages()
.buildRequest()
.filter("subject eq 'let''s meet for lunch?'")
.get();
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestFilter := "subject eq 'let''s meet for lunch?'"
requestParameters := &graphconfig.ItemMessagesRequestBuilderGetQueryParameters{
Filter: &requestFilter,
configuration := &graphconfig.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
result, err := graphClient.Me().Messages().Get(context.Background(), configuration)
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "subject eq 'let''s meet for lunch?'";
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->me()->messages()->get($requestConfiguration);
使用
$count
查询参数检索集合中的项总数或与表达式匹配的项总数。 可以通过以下方式使用
$count
：
作为查询字符串参数，其语法
$count=true
包括集合中项总数的计数以及从 Microsoft Graph 返回的数据值页。 例如，
users?$count=true
。
作为
URL 段
，仅检索集合的整数总计。 例如，
users/$count
。
在具有等式运算符的
$filter
表达式中，检索筛选属性为空集合的数据集合。 请参阅
使用 $filter 查询参数筛选对象的集合
。
在派生自
directoryObject
的资源上，仅在高级查询中支持
$count
。 请参阅
Azure AD 目录对象的高级查询功能
。
Azure AD B2C 租户不支持使用
$count
。
例如，下面的请求返回当前用户的
contact
集合，以及
@odata.count
属性中
contact
集合内的项数。
JavaScript
PowerShell
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.Me.Contacts.GetAsync((requestConfiguration) =>
requestConfiguration.QueryParameters.Count = true;
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
ContactCollectionPage contacts = graphClient.me().contacts()
.buildRequest()
.get();
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestCount := true
requestParameters := &graphconfig.ItemContactsRequestBuilderGetQueryParameters{
Count: &requestCount,
configuration := &graphconfig.ItemContactsRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
result, err := graphClient.Me().Contacts().Get(context.Background(), configuration)
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new ContactsRequestBuilderGetRequestConfiguration();
$queryParameters = ContactsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->me()->contacts()->get($requestConfiguration);
expand 参数
许多 Microsoft Graph 资源都会公开资源的已声明属性以及与其他资源的关系。 这些关系也称为引用属性或导航属性，它们可以引用单个资源或资源集合。 例如，用户的邮件文件夹、管理者和直接下属都将作为关系公开。
通常情况下，可以在单个请求中查询资源属性或其关系之一，但不能同时查询。 可以使用
$expand
查询字符串参数以包含结果中单个关系（导航属性）引用的扩展资源或集合。 在单个请求中只能扩展一个关系。
以下示例在驱动器中获取根驱动器信息以及顶级子项：
JavaScript
PowerShell
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
DriveItem driveItem = graphClient.me().drive().root()
.buildRequest()
.expand("children")
.get();
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
DriveItem driveItem = graphClient.me().drive().root()
.buildRequest()
.expand("children($select=id,name)")
.get();
并不是所有关系和资源都支持
$expand
查询参数。 例如，可以展开一个用户的
directReports
、
manager
和
memberOf
关系，但不能展开其
events
、
messages
或
photos
关系。 并非所有资源或关系都支持在扩展项上使用
$select
。
使用派生自
directoryObject
的 Azure AD 资源(如
user
和
group
)，
$expand
通常最多为扩展关系返回 20 个项，并且没有
@odata.nextLink
。 请参阅更多
已知问题
。
高级查询
当前不支持
$expand
。
filter 参数
使用
$filter
查询参数，以仅检索集合的子集。 有关使用
$filter
的指导，请参阅
使用 $filter 查询参数筛选对象的集合
。
使用
$format
查询参数，指定 Microsoft Graph 返回的项的媒体格式。
例如，下面的请求以 json 格式返回组织中的用户：
JavaScript
PowerShell
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
requestConfiguration.QueryParameters.Format = "json";
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
UserCollectionPage users = graphClient.users()
.buildRequest()
.get();
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestFormat := "json"
requestParameters := &graphconfig.UsersRequestBuilderGetQueryParameters{
Format: &requestFormat,
configuration := &graphconfig.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
result, err := graphClient.Users().Get(context.Background(), configuration)
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->format = "json";
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->users()->get($requestConfiguration);
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.Users.GetAsync((requestConfiguration) =>
requestConfiguration.QueryParameters.Orderby = new string []{ "displayName" };
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
UserCollectionPage users = graphClient.users()
.buildRequest()
.orderBy("displayName")
.get();
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestParameters := &graphconfig.UsersRequestBuilderGetQueryParameters{
Orderby: [] string {"displayName"},
configuration := &graphconfig.UsersRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
result, err := graphClient.Users().Get(context.Background(), configuration)
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->orderby = ["displayName"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->users()->get($requestConfiguration);
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
requestConfiguration.QueryParameters.Orderby = new string []{ "from/emailAddress/address" };
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
MessageCollectionPage messages = graphClient.me().messages()
.buildRequest()
.orderBy("from/emailAddress/address")
.get();
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestParameters := &graphconfig.ItemMessagesRequestBuilderGetQueryParameters{
Orderby: [] string {"from/emailAddress/address"},
configuration := &graphconfig.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
result, err := graphClient.Me().Messages().Get(context.Background(), configuration)
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->orderby = ["from/emailAddress/address"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->me()->messages()->get($requestConfiguration);
若要以升序或降序对结果进行排序，请向字段名称追加
asc
或
desc
，并用空格隔开。例如，
?$orderby=name%20desc
。 如果未指定排序顺序，则推断默认值(升序)。
通过一些 API，可以对多个属性的结果进行排序。 例如，以下请求首先按发件人名称以降序（Z 到 A）排序用户收件箱中的邮件，然后按主题以升序（默认）排序邮件。
JavaScript
PowerShell
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.Me.MailFolders["{mailFolder-id}"].Messages.GetAsync((requestConfiguration) =>
requestConfiguration.QueryParameters.Orderby = new string []{ "from/emailAddress/name desc","subject" };
const client = Client.init(options);
let messages = await client.api('/me/mailFolders/Inbox/messages')
.orderby('from/emailAddress/name desc,subject')
.get();
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
MessageCollectionPage messages = graphClient.me().mailFolders("Inbox").messages()
.buildRequest()
.orderBy("from/emailAddress/name desc,subject")
.get();
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestParameters := &graphconfig.ItemMailFolderItemMessagesRequestBuilderGetQueryParameters{
Orderby: [] string {"from/emailAddress/name desc","subject"},
configuration := &graphconfig.ItemMailFolderItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
result, err := graphClient.Me().MailFoldersById("mailFolder-id").Messages().Get(context.Background(), configuration)
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->orderby = ["from/emailAddress/name desc","subject"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->me()->mailFoldersById('mailFolder-id')->messages()->get($requestConfiguration);
指定
$filter
服务器将推断结果的排序顺序。 如果同时使用
$orderby
和
$filter
获取消息，因为服务器始终会推断
$filter
结果的排序顺序，必须
以特定的方式指定属性
。
下面的示例展示了如何按
subject
和
importance
属性筛选查询，再按
subject
、
importance
和
receivedDateTime
属性进行降序排序。
JavaScript
PowerShell
var graphClient = new GraphServiceClient(requestAdapter);
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" };
let messages = await client.api('/me/messages')
.filter('Subject eq \'welcome\' and importance eq \'normal\'')
.orderby('subject,importance,receivedDateTime desc')
.get();
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
MessageCollectionPage messages = graphClient.me().messages()
.buildRequest()
.filter("Subject eq 'welcome' and importance eq 'normal'")
.orderBy("subject,importance,receivedDateTime desc")
.get();
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestFilter := "Subject eq 'welcome' and importance eq 'normal'"
requestParameters := &graphconfig.ItemMessagesRequestBuilderGetQueryParameters{
Filter: &requestFilter,
Orderby: [] string {"subject","importance","receivedDateTime desc"},
configuration := &graphconfig.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
result, err := graphClient.Me().Messages().Get(context.Background(), configuration)
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$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);
search 参数
使用
$search
查询参数限制与搜索条件匹配的请求结果。 它的语法和行为因 API 操作而异。 若要查看不同资源之间
$search
的语法，请参阅
使用$search查询参数匹配搜索条件
。
select 参数
使用
$select
查询参数返回一组不同于单个资源的默认集或资源集合的属性。 使用
$select
，可以指定默认属性的子集或超集。
例如，检索登录用户的邮件时，可以指定仅返回
from
和
subject
属性：
JavaScript
PowerShell
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
requestConfiguration.QueryParameters.Select = new string []{ "from","subject" };
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
MessageCollectionPage messages = graphClient.me().messages()
.buildRequest()
.select("from,subject")
.get();
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestParameters := &graphconfig.ItemMessagesRequestBuilderGetQueryParameters{
Select: [] string {"from","subject"},
configuration := &graphconfig.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
result, err := graphClient.Me().Messages().Get(context.Background(), configuration)
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["from","subject"];
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->me()->messages()->get($requestConfiguration);
一般来说，建议使用
$select
将查询返回的属性限制为应用所需的属性。 这对于可能返回大型结果集的查询尤为有用。 限制每行返回的属性将减少网络负载并帮助提升应用的性能。
在 中
v1.0
，某些派生自
directoryObject
的 Azure AD 资源（如
用户
和
组
）在读取时返回有限的默认属性子集。 对于这些资源，必须使用
$select
返回默认集之外的属性。
skip 参数
$skip
使用查询参数可设置集合开始时要跳过的项数。
例如，以下请求返回按创建日期排序的用户的事件，从集合中的第 21 个事件开始：
JavaScript
PowerShell
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.Me.Events.GetAsync((requestConfiguration) =>
requestConfiguration.QueryParameters.Orderby = new string []{ "createdDateTime" };
requestConfiguration.QueryParameters.Skip = 20;
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
EventCollectionPage events = graphClient.me().events()
.buildRequest()
.orderBy("createdDateTime")
.skip(20)
.get();
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestSkip := int32(20)
requestParameters := &graphconfig.ItemEventsRequestBuilderGetQueryParameters{
Orderby: [] string {"createdDateTime"},
Skip: &requestSkip,
configuration := &graphconfig.ItemEventsRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
result, err := graphClient.Me().Events().Get(context.Background(), configuration)
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new EventsRequestBuilderGetRequestConfiguration();
$queryParameters = EventsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->orderby = ["createdDateTime"];
$queryParameters->skip = 20;
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->me()->events()->get($requestConfiguration);
某些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。
例如，以下列表
请求
返回用户邮箱中的前五条消息：
JavaScript
PowerShell
var graphClient = new GraphServiceClient(requestAdapter);
var result = await graphClient.Me.Messages.GetAsync((requestConfiguration) =>
requestConfiguration.QueryParameters.Top = 5;
GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();
MessageCollectionPage messages = graphClient.me().messages()
.buildRequest()
.top(5)
.get();
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
graphconfig "github.com/microsoftgraph/msgraph-sdk-go/users"
//other-imports
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)
requestTop := int32(5)
requestParameters := &graphconfig.ItemMessagesRequestBuilderGetQueryParameters{
Top: &requestTop,
configuration := &graphconfig.ItemMessagesRequestBuilderGetRequestConfiguration{
QueryParameters: requestParameters,
result, err := graphClient.Me().Messages().Get(context.Background(), configuration)
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestConfiguration = new MessagesRequestBuilderGetRequestConfiguration();
$queryParameters = MessagesRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->top = 5;
$requestConfiguration->queryParameters = $queryParameters;
$result = $graphServiceClient->me()->messages()->get($requestConfiguration);
查询参数的错误处理
如果不支持指定的查询参数，某些请求将返回错误消息。 例如，不能对
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"
但是，值得注意的是请求中指定的查询参数可能会自行失败。 不支持的查询参数以及不支持的查询参数组合的情况就是如此。 在这些情况下，应检查请求返回的数据，以确定指定的查询参数是否具有所需的效果。
Azure AD 目录对象的高级查询功能
使用$search查询参数匹配搜索条件
查询参数限制
培训模块：将 Microsoft Graph 与查询参数配合使用时优化数据使用情况
