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

  • 项目

由于服务器端分页或使用 $top 查询参数专门限制请求中的页面大小，针对 Microsoft Graph 的某些查询返回多页数据。 当需要多个查询请求来检索所有结果时，Microsoft Graph 将在响应中返回一个 @odata.nextLink 属性，该属性包含指向下一页结果的 URL。

例如，以下 URL 要求对组织中的所有用户使用页面大小 5（使用 $top 查询参数指定）：

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=X%274453707 ... 6633B900000000000000000000%27"

可以通过将 @odata.nextLink 属性的 URL 值发送到 Microsoft Graph 来检索结果的下一页。

https://graph.microsoft.com/v1.0/users?$top=5&$skiptoken=X%274453707 ... 6633B900000000000000000000%27

在读取结果的所有页面之前，Microsoft Graph 将继续通过每次响应返回对 @odata.nextLink 属性中下一页结果的引用。 若要读取所有结果，必须继续使用每个响应中返回的属性 @odata.nextLink 调用 Microsoft Graph，直到不再返回该 @odata.nextLink 属性。

重要说明：应该在请求的 @odata.nextLink 属性中包括整个 URL，以获取下一页结果。 根据正在对其执行查询的 API， @odata.nextLink URL 值将包含 $skiptoken 或 $skip 查询参数。 该 URL 还包含原始请求中存在的所有其他查询参数。 请勿尝试提取 $skiptoken 或 $skip 值，也不要在不同的请求中使用它。

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

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

详细了解分页

以下视频介绍了 Microsoft Graph 中的分页。