Exploiting the Graph When PowerShell Can’t Do Enough for Teams

Teams PowerShell: OK but Limited at Times

After a shaky start, the Teams PowerShell module is now in a reasonable state. Valid gripes still exist that the Teams module is slow, and you must resort to the horrible Skype for Business Online module to work with Teams policies, but hope exists that Microsoft will improve performance and create an integrated module in the future.

But no matter how the Teams PowerShell module improves, its usefulness is still limited by the properties Microsoft chooses to expose through this interface. For instance, even if sometimes Microsoft backtracks on useful changes, Exchange Online, exposes a lot of information about mailboxes and Office 365 Groups. This makes it much easier for administrators to automate common operational processes for mailboxes and groups.

However, Exchange was the first major Microsoft server to adopt PowerShell way back in Exchange 2007. When Teams came along, PowerShell wasn’t its primary choice for an interface to enable automation. Instead, Teams focused on the Microsoft Graph API. The Teams PowerShell module is built on top of the Graph API, a fact that explains some oddities in filtering and other behavior.

To the Graph and Beyond

In any case, because Microsoft doesn’t expose all the properties of teams through PowerShell, sometimes you’re forced to use the Graph to get at information (the Graph Explorer helps you understand the information available for Teams). This is fine if you’re a programmer who’s used to dealing with RESTful APIs, but maybe not so good if you’re an administrator who writes some PowerShell scripts from time to time.

Fortunately, you can access the Graph API through PowerShell. And once you get your head around the concepts involved, it’s reasonably straightforward to write scripts to access and use the information exposed through the Graph.

Basic Graph Concepts

There are many blog posts available that explain how to connect to the Graph with PowerShell (here’s a good example and here’s another approach). The basic idea is that:

  • An app created in Azure Active Directory gives an entry point to the Graph. The app is tied to your tenant and can authenticate to the Graph using an application secret (analogous to a password) to access information. The app is assigned enough permissions to work with the data you need to access, like Groups.
  • PowerShell uses the Invoke-WebRequest cmdlet to send HTTP commands to the app to process against the Graph. For example, you use a GET command to request information.
  • The JSON data returned by the Graph is unpacked and used as normal.
  • If the app has write permission, data can be updated by sending a POST command to the Graph. You can also remove information by sending a DELETE command.

Working Example – Reporting Channel Email Addresses

So much for theory. As my working example, I’ve chosen to interrogate Teams to discover the set of channels that are mail-enabled and report the email addresses assigned to these channels. Any team member can enable a channel by requesting an email address. When this happens, Office 365 creates a special hidden mailbox for the channel and links the mailbox to Teams with a connector. Mail sent to the channel shows up as a new conversation and is also captured in the SharePoint document library belonging to the team.

The Teams PowerShell module includes a Get-TeamChannel cmdlet to return the set of channels in a team. However, it doesn’t return properties to show if a channel is mail-enabled or what its email address is, but the Graph knows. Here’s the code I used, broken into:

  1. Define details of the Azure Active Directory app to use to connect to the Graph.
  2. Create a token to connect.
  3. Connect to the Teams Graph endpoint and fetch a list of teams.
  4. Process each team to find its channels.
  5. Examine each channel to find if it is mail-enabled and if so, record its details.
  6. Generate CSV file.

The output is a CSV file holding details of the mail-enabled channels (Figure 1).

Figure 1: CSV file with details of mail-enabled Teams channels (image credit: Tony Redmond)

Explore the Possibilities

The Graph is hugely important to Office 365 and Microsoft is moving away from older APIs to use the Graph as quickly as it can. There’s obviously lots more that you can do to exploit the Graph with PowerShell (improve my code for a start), but hopefully this example is enough to get some creative juices going and remove a barrier that might have stopped you going near the Graph. PowerShell is great; it’s just even better when connected to the Graph.


Don't have a login but want to join the conversation? Sign up for a Petri Account

Tony Redmond has written thousands of articles about Microsoft technology since 1996. He covers Office 365 and associated technologies for Petri.com and is also the lead author for the Office 365 for IT Pros eBook, updated monthly to keep pace with change in the cloud.