在应用中对 Microsoft Graph 数据进行分页

由于服务器端分页或客户端分页,针对 Microsoft Graph 的某些 GET 查询返回多页数据。 分页数据有助于提高应用的性能和 Microsoft Graph 的响应时间。

注意

如果要查找有关在 Microsoft Graph SDK 中分页的信息,请参阅 使用 Microsoft Graph SDK 对集合进行分页

通过以下视频详细了解分页。

分页工作方式

在客户端分页中,客户端应用使用$top、$skip或$skipToken查询参数指定它希望Microsoft Graph 在单个页面中返回的结果数。 对客户端分页的支持,包括客户端可以在单个页面中请求的结果数取决于 API 和正在执行的查询。 例如, /users 终结点支持 $top 但不支持 $skip

在服务器端分页中,Microsoft Graph 服务在单个页面中返回默认的结果数,而客户端不使用 指定要返回 $top的结果数。 例如,终结点在 GET /users 单个页面中返回默认值 100 个结果。

当需要多个查询请求来检索所有结果时,Microsoft Graph 在响应中返回一个 @odata.nextLink 属性,该属性包含指向下一页结果的 URL。 可以通过将 @odata.nextLink 属性的 URL 值发送到 Microsoft Graph 来检索结果的下一页。 Microsoft Graph 将继续返回对属性中 @odata.nextLink 每个响应中下一页结果的引用,直到没有更多要检索的结果页。 若要读取所有结果,必须继续使用每个响应中返回的属性调用 Microsoft Graph @odata.nextLink ,直到不再返回该 @odata.nextLink 属性。

例如,以下示例演示客户端分页,其中客户端使用 $top 查询参数请求租户中最多五个用户。

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

如果结果包含更多结果,Microsoft Graph 将 @odata.nextLink 返回如下所示的属性以及结果的第一页:

"@odata.nextLink": "https://graph.microsoft.com/v1.0/users?$top=5&$skiptoken=RFNwdAIAAQAAAD8...AAAAAAAA"

在 GET 请求中使用 属性中的 @odata.nextLink 整个 URL 来检索下一页结果。 根据要对其执行查询的 API,URL @odata.nextLink 值包含 $skiptoken$skip 查询参数。 该 URL 还包含原始请求中存在的所有其他查询参数。 请勿尝试提取 $skiptoken$skip 值并在其他请求中使用它。

分页行为因 Microsoft Graph API 不同而异。 处理分页数据时,应考虑以下几点:

  • 结果页可能包含零个或多个结果。
  • 不同的 API 可能具有不同的默认页面大小和最大页面大小。
  • 如果指定超过相应 API 最大页面大小的页面大小(通过 $top 查询参数),则不同 API 的行为会有所不同。 具体取决于 API,所请求的页面大小可能会被忽略,它默认选择相应 API 的最大页面大小,否则 Microsoft Graph 会返回错误。
  • 并非所有资源或关系都支持分页。 例如,针对 directoryRole 的查询不支持分页。 这包括读取角色对象本身和角色成员。
  • 当对 目录资源进行分页时,任何自定义请求标头 (不是 Authorization 或 Content-Type 标头) (如 ConsistencyLevel 标头)默认情况下不会包含在后续页面请求中。 如果需要在后续请求中发送这些标头,则必须显式设置它们。
  • 在对目录资源进行查询时使用$count=true查询字符串时,@odata.count属性仅在分页结果集的第一页中返回。