Microsoft Graph for Office 365 - 分页和NextLink

博客地址：http://blog.csdn.net/FoxDave
前两篇文章我们介绍了Graph请求中可用的查询参数。本篇我们介绍如何对返回的大数据集进行分页相关的内容。

NextLink

Microsoft Graph会在我们执行需要分页的查询时返回多页数据。这会在服务器端分页或在查询中使用$top参数来限制返回结果的数量时发生。这种情况下，Microsoft Graph会在响应中返回一个@odata.nextLink属性，它包含了下页结果数据的URL，我们可以通过这个URL获取下页的结果数据。

下面我们在Graph Explorer中查看一下效果，我们执行获取组织中所有用户的查询，并附加$top查询参数：

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

示例的响应值如下所示：

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/users?$top=3&$skiptoken=X%2744537074020001000000253A31314E6F74466F72473168404A466F78646176652E6F6E6D4963726F736F66742E636F6D29557365725F65303632396136302D366226362D343963632D426362312D645537353339383563346561B900000000000000000000%27",
    "value": [
        {
            "businessPhones": [],
            "displayName": "1user",
            "givenName": null,
            "jobTitle": null,
            "mail": "1@contoso.onmicrosoft.com",
            "mobilePhone": null,
            "officeLocation": null,
            "preferredLanguage": "zh-CN",
            "surname": null,
            "userPrincipalName": "1@contoso.onmicrosoft.com",
            "id": "9ae39f73-64ff-4b1e-805d-73104539c35e"
        },
        {
            "businessPhones": [],
            "displayName": "11ForGAOAdd1h",
            "givenName": null,
            "jobTitle": null,
            "mail": null,
            "mobilePhone": "23",
            "officeLocation": null,
            "preferredLanguage": null,
            "surname": null,
            "userPrincipalName": "11ForGAOAdd1h@contoso.onmicrosoft.com",
            "id": "efa04dcc-0259-4fc7-85f1-2ce39bb87293"
        },
        {
            "businessPhones": [],
            "displayName": "11NotForG1h",
            "givenName": null,
            "jobTitle": null,
            "mail": null,
            "mobilePhone": null,
            "officeLocation": null,
            "preferredLanguage": null,
            "surname": null,
            "userPrincipalName": "11NotForG1h@contoso.onmicrosoft.com",
            "id": "e0629a60-6bf6-49cc-bcb1-de753985c4ea"
        }
    ]
}

响应结果包含了@odata.nextLink属性：

https://graph.microsoft.com/v1.0/users?$top=3&$skiptoken=X%2744537074020001000000253A31314E6F74466F72473168404A466F78646176652E6F6E6D4963726F736F66742E636F6D29557365725F65303632396136302D366226362D343963632D426362312D645537353339383563346561B900000000000000000000%27

这个URL中包含$skiptoken查询参数，我们可以使用这个URL发起一个新的查询来获取下页数据。

Microsoft Graph仍然会继续在每个响应中返回@odata.nextLink属性，直到所有页的结果都已经读取过。

这里有一些需要注意的事情：

• 任何集合甚至是字符串集合都可以进行分页。
• 如果第一次返回的结果是无分页的那可能是它们的数量不够进行分页。
• 在一些API中 (如Azure AD users “/users”、SharePoint list items “/items”等)如果使用$top参数请求过多的结果数可能会返回错误。
• @odata.nextLink返回的属性值会一直保留所有的原始查询参数，不要进行更改。
• 基于查询资源的不同，@odata.nextLink属性会包含skipToken或skip查询参数。
• 不是所有资源或关系都支持分页。例如，directoryRoles的查询不支持分页。
• 推荐为要分页的所有数组做准备并依此编写我们自己的代码/查询。

练习

访问Microsoft Graph Explorer，执行以下命令：

1. 获取组织目录的前10个用户
   https://graph.microsoft.com/v1.0/users?$top=10
2. 获取OneDrive for Business中前5个项目
   https://graph.microsoft.com/v1.0/me/drive/root/children?$top=5
3. 获取SharePoint Online网站列表中的前5000个项目
   https://graph.microsoft.com/v1.0/sites/jfoxdave.sharepoint.com:/sites/nms:/lists/9456c04d-1aaa-4d29-bc3d-aadb99fb2233/items?$top=5000
   关于构建此练习请求的具体内容查看下面的附录

附录

如何通过Microsoft Graph获取SharePoint列表项目

1. 使用如下请求获得租户名称：
   https://graph.microsoft.com/v1.0/sites/root
   从返回结果的siteColeection条目中复制hostname，例如“jfoxdave.sharepoint.com”
2. 接下来使用该网站集的相对URL获取列表集合，并选出要查询的该网站中某个列表的id：
   https://graph.microsoft.com/v1.0/sites/<hostname value from step 1 above>:/<relative path to site>:/lists
   例如：https://graph.microsoft.com/v1.0/sites/jfoxdave.sharepoint.com:/sites/nms:/lists
   复制id的值。
   例如：“id”: “9456c04d-1aaa-4d29-bc3d-aadb99fb2233”
3. 构建请求获取该列表前5000条项目（这也是SharePoint单页能返回的最大数）
   https://graph.microsoft.com/v1.0/sites/<hostname value from step 1>:/<relative path to site>:/lists/<id value from step 2>/items?$top=5000
   例如：https://graph.microsoft.com/v1.0/sites/jfoxdave.sharepoint.com:/sites/nms:/lists/9456c04d-1aaa-4d29-bc3d-aadb99fb2233/items?$top=5000