Microsoft Graph is described by Microsoft as a RESTful web API that enables you to access Microsoft cloud service resources and the gateway to data and intelligence in Microsoft 365. That’s quite a mouthful, but if you’re a developer, there are tons of Microsoft Graph tutorials available on Microsoft Docs. Whether you program in Node.js, Python, Xamarin, or Angular, these tutorials are a good way to get started using Microsoft Graph. But what about PowerShell? Until recently, there was no simple way to work with the Microsoft Graph API from PowerShell. But with the recent release of the alpha version of the Microsoft Graph PowerShell module, you can now begin to do all kinds of really cool stuff with it using PowerShell. To give us a glimpse of what may be ahead, I asked veteran PowerShell expert Vlad Catrinescu to give us a short walkthrough of using the new module. Vlad is a SharePoint and Office 365 consultant specializing in SharePoint and SharePoint Online deployments as well as hybrid scenarios. As a Pluralsight author, Microsoft Certified Trainer, and recognized international speaker, Vlad has also helped hundreds of thousands of users and IT pros across the globe better understand and to get the most out of SharePoint. Vlad is also a Microsoft Most Valuable Professional (MVP) in SharePoint since 2013 and maintains a personal blog called Absolute SharePoint Blog, and he often shares his knowledge by speaking at local conferences and community events. Vlad also blogs at CMSWire as well as Computerworld and is often featured on other Microsoft sites such as Redmond Channel Partner. You can also connect with Vlad on LinkedIn and follow him on Twitter.
Another PowerShell module? But why??
At Ignite 2019, Microsoft announced a new PowerShell module they are working on: the Microsoft Graph PowerShell module. I will start with the obvious question, which was also answered during the session: Another one? But why? Office 365 administrators today already have a dozen PowerShell modules they need to know for management, why do we need another one?
As you can see in the screenshot below taken from Darrel Miller’s THR3095 session, which you should watch (after reading this blog post of course!), there is a huge demand in the community for a PowerShell module for Graph. There are a dozen Graph modules for PowerShell out there in the PowerShell Gallery, but most of them use either one of the old Graphs or are simply outdated.
But Vlad, still, why?
I know that just saying “other people did it, so we must do it as well” is never a great explanation, so let me give you more examples. The advantage of having the power of Microsoft Graph in our hands in a PowerShell module enables us to automate a bunch more “end-user experiences” than ever before, without needing those expensive devs who break everything (just kidding!): Adding a task in someone’s Outlook tasks, posting a message in Teams, modifying Team shifts, and so on. Up until now, the PowerShell modules we had were strictly for management, and anything that we wanted to automate inside the end-user experience required a developer to create a solution (for example, Azure Function, Azure Web App) that connects to Microsoft Graph to automate it. The goal, with the PowerShell Microsoft Graph module, is that as IT pros who master PowerShell, we will now be able to access all the power of the Microsoft Graph, from PowerShell scripts either run locally or in Azure Automation, for example. This module is also cross-platform, meaning it will work on any platform that PowerShell works on! (PS: Nothing against devs, I just couldn’t resist taking another friendly jab at you guys!)
Getting started with the Microsoft Graph PowerShell module
Now let’s go just a bit more technical to show you guys how to get started. This module isn’t in beta yet, it’s still in alpha, so play it with, learn it, build proof of concepts, but try not to use it in production just yet! Since it’s not yet ready for prod, the module is not yet hosted on the PowerShell Gallery (it will be in the future), but instead, you can find it on GitHub. To install it, we will first need to register the repository on our computer and then install the module with the following cmdlets:
Register-PSRepository ` -Name GraphPowerShell ` -SourceLocation https://graphpowershellrepository.azurewebsites.net/nuget Install-module Microsoft.Graph.Beta -Repository GraphPowerShell
Doing this will download about 200MB of data.
Something that you might notice, depending on what modules you already have installed, is that at the time of writing this article, Microsoft has decided not to add a prefix so the Module. So instead of cmdlets being something like Get-MSGraphSite, it’s simply Get-Site. There were quite some passionate reactions on this, both in person, and on GitHub, and according to the latest update to that thread, it seems that Microsoft gave in to the community pressure, so I hope we will see a prefix soon! Because it doesn’t have a prefix, you might have errors such as the one below if you have for example the Teams module installed!
For this article, I have uninstalled the Teams PowerShell module and installed the Microsoft Graph PowerShell module to look at some quick examples. As this is in its very early stages, a lot of the tech details might change, so I will only cover how to connect to the Graph, where to get more information, and will be sure to write more deep-dive articles in the future.
Connecting to the Graph
To connect to the graph, the first thing you need to run is the Connect-Graph cmdlet. This will give you a code, and a page to open in your browser where you enter that code and authenticate, and after that, you will be connected. They will be working on a better experience in the future, but for the alpha release those are the required steps:
Depending on your permissions, running the Connect-Graph cmdlet will only give you the “read user” permissions on the Graph, so most of the cmdlets will not work. You might need to specify what permissions you need, for example:
Connect-Graph -Scopes "User.Read","User.ReadWrite.All","Mail.ReadWrite",` "Directory.ReadWrite.All","Chat.ReadWrite", "People.Read", ` "Group.Read.All", "Directory.AccessAsUser.All", "Tasks.ReadWrite", ` "Sites.Manage.All"
Trying out some samples
Now that you are connected, you can go and try some of the samples that Microsoft has provided in the GitHub repository, and to see all of the available cmdlets on a specific topic, you can always run something like the following cmdlet to see all of the cmdlets that talk about OutlookTasks.
Get-Command -Module Microsoft.Graph.Beta* *OutlookTask*
Microsoft Graph PowerShell module: High hopes
This is it for this very introductory blog post on the new PowerShell module for the Microsoft Graph. Right now, the module is still very early, and it’s good to see Microsoft working with the community to make it the best version it could be. I have high hopes for this module, as I believe this module will really allow IT pros to not only have management control but full control on the tenant by using the full power of Microsoft Graph to automate both management, and more end-user experiences, directly with the tool we know and love, which is PowerShell.
Remember to listen to the 20-minute Ignite session about the module and play around with it. If you find any issues, report them on GitHub, as Microsoft is actively monitoring it for feedback and stuff to fix.
Featured image: Shutterstock / TechGenix photo illustration
More PowerShell Basics articles
- PowerShell Gallery: A great free resource for finding scripts
- Using JSON with PowerShell: A guide for IT professionals
- Reading text files with PowerShell and Linux bash shell
- How malicious PowerShell scripts evade detection
- Building PowerShell hash tables