A look into Microsoft Graph SDK
Microsoft Graph provides access to the enormous amount of data existent on the Office 365 Universe + Windows 10 and Enterprise Mobility + Security.
These data gives the possibility to enrich the user experience by creating new apps that can fill the missing gaps from a organization or user perspective or by empowering it.
Microsoft Graph exposes diversified REST APIs and client libraries that can be easily accessible in order to obtain the information. The following image represents some of the zones that Microsoft Graph provides access in.
A simple HTTP request to Graph is the necessary to retrieve information. Here it is an example of a request that will be looked upon ahead in the article. This exposure allows a fast development with any programming language for future apps related with Microsoft products.
In other hand Microsoft Graph SDK gives a different approach to access the MS Graph. In this article I’ll be using the .NET SDK to provide example on how Microsoft Graph SDK can help access and structure the information.
Authentication
Creating a Graph Service Client creates a client to be used in order to access Microsoft Graph. It supports multiple types of authentication providers. At the time of this article there are eight ways to create a client with different authentication provider.
In order to help which might be the best choice to pick there is a table with different scenarios and its recommendation accessible here.
The current Nuget Package ( Microsoft.Graph.Auth ) is still in a prerelease state.
I will be using the DelegateAuthenticationProvider in order to use an access token that contains certain permissions previously delegated with the Azure AD ( Azure Active Directory ).
In this case one of the permissions delegated is related to the SharePoint environment. The usage of the access token gets relevant to have flexibility with using the same token in different services, not just Microsoft Graph.
The access token was obtained using the OAuth 2.0 authentication protocol to comply with the Microsoft Identity Platform ( or as I called before Azure AD ).
After creating the client making a request is relatively simple as shwon on the line 11 of the figure above. Obtaining the root site of my SharePoint that in a url is:
https://graph.microsoft.com/v1.0/sites/root
looks pretty similar to using the method:
Site rootSite = await graphserviceClient.Sites.Root.Request().GetAsync();
Request() constructs the request that will be called and finally getAsync() assign a HTTP GET request delivering a Site structure with the properties of the SharePoint root site when returning the response.
In more complex scenarios you might need to have pagination or have different query parameters to specific the search.
Let’s look at the following example.
In the case I used the id from the Root Site obtained before to get information about all the sites that belong to that SharePoint. This is also obtainable by using the SharePoint client object model (CSOM).
But in this case Graph might return more results then CSOM.
When starting a search on example.sharepoint.com :
The first one will be shown by either CSOM and Graph on its first call while the second one will be presented only by Graph where in CSOM there is the necessity to recursively go to /sites/example and find all of its subsites.
QueryOption are used in order to have query parameters on the requests. In this case I used search=* since it will look for all the sites (based on the regex).
The request is slightly different as:
await graphserviceClient.Sites[rootId].Sites.Request(options).GetAsync();
which will receive an ISiteSitesCollectionPage. Adding the rootId on the Sites specifies which id you want to look.
It is in the Request that the parameter options are added. The response that comes from the request might contain new query parameters if there is more information to be shown such as the pagination. Replacing the old query parameters with the new ones does the trick.
Pros
It is structured and easy to implement. I was not familiarized with the concept of OData protocol on REST APIs which required more coding to be done when calling the endpoints. In other hand the SDK contains classes for the types of objects that are expected to be returned making it a more simple process.
When using the usual Http client it is still possible to remove this obstacle by implementing an abstract class that will deserialize the data.
Cons
When using the SDK some available methods might be unavailable. A good example is adding a custom app as a zip into Teams. I looked on it for a substantial amount of time until I gave up and decided to go using the traditional method of creating a HttpClient with its request and stream of content.
Conclusion
Microsoft Graph is an insane tool to enrich the user experience and provide new apps into the ecosystem. For more information that a look on the documentation here.
It is currently getting more features and its upcoming changes can seen on the beta graph endpoint. Beware when using that endpoint since it is not certain that it will not have changes.
Have a nice week,
Paulo
