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