Getty Images/iStockphoto

Tip

Start managing with these Microsoft Graph API features

Microsoft Graph offers several administrative advantages when handling jobs on Microsoft 365 and Azure AD, but be aware of some potential trouble spots when employing this technology.

It's a headache to manage Microsoft's multiple cloud services due to the many management options, but a relatively new technology delivers a unified approach to bring administrative relief.

Microsoft 365 as a core service is a connected series of components, controls and services. Each service -- including Exchange, SharePoint, Microsoft Teams, and even the security and compliance features -- has its own API. Separate APIs make it more complicated to pull information or perform changes; you need to use a different endpoint with distinctive properties and even dissimilar syntax. Microsoft created Microsoft Graph to streamline the way to work with services within Microsoft 365/Office 365 tenants. With PowerShell, you can connect to one endpoint to work with all your Microsoft services.

Microsoft Graph exposes the existing REST APIs and client libraries to allow connections to Microsoft cloud services, such as the following:

  • Microsoft 365 cloud services
  • Microsoft 365 compliance eDiscovery
  • Microsoft Search
  • Enterprise Mobility + Security services
  • Windows 10 services
  • Dynamics 365 Business Central

Each service has its own API, but Microsoft Graph wraps them in a more cohesive framework.

Microsoft Graph has two core endpoints: a released version, known as version 1.0, and a beta version for testing purposes. For example, to view your personal Microsoft 365 user profile, you can use either endpoint using the following links to the online Graph Explorer tool:

How do you use Microsoft Graph?

Graph Explorer is a great starting place to connect to your tenant and execute commands. The Microsoft Graph toolkit works with other programming languages with a common framework. To learn more about the Microsoft Graph toolkit, the following link offers more detailed information.

Another option is the Graph PowerShell SDK, which is a wrapper for Microsoft Graph. Each PowerShell command directly connects to either one or more Microsoft Graph API calls.

No matter the approach, using Microsoft Graph requires connecting to a REST API endpoint combined with the properties or values needed. For example, to retrieve the members of a Microsoft Teams channel using Microsoft Graph, the following Uniform Resource Identifier (URI) is required:

https://graph.microsoft.com/v1.0/groups/0c83236a-7484-4128-b43c-f7f5011a581b/members

The URI starts with the graph endpoint and graph version, followed by the service endpoint, resource ID (Team ID) and required object type, which, in this case, is members of the team. You can use the same URI within any supported programming language or tool that supports REST API calls. For example, to call the same URI with PowerShell, use the following commands:

$endpoint= https://graph.microsoft.com
$version = "beta"
$serviceendpoint = "groups"
$resource = "0c83236a-7484-4128-b43c-f7f5011a581b"
$objecttype = "members"
$body = @{}
$members = Invoke-MgGraphRequest `
     -Uri "$endpoint/$version/$serviceendpoint/$resource/$objecttype" `
     -Method GET `
     -Body $body
$members.value | ForEach-Object {
     Write-Host $_.mail
}

Why use Microsoft Graph?

There are six compelling reasons to use Microsoft Graph:

  1. provides a single resource endpoint;
  2. supports multiple development types;
  3. eases the navigation of Microsoft Graph objects;
  4. offers development platform and language flexibility;
  5. gets protection from the Microsoft identity stack and services; and
  6. utilizes open standards.

Microsoft Graph helps you avoid several issues in other management methods. Some configuration options do not exist within the administration portals and are only available within Microsoft Graph. New features typically surface in Microsoft Graph before they appear in the portals.

It is often easier to retrieve the required information with Microsoft Graph rather than the administration portals. For example, to see all users in the tenant and their assigned licenses, you would have to go to specific pages within the admin center or Azure Active Directory or click into each user to see these assignments. However, Microsoft Graph just requires a simple URI to get the list:

https://graph.microsoft.com/v1.0/users?$select=id,userPrincipalName,assignedLicenses

The resulting output is JavaScript Object Notation (JSON), which is an industry standard for data. You can then interrogate or manipulate the results as needed. The ability to export a list is not universally available from the portals, which gives the advantage to Microsoft Graph.

What is the Microsoft Graph SDK?

Microsoft provides an SDK for multiple programming languages to help write code to work with Microsoft Graph.

The Microsoft Graph SDKs simplify the process to access Microsoft Graph. The Microsoft Graph SDKs provide two components: a service library and a core library. The service library contains models and requests builders to offer a rich, strongly typed and discoverable experience. Several advanced, embedded Microsoft Graph API features in the central core library include retry handling, secure redirects, transparent authentication, payload compression, paging through collections and creating batch requests. These features can bring more flexibility to scripts and avoid potential problems when working with Microsoft Graph.

For example, if throttling occurs during a Microsoft Graph call, a retry-after property gives the time to wait before the next request attempt.

Microsoft Graph retry handling
The retry handling feature offers a way to handle throttling on Microsoft Graph.

The code you use needs to accommodate this approach. For example, if you call Microsoft Graph on a schedule, then you need to add how the script handles throttling to successfully execute.

In addition to PowerShell, the Microsoft Graph SDKs currently support Android, Angular, ASP.NET, iOS, JavaScript, Node.js, Java, PHP, Python and Ruby.

To learn more about the Microsoft Graph toolkit, you can view the architectural documentation at the following link.

Ways to use Microsoft Graph

As with any service or platform, it is critical to define how to use it. Microsoft Graph is no different.

There are certain tasks that are ideal for Microsoft Graph due to how complex it is to retrieve the data or perform the same action from the admin portals. Some of these jobs include finding daily meetings schedules from Exchange, checking unfinished tasks across Microsoft 365/Office 365 and showing what Microsoft Teams channels a user belongs to.

In the Microsoft Teams example, you must navigate through each team and review each channel to check your access if you handle this task from the UI. The job is easier when you use PowerShell to query the Microsoft Graph endpoints:

$me = "[email protected]"
$mychannels = New-Object System.Collections.ArrayList
$body = @{}
 
$teams = Invoke-MgGraphRequest `
    -Uri "https://graph.microsoft.com/v1.0/me/joinedTeams" `
    -Method GET `
    -Body $body
 
$teams.value | ForEach-Object {
    $team = $_
    $channel = Invoke-MgGraphRequest `
        -Uri "https://graph.microsoft.com/v1.0/teams/$($team.ID)/channels" ` `
        -Method GET `
        -Body $body
 
    $channel.value | ForEach-Object {
        $ch = $_
        if($ch.id) {
            $members = Invoke-MgGraphRequest `
                -Uri
"https://graph.microsoft.com/v1.0/teams/$($team.ID)/channels/$($ch.id)/members" `
                -Method GET `
                -Body $body
            
            
            $members.value.email | ForEach-Object {
                if($_ -eq $me)
                {
                    $my =
[pscustomobject]@{'TeamID'=$team.ID;'ChannelID'=$ch.id;'Email'=$_;}
                    $mychannels.Add($my)
                }
            }
        }
    }
}
Microsoft Teams channels membership
The results from using Microsoft Graph to find out which Microsoft Teams channels a user belongs to

The principle is the same in terms of actions to perform; it is much quicker and easier to use Microsoft Graph calls. I recommend you take time to learn more about Microsoft Graph, use the Graph Explorer tool and practice with the programming language of choice.

It's beneficial to check the release notes in the current version of Microsoft Graph from this link to see its new or updated capabilities.

Dig Deeper on Windows Server OS and management

Cloud Computing
Enterprise Desktop
Virtual Desktop
Close