Overview
Microsoft Graph can seem daunting to understand when first starting off doing SPFx development. You want to access information from across your organization and through different services but don’t know where to start or what Microsoft Graph even is. This part of the blog will cover what it is, how it works and the permissions levels! The next part will focus on integrating it your SPFx webparts. This blog pools from Microsoft documentation to provide a basic guide on what Microsoft Graph is and parts of using it. The next part in the series will cover how to use it in your SPFx web parts!
Table of Contents
What Is The Graph?
The Graph manages Microsoft 365 services such as Calendar, Excel, and SharePoint but it also goes beyond that. You can use Microsoft Graph for Dynamics 365, device management through Intune, and Azure Active Directory (and more). You can connect to the Graph to get information or send information through REST APIs. This allows you to get information such as getting the profile picture of a user, your SharePoint groups, or someone’s Intune devices!
Graph APIs
Microsoft graph has an API structure that will be recurring in different requests you’ll see. It looks like this:
https://graph.microsoft.com/v1.0/{resource}?[query_parameters]The first thing you’ll notice is that we’re accessing version 1.0 of Microsoft Graph. This is the most tested version. If you’re getting into more high-level stuff, you can come across some APIs that will be in Beta. For a safe bet you always want to use v1.0 of Microsoft Graph. Read more on this here.
Moving on, you’ll notice that there is a “resource” part of the API. The resource is what we want to access. If you want to get all of the information on every user in the organization you would use “users” as your resource. A lot of these resources that are available are found in the documentation, but if you want to test different endpoints Graph Explorer is a must-use.
The best tool for remembering this is to start basic and then get more detailed. Once you locate your resource you can start do narrow it down based on the fields you like!
Query Parameters
Query parameters give the option to filter or sort your responses for GET API calls. They help you grab the information you want- and only that.
You may want to get specific properties or matches and queries can help you with that! They’re added onto the end of the graph API structure we just went over.
| Name | Purpose | Functions | Example Use | More |
|---|---|---|---|---|
| Filter | Filter the results you get back for specific matches to a property | eq, ne, not, in, has, lt, gt, le, ge, any, all, and, or, startsWith, endsWith, contains | /users?$filter=givenName eq ‘Alison’ (All users with the givenName Alison’) | |
| Top | Get the top number of results you set | $top | /groups?$top=5 (gets the first 5 groups) | Minimum value is 1 |
| Skip | Skip the first certain number of results | $skip | /me/messages?$skip=15 (Gets the 16th message and on) | Not supported with Directory objects (user, group, application) |
| Expand | Expand a property to get more information. Can return properties that aren’t normally returned (manager, memberOf) | $expand can have properties selected from its property with $select: expand=manager OR manager($select=id,name) | /users?$expand= manager($select=id, name) (Gets users and their manager. Gets the manager name and id) | Not supported with advanced queries |
| Select | Select specific properties to pull back and only them (like name, id, etc from users) | $select | /users?$select=id,displayName (Gets only the id and displayName of every user) | Gets properties not accessed by default as well (if selected) |
| Search | Search all properties or a property to see if they contain your search | $search AND, OR | /me/todo/lists?$search=”number” | Not supported in Azure AD B2C tenants Returns up to 1000 results |
| Orderby | Sorts your results (ascending default) | $orderby | me/messages?$orderby=from/emailAddress/name desc,subject (Z to A for names, ascending default for subject!) | %20desc at the end to get all in descending (or %20asc for ascending) |
| Count | Count each item in the response (like each user in a list) | $count | /groups?$count=true (Gets the groups and counts them) | Advanced query for directoryObjects Not supported in Azure AD B2C tenants |
| Format | Return the results in a designated format. | Full list of supported formats (pdf, json, etc) | /users?$format=json |
This list looks daunting but with practice it will gradually become easier to use. Stack Overflow and the Microsoft Documentation are also always there to help out when you’re in need!
To give a simple use case scenario you could search up all of your companies’ users: /users. Then you could simplify all of the information to just get the name of every user: /users?$select=displayName. Combining multiple queries will be in the next blog on working with Microsoft Graph as well.
Security Permissions
If you’ve used Microsoft Graph in your web parts you may have run into issues with web part permissions. There are several different types of permissions and the permission you need for a request is dependent on what you want to do. The basic types can be broken up into Read and Write (using User as an example resource):
| Read (see the information) | Write (modify the information) |
|---|---|
| User.Read (Read signed-in user information) | User.ReadWrite (read and modify signed-in user information) |
| User.ReadBasic (Read basic profile information of signed-in user) | User.ReadWrite.All (Read and modify all other user information) |
| User.ReadBasic.All (Read basic profile information of other users) | Mail.Read.Shared (Read mail from the signed-in accounts’ mailbox as well as any mail in mailboxes shared with you) |
| User.Read.All (Access all other users’ information) |
What these permissions do is they allow multiple levels of access to certain information. For example, you don’t want to allow someone to view every user’s mailbox- you only want them to be able to view their own inbox. This can make a big difference in security if there are loose permissions on different apps.
As the documentation puts it, “If no constraint is specified the app is limited to performing the operations on the resources owned by the signed-in user.” Adding a constraint specifies that the operation access is not just restricted to the signed-in user and gives specific access for the web part.
It is best practice to use the permission with the least amount of viewing privilege as you want to make sure everything is secure. Speaking of permissions, how do you go about adding Graph API calls to your web part? The next part of this blog series will cover that so stay tuned!
Conclusion
Now that you’ve seen how queries work you can test out the Graph Explorer! You can come up with different endpoints using your knowledge of user permissions for the Graph. Stay tuned for the second part of this blog series and let me know what other things I should write about!
Graphgod 
Leave a comment