Microsoft Teams – 3. Teil der Graph PowerShell Reihe

MVP Damien Scoles berichtet über seine Erfahrungen mit Microsoft Graph. In seinem dritten Artikel geht er näher auf Teams ein und stellt das Modul Microsoft.Graph.Teams vor. Lies hier im letzten Teil, welche Empfehlungen er zu diesem Modul hat.

Weitere Einblicke 

In den ersten beiden Artikeln dieser Reihe haben wir die Graph PowerShell und ihre zahlreichen Untermodule und Cmdlets kennengelernt und uns dann mit der Verwendung von Graph PowerShell und Exchange Online beschäftigt. Nun erkunden wir Microsoft Teams und Graph PowerShell und stoßen dabei auf ein anderes Setup. Der größte Unterschied besteht darin, dass wir ein eigenes Untermodul namens Microsoft.Graph.Teams haben, das Hunderte von verschiedenen Cmdlets enthält. Wir finden aber auch Gemeinsamkeiten, wenn 'Teams'-Cmdlets außerhalb dieses Code-Sub-Moduls existieren:

• Graph.Compliance
• Graph.Reports
• Graph.Security
• Graph.Teams
• Graph.Users.Actions
• Graph.Users.Functions
• MicrosoftGraph

Mit einer kurzen PowerShell-Anweisung können wir jedes Cmdlet mit dem Wort "Team" finden und eine Zählung nach Untermodul erhalten:

$uniqueTeamsCmdletSources = Get-Command *team* | Where-Object Source -Like *graph* | Sort-Object Source -Unique

$uniqueTeamsCmdletSources.Source |

   ForEach-Object {

      Write-Host $_ -ForegroundColor Green -NoNewline

      Write-Host ' - ' -NoNewline

      Write-Host "$((Get-Command *team* -Module $_).Count)"

   }

Das ist das Ergebnis:

Anzahl der Cmdlets pro Sub-Modul

Das Untermodul Microsoft.Graph.Teams hat mehr Cmdlets, die nicht das Substantiv 'Team' enthalten, nämlich insgesamt 654 Cmdlets. Es verbleiben 121 Cmdlets ohne das Substantiv 'Team'. Zur Bestätigung:

(Get-Command -Module Microsoft.Graph.Teams | Where-Object Name -NotLike *team*).Count

Microsoft Teams PowerShell-Aufgaben

Wie bei Exchange Online werden auch hier einige häufige Aufgaben kurz beschrieben, die mit dem speziellen Microsoft Teams PowerShell-Modul durchgeführt werden können.

• Automatische Präsenz/Anwesenheit (Auto attendant)
• Besprechungskonfiguration
• Einwahl planen (dial plan)
• Einwahl-Konferenz  (Dial-in conference
• Einstellungen für Nutzer in Teams 
• Shifts/Verschiebungen in und von Teams shifts
• Gast-Konfiguration
• Zugang gewähren
• Richtlinien für Kanäle
• Richtlinien für Anrufe
• Richtlinien für Notfälle/Notrufe (emergency policies
• Richtlinien für Besprechungen 
• Konfiguration von Schichten (Shifts configuration
• und vieles mehr

 Berechtigungen einschränken 

Obwohl dies bereits im ersten und zweiten Artikel dieser Serie behandelt wurde, sei hier noch einmal darauf hingewiesen, dass wir bei der Verwendung von Graph PowerShell die Berechtigungen korrekt einschränken müssen, um die Teams-Cmdlets verwenden zu können.

$AllCmdlets = @()

Foreach ($Cmdlet in $GraphTeamsCmdlets) {

   Try {

      $Line = Find-MgGraphCommand $Cmdlet.Name -ERRORACTION STOP | 

         Select Command,Method,URI,Permissions

   } Catch {

   }

   $AllCmdlets += $Line

}

$AllCmdlets | 

   Select Command,Permisions

Wir erhalten Folgendes zurück:

Gekürzte Liste der benötigten Berechtigungen

Eine lange Liste von Berechtigungen wird benötigt, um die unzähligen Cmdlets im Teams-Sub-Modul von Graph auszuführen. Die vollständige Liste kann hier heruntergeladen werden.

Wir können auch eine Zusammenfassung aller delegierten Teams-Berechtigungen mit einem einfachen Einzeiler erstellen:

Find-MgGraphPermission teams -PermissionType Delegated

Liste der Berechtigungen für Teams-Cmdlets in Graph

Die Unterschiede im Detail

All diese Cmdlets sind schön und gut, bis ein Administrator eine Aufgabe ausführen muss und entscheiden muss, in welchem Modul er die Aufgabe ausführen soll. Wie sollte ein Administrator also an dieses Modul herangehen? Eine Möglichkeit ist, die Cmdlets gebündelt zu betrachten, vielleicht nach Verben oder Substantiven. Wenn man eine bestimmte Aufgabe ausführen möchte, wie z. B. Teamreaktionen verwalten, wäre es besser, nach Substantiven zu suchen. Nachfolgend ein Beispiel für die Gruppierung nach Substantiven, um eine Vorstellung davon zu bekommen, was in Microsoft Teams vs. Microsoft.Graph.Teams verfügbar ist.

Beispiele für Unterschiede

Wenn wir die Cmdlet-Typen mit den verfügbaren Cmdlets in den einzelnen Modulen vergleichen, sehen wir katastrophale Unterschiede bei den Typen/Anzahl der Cmdlets:

Vergleich der verfügbaren Cmdlets

Im Folgenden werden einige Gruppen von Cmdlets zum Vergleich aufgelistet. Die obigen Beispiele sind nach Schlüsselwörtern aufgeschlüsselt - 'clear', team reactions und dial.

Benutzer, die neu in Microsoft.Graph.Teams sind, sollten sich eine vollständige Liste der Cmdlets besorgen und die vertrauten Cmdlets nach ihrem Namen aufschlüsseln. Auf diese Weise können sie vielleicht die Cmdlets identifizieren, die sie für ihre Verwaltungsaufgaben verwenden sollten. Nach der Identifizierung solltest du die Hilfe und die Beispiele für jedes Cmdlet durchlesen, um mit den neu entdeckten Cmdlets Einzeiler und Skripte zu erstellen.

Praktische Anwendungen von Teams

Die Diskussion über Cmdlets und ihre Einteilung in Gruppen kann für diejenigen interessant sein, die herausfinden möchten, was in Microsoft Teams mit Graph PowerShell verwaltet werden kann. Im folgenden Abschnitt werden einige Beispielszenarien vorgestellt, in denen Graph PowerShell für Administratoren nützlich ist.

Team-Mitgliedschaft

Durch die Kombination von Cmdlets wie diesen drei: Get-MgTeam, Get-MgUser und Get-MgUserJoinedTeam können wir ein Skript erstellen, das die Mitgliedschaft in Microsoft Teams überprüft. Warum sollten wir das tun? Ein Beispielszenario wäre eine Migration von Tenant-zu-Tenant, bei der wir überprüfen müssen, ob die Teammitgliedschaften durch einen externen Prozess erstellt wurden. Oder um zu überprüfen, ob die Mitglieder einer Gruppe auch Mitglieder ihrer jeweiligen Teams sind.

Einzelner Nutzer

Get-MgUserJoinedTeam -UserId damian@powershellgeek.com

Mehrere Nutzer

Get-MgUser | ForEach-Object {    

   Write-Host "$($_.DisplayName)" -ForegroundColor Green 

   $Groups = Get-MgUserJoined

   Team -UserId $_.Id

   If ($Groups.Count -eq 0 ) { 

      Write-host 'No Groups' -ForegroundColor Yellow 

   } Else {

      $Groups 

   }

}

Mitglieder eines Teams

Get-MgTeamMember -TeamId cfdba387-1319-4f6b-a883-8700046f07e7

Liste der Mitglieder eines Teams (Standardansicht)

$Members | Format-List

Zusätzliche Eigenschaften

Beachte, dass jedes Teammitglied eine Eigenschaft mit dem Namen 'zusätzliche Eigenschaften' hat, in der wir das Schlüssel/Wert-Paar (key/value pair) 'userId' sehen.

Da wir nun eine Liste der Mitglieder haben, können wir die Id des Nutzers abrufen, die dann wiederum für die Suche nach dem vollständigen Nutzerkonto verwendet werden kann:

$Members.AdditionalProperties.userId

Beachte, dass bei 'userId' zwischen Groß- und Kleinschreibung unterschieden wird, was wir uns für zukünftige Eigenschaften von Graph-Objekten merken sollten. Jetzt können wir in einer Schleife alle Nutzereigenschaften für Gruppenmitglieder finden:

$Members.AdditionalProperties.userId | ForEach-Object { Get-MgUser -UserId $_ }

Liste der Nutzer, ihre IDs, E-Mail-Adressen und UserPrincipalNames (UPN) 

Mitglieder aller Gruppen

Get-MgTeam | ForEach-Object { 

   Write-Host "$($_.DisplayName)" -ForegroundColor Green

   $Members = Get-MgTeamMember -TeamId $_.id

   $Members.AdditionalProperties.userId | 

   ForEach-Object { 

      Get-MgUser -UserId $_

   }   

}

Verwaltung von Teams-Kanälen 

Ein weiterer Bereich, in dem sich die Cmdlets zwischen den Modulen unterscheiden, ist die Kanalverwaltung. Das Microsoft Teams Modul hat 14 Cmdlets mit dem Substantiv 'Channel', während das Microsoft.Graph.Teams PowerShell Modul 283 Cmdlets hat:

Eine kleine Auswahl von Teams-Cmdlets, die sich auf das Substantiv 'Channel' beziehen

Unter diesen Cmdlets werden wir viele Ähnlichkeiten finden:

Beispiel – Mitglieder in Teams verwalten

Teams

Add-TeamChannelUser, Get-TeamChannelUser and Remove-TeamChannelUser

Graph

Add-MgTeamChannelMember, Add-MgTeamPrimaryChannelMember, Add-MgTeamworkDeletedTeamChannelMember, Get-MgGroupTeamChannelMember, Get-MgGroupTeamChannelMemberCount, Get-MgGroupTeamPrimaryChannelMember, Get-MgGroupTeamPrimaryChannelMembe rCount, Get-MgTeamChannelMember, Get-MgTeamChannelMemberCount, Get-MgTeamPrimaryChannelMember, Get-MgTeamPrimaryChannelMemberCount

Get-MgTeamworkDeletedTeamChannelMember, Get-MgTeamworkDeletedTeamChannelMemberCount, New-MgGroupTeamChannelMember, New-MgGroupTeamPrimaryChannelMember, New-MgTeamChannelMember, New-MgTeamPrimaryChannelMember, New-MgTeamworkDeletedTeamChannelMember, Remove-MgGroupTeamChannelMember, Remove-MgGroupTeamPrimaryChannelMember, Remove-MgTeamChannelMember, Remove-MgTeamPrimaryChannelMember, Remove-MgTeamworkDeletedTeamChannelMember, Update-MgGroupTeamChannelMember, Update-MgGroupTeamPrimaryChannelMember, Update-MgTeamChannelMember, Update-MgTeamPrimaryChannelMember and Update-MgTeamworkDeletedTeamChannelMember

Wir sehen, dass die Graph PowerShell-Cmdlets zahlreicher sind und sich mehr auf bestimmte Aspekte der Mitgliedschaft von Benutzern in einem Team-Channel konzentrieren. Außerdem werden Nutzer in den Cmdlets als Mitglieder bezeichnet, während die gleiche Nomenklatur in Teams Nutzer als 'User' und nicht als Mitglieder bezeichnet.

Team-Channel-Mitgliedschaften abrufen

Zuerst benötigen wir die ID des Teams, dessen Channel-Mitgliedschaften wir abrufen möchten:

Get-MgTeam

Kopiere die ID des Teams und erhalte eine Liste der Channels:

Get-MgTeamChannel -TeamId cfdba387-1319-4f6b-a883-8700046f07e7

Kopiere die ID des Channels und ermittle nun die Mitglieder dieses Channels:

Get-MgTeamChannelMember -ChannelId 19:1b01cc16e436489dbf22462dfce1443d@thread.skype -TeamId cfdba387-1319-4f6b-a883-8700046f07e7

Was, wenn wir eine Liste aller Mitglieder aller Teams/Channels brauchen?

$Teams = Get-MgTeam | Select DisplayName,Id

Foreach ($Team in $Teams) {

   $Channels = Get-MgTeamChannel -TeamId $Team.Id

   Foreach ($Channel in $Channels) {

      $AllMembers = $Null
  
      $AllMembers = @()

      $JoinedMembers = $Null

      $JoinedMembers = @()

      $Members = Get-MgTeamChannelMember -ChannelId $Channel.Id -TeamId $Team.Id

      Write-Host "$($Team.DisplayName)" -ForegroundColor Green -NoNewline

      Write-Host " / $($Channel.DisplayName) / " -ForegroundColor Yellow -NoNewLine

      $MemberCount = $Members.Count

      If ($MemberCount -gt 2) {

         Foreach ($Member in $Members) {

            $AllMembers += $Member.AdditionalProperties.email

         }

         $JoinedMembers = $AllMembers -join ','

         $JoinedMembers

      } Else {

         Write-Host "$($Member.AdditionalProperties.email)"

      }

   }

}

Wenn du diesen Code ausführst, erhältst du diese Ergebnisse:

Den Berechtigungen zustimmen

Beachte, dass du den folgenden Berechtigungen zustimmen musst, damit es funktioniert: Team.ReadBasic.All,ChannelMember.Read.All.

Neue Teams erstellen

In diesem Beispiel möchte eine Beratungsunternehmen jedes Mal ein neues Team erstellen, wenn ein Kunde an Bord kommt und Unterstützung benötigt. Mit der PowerShell können wir das Team erstellen, Kanäle anlegen und jedem Team die Mitglieder hinzufügen, die für die Projektarbeit benötigt werden.

Zunächst haben wir eine CSV-Eingabedatei, die wir für die Konfiguration der neuen Teams verwenden:

Name, Description, AllowAddRemoveApps, AllowCreatePrivateChannels, AllowCreateUpdateChannels, AllowDeleteChannels, AllowCreateUpdateRemoveConnectors, AllowCreateUpdateRemoveTabs, Guest-AllowCreateUpdateChannels, Guest-AllowDeleteChannels

"Project Falcon","Falcon, llc - client team",$False,$True,$True,$False,$True,$False,$False,$False

"Big Box, Inc.","Big Box, Inc. - Banking Industry",$False,$True,$True,$True,$True,$False,$False,$False

Mit dem folgenden PowerShell-Codeblock können wir die neuen Teams erstellen:

Foreach ($Team in $Teams) {

   $params = @{

      "template@odata.bind" = "https://graph.microsoft.com/v1.0/teamsTemplates('educationClass')"

      DisplayName = $Team.Name

      Description = $Team.Description

      Visibility = $Team.visibility

      MemberSettings = @{

         AllowAddRemoveApps = $Team.allowAddRemoveApps

         AllowCreatePrivateChannels = $Team.AllowCreatePrivateChannels

         AllowCreateUpdateChannels = $Team.allowCreateUpdateChannels

         AllowCreateUpdateRemoveConnectors = $Team.allowCreateUpdateRemoveConnectors

         AllowCreateUpdateRemoveTabs = $Team.allowCreateUpdateRemoveTabs

         AllowDeleteChannels = $Team.allowDeleteChannels

      }

      GuestSettings = @{

         AllowCreateUpdateChannels = $Team.AllowCreateUpdateChannels

         AllowDeleteChannels = $Team.AllowDeleteChannels

      }

   }

   

   Try {

      New-MgTeam -BodyParameter $params -ErrorAction STOP

   } Catch {

      Write-Host 'Failed to create team: ' -ForegroundColor Red -NoNewline

      Write-Host "Error message - $_.Exception.Message" -ForegroundColor Yellow

   }

}

Nachdem der Code ausgeführt wurde, gibt es keine Rückmeldung, so dass wir Get-MgTeam ausführen müssen, um die Erstellung zu überprüfen:

Neue Teams werden im roten Rechteck

Dann brauchen wir eine Art Input-CSV für die Channels:

Team,ChannelName,Members,Description,membershipType

"HR Department",InternalProject-Vision,,"Effort to upgrade ERM app.",standard

"HR Department",InternalProject-Money,,"Effort to improve salaries.",private

Mit dieser CSV-Datei können wir den folgenden PowerShell-Codeblock ausführen:

Foreach ($Channel in $TeamsChannels) {

   $teamId = (Get-MgTeam | Where-Object DisplayName -eq $Channel.Team).Id

   $params = @{

      "@odata.type" = "#Microsoft.Graph.channel"

      MembershipType = $Channel.MembershipType

      DisplayName = $Channel.ChannelName

      Description = $Channel.Description

   }

   Try {

      New-MgTeamChannel -TeamId $teamId -BodyParameter $params -ErrorAction STOP

   } Catch {
 
      Write-Host 'Failed to create channel in Team: ' -ForegroundColor Red -NoNewline

      Write-Host "Error message - $_.Exception.Message" -ForegroundColor Yellow

   }

}

Dies führt zu den folgenden Ergebnissen in der Beispiel-CSV:

Wir sehen unsere zwei neuen Kanäle, die dem HR-Team hinzugefügt wurden

Fazit – abschließende Gedanken

Microsoft Teams ist ein ebenso komplexes Produkt wie Exchange Online. Es gibt hunderte von Einstellungen und Feinheiten, die berücksichtigt und gesichert werden müssen, um das Beste aus Teams herauszuholen. Mit dem Microsoft.Graph.Teams-Modul können wir einige Einstellungen, Teams, Kanäle und Nutzer mit PowerShell verwalten und bearbeiten. Es gibt einige Operationen, die nicht möglich sind, z. B. gibt es keinen Grant-Satz von Cmdlets, so dass diese Operationen im PowerShell-Modul von Microsoft Teams durchgeführt werden müssen. Wie bei allem in Teams wird es einige Zeit dauern, bis die Berechtigungen korrekt sind, und es ist zusätzliche Arbeit erforderlich, um die BodyParameter-Einstellungen zu erstellen, damit die Änderungen korrekt vorgenommen werden können. Der Tipp hier ist, die Hilfe zu benutzen und einige Beispiele zu üben. Letztendlich ist dieses Untermodul sehr nützlich und mehr als die Exchange-Cmdlets in Graph – es lohnt sich für Microsoft Teams-Administratoren, es zu lernen.

Weiterführende Links

• ScriptRunner Graph ActionPacks
• Alle drei Teile unserer Graph PowerShell Serie: SDK (Teil 1), Exchange Online (Teil 2), Microsoft Teams (Teil 3)
• Jetzt ScriptRunner testen
• ScriptRunner: Buche hier direkt deine Demo und sprich mit einem Produktexperten