30DaysMSGraph – Day 7 – Paging and NextLink

Brian T. Jackett

November 7th, 2018 0

List of all posts in the #30DaysMSGraph series

-Today’s post written by Srinivas Varukala

In Day 6 we finished discussing many of the query parameters available for Microsoft Graph requests.  Today we’ll look at the concept of paging results when there are more records than can be returned in a single response.

Microsoft Graph returns multiple pages of data when you issue a query that requires pagination. This could happen either due to server-side paging or due to the query using the $top query parameter to restrict the number of records that are returned. In either case, Microsoft Graph returns an @odata.nextLink property in the response that contains the URL to the next page of results.

You can use the link that is provided in the @odata.nextLink to get the next page of results.

To see this in action navigate to the Graph Explorer and issue a query to get back all the users in your organization along with the $top query parameter:

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

Sample response value (truncated for brevity) is as follows:

{ “@odata.context”: “https://graph.microsoft.com/v1.0/$metadata#users”, “@odata.nextLink”: “https://graph.microsoft.com/v1.0/users?$top=3&$skiptoken=X%2744537074020001000000223A416C657857404D333635783939353035322E4F6E4D6963726F736F66742E636F6D29557365725F33613166623664392D373666342D346233352D623139332D333764643136373530396233B900000000000000000000%27”, “value”: [ { “id”: “c25b1eaf-eb49-4f66-90a1-aa41be4d993a”, “displayName”: “Adele Vance”, “givenName”: “Adele”, “userPrincipalName”: “AdeleV@M365x995052.OnMicrosoft.com” }, { … }, { … } ] }

The response contains the @odata.nextLink property that contains a URL (Microsoft Graph query) with an additional $skiptoken query parameter. Using this URL you can re-issue another query within the Graph Explorer to get the next page results.

Microsoft Graph will continue to return the @odata.nextLink property in each response until all pages of the result has been read.

A few important things to note:

  • Any collection can be paginated, even collections of strings.
  • Collections might appear unpaginated initially because they don’t have enough items to return a NextLink.
  • There are a few APIs that may return errors if you ask for too many items with $top (ex. Azure AD users “/users”, SharePoint list items “/items”, etc.)
  • The @odata.nextLink returned will always retain all of the original query parameters and should not be modified.
  • Depending on the resource (example: Users, SharePoint list etc.) that you are querying against, the @odata.nextLink will contain either $skipToken or a $skip query parameter.
  • Not all resources or relationships support paging. For example, queries against directoryRoles do not support paging.
  • It is recommended to prepare for all arrays to be paginated and write your code / query accordingly.

 

Try It Out

Navigate to the Graph Explorer.  Execute the following commands.

Day 7 repo link

  1. Get the users from your organization’s directory
    • https://graph.microsoft.com/v1.0/users?$top=10
  2. Get all the items in your OneDrive for Business
    • https://graph.microsoft.com/v1.0/me/drive/root/children?$top=5
  3. Get all the items from a SharePoint Online Site list

 

Join us tomorrow as we review authenticating to Microsoft Graph and specifically access tokens in Day 8.

 

Appendix

How to get SharePoint List Items using Microsoft Graph

  1. If you are not logged into the Graph Explorer (i.e. using a demo tenant) find out the name of the tenant. Issue the following Microsoft Graph query:
    • https://graph.microsoft.com/v1.0/sites/root
    • Copy the hostname value from siteCollection entity, ex. “m365x214355.sharepoint.com”
  2. Next you must use the site collection relative URL and find out the id of a list on that site. Issue below Microsoft Graph query to get those details:
    • https://graph.microsoft.com/v1.0/sites/<hostname value from step 1 above>:/<relative path to site>:/lists
      • Ex. https://graph.microsoft.com/v1.0/sites/m365x214355.sharepoint.com:/sites/HR:/lists
    • Copy the {id} value from the first list record shown.
      • Ex. “id”: “ed70c81d-fedf-4a1b-a1f1-f44e39c5bb78”
  3. Next create Microsoft Graph query to fetch the top 5000 items (max that SharePoint can return in one page) from the list
    • 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
      • Ex. https://graph.microsoft.com/v1.0/sites/m365x214355.sharepoint.com:/sites/HR:/lists/ed70c81d-fedf-4a1b-a1f1-f44e39c5bb78/items?$top=5000

Brian T. Jackett

Read next

Feedback usabilla icon