在应用中对 Microsoft Graph 数据进行分页Paging Microsoft Graph data in your app

由于服务器端分页或由于使用 $top 查询参数来明确限制请求中的页面大小,致使针对 Microsoft Graph 的一些查询返回多页数据。当结果集跨多个页面时,Microsoft Graph 将在响应中返回 @odata.nextLink 属性,该属性包含指向结果下一页的 URL。Some queries against Microsoft Graph return multiple pages of data either due to server-side paging or due to the use of the $top query parameter to specifically limit the page size in a request. When a result set spans multiple pages, Microsoft Graph returns an @odata.nextLink property in the response that contains a URL to the next page of results.

例如,以下 URL 要求对组织中的所有用户使用页面大小 5(使用 $top 查询参数指定):For example, the following URL requests all the users in an organization with a page size of 5, specified with the $top query parameter:

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

如果结果包含超过 5 个用户,则 Microsoft Graph 将返回一个下列类似的 @odata.nextLink 属性以及第一页的用户。If the result contains more than five users, Microsoft Graph will return an @odata.nextLink property similar to the following along with the first page of users.

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

可以通过将 @odata.nextLink 属性的 URL 值发送到 Microsoft Graph 来检索结果的下一页。You can retrieve the next page of results by sending the URL value of the @odata.nextLink property to Microsoft Graph.

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

Microsoft Graph 将继续通过每次响应返回对 @odata.nextLink 属性中下一页数据的引用,直到读取结果的所有页面。Microsoft Graph will continue to return a reference to the next page of data in the @odata.nextLink property with each response until all pages of the result have been read.

重要说明: 应该在请求的 @odata.nextLink 属性中包括整个 URL,以获取下一页结果。Important: You should include the entire URL in the @odata.nextLink property in your request for the next page of results. 根据正在对其执行查询的 API, @odata.nextLink URL 值将包含 $skiptoken$skip 查询参数。Depending on the API that the query is being performed against, the @odata.nextLink URL value will contain either a $skiptoken or a $skip query parameter. 该 URL 还包含原始请求中存在的所有其他查询参数。The URL also contains all the other query parameters present in the original request. 请勿尝试提取 $skiptoken$skip 值,也不要在不同的请求中使用它。Do not try to extract the $skiptoken or $skip value and use it in a different request.

分页行为因 Microsoft Graph API 不同而异。Paging behavior varies across different Microsoft Graph APIs. 处理分页数据时,应考虑以下几点:Consider the following when working with paged data:

  • 不同的 API 可能具有不同的默认页面大小和最大页面大小。Different APIs might have different default and maximum page sizes.
  • 如果指定超过相应 API 最大页面大小的页面大小(通过 $top 查询参数),则不同 API 的行为会有所不同。Different APIs might behave differently if you specify a page size (via the $top query parameter) that exceeds the maximum page size for that API. 具体取决于 API,所请求的页面大小可能会被忽略,它默认选择相应 API 的最大页面大小,否则 Microsoft Graph 会返回错误。Depending on the API, the requested page size might be ignored, it might default to the maximum page size for that API, or Microsoft Graph might return an error.
  • 并不是所有的资源和关系都支持分页。例如,针对 directoryRoles 的查询不支持分页。这包括读取角色对象本身以及角色成员。Not all resources or relationships support paging. For example, queries against directoryRoles do not support paging. This includes reading role objects themselves as well as role members.

详细了解分页Learn more about paging

以下视频介绍了 Microsoft Graph 中的分页。The following video introduces you to paging in Microsoft Graph.