M365 PowerShell

Get-MgTeam: How to Retrieve Microsoft Teams Details with Graph PowerShell

This guide demonstrates how to use the Get-MgTeam cmdlet in Microsoft Graph PowerShell to retrieve Microsoft Teams information. Learn how to list all teams, filter specific teams, and fetch detailed team properties with practical examples.

The Get-MgTeam cmdlet is part of the Microsoft Graph PowerShell module and is used to retrieve information about Microsoft Teams within an organization. This cmdlet is particularly useful for administrators who need to manage and monitor their Microsoft Teams environments.

Prerequisites

You need to be a Teams Administrator.
Install the Graph PowerShell module by running the command: Install-Module Microsoft.Graph -Scope CurrentUser.
Connect to Graph PowerShell with the scope 'Group.ReadWrite.All' by running the command: Connect-MgGraph -Scopes "Group.ReadWrite.All".

Syntax Basics

Get-MgTeam [-TeamId <String>] [-All] [-Filter <String>] [-Search <String>] [-Property <String[]>] [<CommonParameters>]

Parameters Explanation

-TeamId <String>: Specifies the ID of the Team you want to retrieve. If you know the specific Team ID, you can use this parameter to get details about that particular Team.
-All: Retrieves all Teams in the organization. This parameter is useful when you need to get information about every Team.
-Filter <String>: Filters the Teams based on specific criteria. The filter must follow the OData query standards.
-Search <String>: Searches for Teams based on a specified string. This is useful for finding Teams that match a certain keyword in their display name or other searchable properties.
-Property <String[]>: Specifies which properties to include in the results. By default, the cmdlet returns a standard set of properties, but you can use this parameter to request specific properties.
<CommonParameters>: Supports common parameters used by all PowerShell cmdlets, such as -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, and -Verbose. These parameters help in controlling the cmdlet's behavior and output.

Usage Examples

Example 1: Retrieve All Teams

Get-MgTeam -All

This command retrieves all Teams in the organization.

Example 2: Retrieve a Specific Team by Team ID

Get-MgTeam -TeamId "team-id"

Replace "team-id" with the actual ID of the Team you want to retrieve.

Example 3: Filter Teams Based on a Property

Get-MgTeam -Filter "displayName eq 'MSFT'"

This command retrieves Teams with the display name "MSFT".

Example 4: Retrieve Specific Properties of All Teams

Get-MgTeam -All -Property "id", "displayName"

This command retrieves only the ID, display name, and description properties of all Teams.

Simple Scripts Illustrating Get-MgTeam Cmdlet Usage

Script to List All Teams and Display Their Names and Descriptions

$teams = Get-MgTeam -All -Property "displayName", "description"
$teams | ForEach-Object {
    "Team Name: $($_.displayName) Description: $($_.description)"
}

This script fetches all the Teams within the tenant, loops through them, and displays the team name and description.

Script to Find Teams Containing "Sales" in Their Display Name

$teams = Get-MgTeam -All | Where-Object { $_.displayName -like '*Sales*' }
$teams | ForEach-Object {
    "Team ID: $($_.Id) Team Name: $($_.displayName)"
}

This script fetches all the Teams that contain ‘Sales’ in the display name, loops through them, and displays their team ID and name.

Possible Errors

Authentication Error

Get-MgTeam : Authorization_RequestDenied

Ensure you have the necessary permissions to execute this cmdlet. Typically, you need to be a Teams administrator or have the required delegated permissions.

Invalid Team ID

Get-MgTeam : Resource 'team-id' does not exist or one of its queried reference-property objects are not present.

Verify that the Team ID is correct and that the Team exists in your organization.

Filter Syntax Error

Get-MgTeam : Invalid filter clause

Ensure that your filter syntax adheres to the OData query standards. Refer to the Microsoft Graph documentation for valid filter options.

Cmdlet Tips

Use the -All Parameter: When you need to retrieve information about all Teams, use the -All parameter to ensure you get a complete list.
Optimize Filters and Searches: Using filters and search parameters can significantly reduce the amount of data returned, making your scripts more efficient.
Select Specific Properties: When you only need certain properties, use the -Property parameter to specify which ones. This reduces the amount of data processed and can improve performance.
Error Handling: Always include error handling in your scripts to manage common issues like authentication problems or invalid input.

Frequently Asked Questions

1. What is Get-MgTeam used for?

Get-MgTeam is a Microsoft Graph PowerShell cmdlet used to retrieve information about Microsoft Teams, such as their IDs, display names, and properties.

2. How can I list all teams in my tenant?

Use the following command to list all teams:

Get-MgTeam -All

3. How can I retrieve details of a specific team?

Use the -TeamId parameter to fetch details of a specific team:

Get-MgTeam -TeamId "<TeamId>"

4. Can I filter teams based on their visibility (e.g., private)?

You can filter teams after retrieval using Where-Object. Example:

$Teams = Get-MgTeam -All
$PrivateTeams = $Teams | Where-Object { $_.Visibility -eq "Private" }

5. How can I export team details to a CSV file?

Use this script to export team details like name, ID, and visibility:

$Teams = Get-MgTeam -All
$Teams | Select-Object DisplayName, Id, Visibility | Export-Csv -Path "C:\Path\To\Teams.csv" -NoTypeInformation

Conclusion

The Get-MgTeam cmdlet is a powerful tool for Microsoft Teams administrators, enabling them to retrieve detailed information about Teams within their organization. By understanding its parameters and possible errors, you can effectively use this cmdlet to manage and monitor your Teams environment.

For more details and additional examples, refer to the official Get-MgTeam Microsoft documentation.