Microsoft Graph API in SPFx
Development Microsoft 365 SharePointMicrosoft Graph API allows developers to leverage the power of many services in the Microsoft 365 suite in SharePoint (SPFx) web parts, extension and standalone apps. Developers can combine the use of different API endpoints to come up with new solutions.
In this article, I’ll give you a rundown on some resources to help you get started using the Graph API in a SPFx solution.
Graph Explorer
https://developer.microsoft.com/graph/graph-explorer/
This is a very helpful tool to check out what the Graph API is capable of and test queries of your own to retrieve data from your Microsoft 365 services when you are logged in using your Office 365 account.
The API reference
https://docs.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0
The API reference is another important resource that provides detailed explanations of methods, properties and JSON representation that may help you understand the endpoints you are intending to use and in some cases plan your solutions around them if they are not quite to your requirements. This is especially of note when you are using new endpoints in the beta version of the Graph API, such the ones for Teams and Planner.
Microsoft Graph JavaScript Client Library
https://www.npmjs.com/package/@microsoft/microsoft-graph-client
This is a wrapper around the Graph API that can be used in both client-side and server-side solutions. It provides a fluent way for consuming the Graph API and is usable in TypeScript projects such as SPFx web parts and extensions. It makes accessing the Graph API features such as HTTP methods and query parameters more convenient.
Examples of using the Graph API
There are a quite a few ways to use the Graph API in a solution. The simplest being a single request to retrieve data from an endpoint such as the one for recent documents or tasks in Outlook Tasks, and display the results in a customised view.
In this example, we will retrieve ten uncompleted tasks from Outlook and display them in a React Redux SPFx solution. For more on Redux in SPFx, read my previous article. Let’s assume that we’ve got that covered so we can jump straight into the interesting stuff.
Okay, so we have set up a solution with React Redux ready to go, installed the Microsoft Graph JavaScript Client Library, set up constants, our Redux store, reducers and we’re ready to write in some actions to retrieve some uncompleted tasks.
Firstly we will need to initialise the Microsoft Graph Client in our solution as we will need to run our queries. I’ve chosen to add it to the persistent state in my solution because it requires a HTTP request and it make things more efficient by not having to perform an additional request whenever a Graph API based action is called.
Here’s what my persistent state looks like. I’ve also included a few configurable state for item limit in the SPFx property pane to allow users to choose how many results they want retrieved. Note that context is extremely important as it is required to initialise the MS Graph Client.
Now, we can add an action to initialise the MS Graph Client in our solution. Done with minimal code! How nice.
Next, we write an action to retrieve some uncompleted tasks from Outlook using the beta version of the Graph API. This is pretty simple request with a filter and an item limit applied.
Here’s a link with more detail on the different query parameters that are available https://docs.microsoft.com/en-us/graph/query-parameters?view=graph-rest-beta.
Keep in mind that some parameters are not available for certain endpoints and this is not particularly well documented making it necessary to test things yourself before committing to a solution.
Then in our React component, add the necessary connections to make the actions available in your solution properties.
Once we’ve done that we can initialise an instance of the MS Graph Client and then use it to make a request using the Graph API to retrieve some tasks (make sure that you have some uncompleted tasks).
With that done, you can look into how you’d like to render the task list. In this example, I’m just going to render them using the Checkbox component in the Office UI Fabric library.
Here’s how mine looks. Rather plain but there’s a reason why I chose to use the Checkbox. It is because we can wire it up to complete tasks by making another Graph API request.
That’s when the Graph API is most useful. When a combination of endpoints are used to create solutions that offer a rich Office 365 experience in SharePoint and even standalone apps.
