This post has the intention to give you an overview and starting point to automate things with the Microsoft Graph API and PowerShell. While having the focus on Intune and EM+S but the basics are also valid for other Microsoft services.
The world is changing and so are you?
When talking about automation most people only think about some PowerShell code and scheduled tasks running on whatever box in an environment. But technology regarding Microsoft services and it’s automation possibilities have definitely evolved quickly. Automation can now be done with basically any scripting or programming language because Microsoft offers us the Microsoft Graph API. Although API (application program interface) sounds more like a developer term engineers should better get used to consuming API’s. As more and more services can be consumed as SaaS API’s are mostly offered for further data processing and automation.
Microsoft Graph API
Microsoft describes it’s own Graph API as “Microsoft Graph is the gateway to data and intelligence in Microsoft 365”. Most of the API’s out there are built according the RESTful definition. A RESTful, also called REST API should implement the following operations (HTTP methods) to work with data:
- GET: Retrieve items
- POST: Create items
- PUT : Create, overwrite items
- DELETE: Delete items
The Microsoft Graph API also implements PATCH requests which allow you to update existing entities and properties. In the Microsoft Graph context they are probably used more often instead of PUT requests.
As entry point Microsoft Graph is available under the following URL: https://graph.microsoft.com.
A schematic request looks like this:[HttpMethod] https://graph.microsoft.com/{version}/{route}/{resource}[/{id}/{query-parameters}
A request to retrieve all Intune devices looks like:GET https://graph.microsoft.com/beta/deviceManagement/managedDevices
As a response we retrieve all enrolled devices in JSON format:
As mentioned the Graph API offers routes to almost all Microsoft 365 components like Intune, Office 365 and Windows. A full list is available in theofficial documentation.
Beta vs v1.0 version
The Graph API is available in two different versions: naming them “beta” and “v1.0” with their respective urls: https://graph.microsoft.com/beta and https://graph.microsoft.com/v1.0.
If you want to build a rock-solid business application and receive support from Microsoft you are supposed to go with the v1.0 version.
If you want to consume the latest features for scripting and automation you are probably better served with the beta version. The fact that most of the scripts out there use the beta endpoint might tell it’s own story.
How to access the Microsoft Graph API?
Now you should have a rough estimation what the Microsoft Graph API allows us to do and which endpoints are available. But how to consume an API? The described operations (GET, POST, PUT, PATCH, DELETE) must be initiated via web request. To access your tenant’s data with Microsoft Graph you need to acquire an access token which must be included in the header of every API request you perform.
In order to retrieve an access token an application registration in your tenant is required. The Graph explorer and Intune-PowerShell-SDK have both built-in functionality which prompts you for the permissions when you try to access Microsoft Graph for the first time.
By default you should have an enterprise application registered in your tenant with the name “Microsoft Intune PowerShell” and the client ID “d1ddf0e4-d672-4dae-b554-9d5bdfd93547” which is used by the Intune PowerShell SDK and other Microsoft samples you will find on the web.
Note that if you consent to an application with delegated permissions the application will never have more permissions than the currently signed-in user. If you want to access the Graph API without a signed in user you might want to set up application based authentication.
Helpers to access Microsoft Graph
Fortunately we do not need to start from scratch and Microsoft offers use some nice helpers to start working with the Microsoft Graph API.
- Graph Explorer is an interactive tool to experience and explore the Graph API
- Intune-PowerShell-SDK is a PowerShell module offering various helper cmdlets to work with the API and PowerShell
My three favorite commands from the Intune PowerShell SDK are:
Invoke-MSGraphRequest(perform any kind of Graph requests)Get-MSGraphAllPages(get all entries for requests which return a lot of data and use paging)Connect-MSGraph(connect to Graph, get an access token)
the best thing is that those three cmdlets mentioned above are also useful for other parts of Microsoft Graph and not limited to Intune.
Troubleshooting Microsoft Graph API calls
If you want to use some newer Microsoft Graph resources the features are sometimes implemented faster than they are documented. Or you just missed some piece of the documentation. So we need a way to troubleshoot our Microsoft Graph API calls. I prefer to do the action in the portal where things usually work and then analyze the https traffic and calls mad to Graph.
We have the following two options to do so:
- Developer Tools of your web browser
- Fiddler HTTP Proxy
As an example an exempt when you create a new device configuration in the Intune portal we can trace the behaviour with the network section of a web browser:
Recurring automation - are scheduled tasks dead?
For recurring automation like cleanup and reporting scripts which are intended to run on a regular basis we used to rely on scheduled tasks. Personally I do not like them anymore since I started using Azure automation. Azure automation offers the following advantages over scheduled tasks:
- More transparency and overview of configured tasks
- Simplified and more secure handling of credentials (you do not need to work with secure strings and things like that) and support for service principals
- History of past jobs and their respective PowerShell output streams
- Automate both cloud and on premise tasks with hybrid workers
If you want to use Azure automation to access Microsoft Graph continue reading with this post.