Praxisbeispiel für Action Cards: Alert bei geringem Speicherplatz an Microsoft Teams senden und von dort WAC starten

Im Artikel "Systemnachrichten über Webhooks an Microsoft Teams senden" habe ich bereits das Verschicken von Message Cards per PowerShell an Teams beschrieben. Der vorliegende Beitrag behandelt dagegen die so genannten Action Cards. Sie können nicht nur Informationen speichern, sondern über Buttons auch Aktionen auslösen.

Diese Möglichkeit werde ich an einem konkreten Beispiel demonstrieren: Ein PowerShell-Script liest die Laufwerke von bestimmten Servern aus, prüft wieviel Speicher dort jeweils noch prozentual zur Verfügung steht und entscheidet anhand eines Schwellenwerts, ob ein Alert als Action Card per Webhook an Teams gesendet werden soll.

Ein Button öffnet anschließend den Server im Storage-Tool von Windows Admin Center, so dass man dort die Partition vergrößern könnte.

Technische Umsetzung

Action Cards werden über ein JSON-File deklariert und per HTTP-Post an die URL des Teams-Connectors gesendet. Das Konfigurieren eines Teams-Connectors für Webhooks habe ich im oben genannten Artikel beschrieben. Die gleichen Schritte sind auch für Action Cards erforderlich.

Das standardisierte JSON-Format im Zusammen­spiel mit einem HTTP-Request ermöglicht eine plattform­unabhängige Nutzung. So lassen sich neben der PowerShell auch curl oder andere Dienste für das Senden des Webhooks nutzen.

PowerShell bietet zwar Cmdlets, um JSON-Dateien zu erstellen und zu bear­beiten, aber das Erzeugen einer Action Card ist damit relativ umständlich. Daher hat die Community ein spezielles PowerShell-Modul für diesen Zweck entwickelt: PSTeams. Die folgende Anleitung bedient sich dieses Moduls.

Erläuterung des PowerShell-Scripts

Vor dem eigentlichen Design der Action Card müssen diverse Angaben erfasst werden. Dazu zählen die abzufragenden Server, ein Schwellenwert, der den Alert auslöst, die Connector-ID und die URL des eigenen Windows Admin Center.

Dem Array mit den Computernamen können beliebig viele weitere Rechner hinzugefügt werden. Bei einer größeren Anzahl bietet sich ein CSV-Import in das Array an.

# Zu prüfende Computer $TargetComputers = @("Server01", "Server02") # Freier Speicher in Prozent, ab welchem alarmiert werden soll $Threshold = 60 # TeamsID - URL, welche vom Connector generiert wurde $TeamsID = "" # URL des Windows Admin Centers $WACURL = "<https://localhost:6516/>"

Hinweis: Der Wert 60 ist für den Schwellenwert sehr hoch gewählt und dient lediglich dazu, für die Demonstration in jedem Fall einen Alert auszulösen. Praxisnah wären hier 10 oder 20 Prozent freier Laufwerks­speicher.

Mit den folgenden Zeilen wird sichergestellt, dass das notwendige Modul auf dem System installiert und importiert ist:

# ModuleCheck: Installiert PSTeams, falls noch nicht vorhanden try { Get-InstalledModule PSTeams } catch { Install-Module -Name PSTeams -Force } finally { Import-Module PSTeams }

Nun müssen auf dem Server sämtliche Laufwerks­informationen ausgelesen und in Variablen zwischen­gespeichert werden:

# Abfrage der Disk-Informationen $Disks = Get-WmiObject Win32_LogicalDisk -ComputerName $TargetComputer | Select-Object DeviceID, Size,FreeSpace # Iterieren über die angegebenen Computer foreach ($Disk in $Disks){ # Ermitteln des Laufwerksbuchstaben $DiskName = $Disk.DeviceID # Größe des Laufwerks in GibiByte [double]$DiskSpaceGiB = $Disk.Size / (1024 * 1024 * 1024) $DiskSpaceGiB = [math]::Round($DiskSpaceGiB,2) # Freier Speicher in GibiByte [double]$DiskFreeSpaceGiB = $Disk.FreeSpace / (1024 * 1024 * 1024) $DiskFreeSpaceGiB = [math]::Round($DiskFreeSpaceGiB,2) # Freie Speicher in Prozent mit zwei Nachkommastellen [double]$DiskFreePercentage = $DiskFreeSpaceGiB / $DiskSpaceGiB $DiskFreePercentage = [math]::Round($DiskFreePercentage,4) * 100 }

Alle gewünschten Disk-Informationen sind nun in entsprechenden Variablen hinterlegt. $DiskFreePercentage, deren Wert sich aus dem Verhältnis von freiem zu gesamten Speicher ergibt, enthält nun den freien Plattenplatz in Prozent. Davon hängt ab, ob ein Alert zu erzeugen ist.

# Wenn freier Speicher (Prozent) den Threshold unterschreitet, wird ein Teams-Alert gesendet if ($DiskFreePercentage -lt $Threshold){ $WACURLServer = $WACURL + "computerManagement/connections/computer/" + $TargetComputer + "/tools/storage/storage/volumes" # Erstellen der Card-Elemente $Button1 = New-TeamsButton -Name 'Open Client Storage Options' -Link $WACURLServer $Fact1 = New-TeamsFact -Name "Server" -Value "**$($TargetComputer)**" $Fact2 = New-TeamsFact -Name "Partition" -Value "**$($DiskName)**" $Fact3 = New-TeamsFact -Name "Space Total (GibiByte)" -Value "**$($DiskSpaceGiB)**" $Fact4 = New-TeamsFact -Name "Space Free (GibiByte)" -Value "**$($DiskFreeSpaceGiB)**" $Fact5 = New-TeamsFact -Name "Space Free (Percent)" -Value "**$($DiskFreePercentage)**" # Erstellen einer Sektion und Zuordnung der Card-Elemente $Section = New-TeamsSection -Buttons $Button1 -ActivityDetails $Fact1, $Fact2, $Fact3, $Fact4, $Fact5 # Senden der Card Send-TeamsMessage -URI $TeamsID -Color Red -Sections $Section ` -MessageTitle "Alert: Drive $DiskName on $TargetComputer has only $DiskFreePercentage % left!" }

Wenn die ermittelten Prozent den festgelegten Threshold unterschreiten, wird über die Cmdlets des PSTeams-Moduls eine Action Card erstellt. Diese setzt sich aus sogenannten Facts und einem Button zusammen.

Die Facts enthalten die Eigenschaften des betroffenen Laufwerkes. Der Button ruft die URL der Storage-Verwaltung für den Server im Windows Admin Center auf. Dieser Link wird direkt unter der IF-Bedingung erzeugt.

Die Objekte werden zu einem Abschnitt zusammen­gefasst und schluss­endlich per Send-TeamsMessage an die vorgegebene URL übertragen. Im Teams-Channel erscheint die bereits gezeigte Action Card.

Das vollständige Script kann hier heruntergeladen werden.

Fazit

Mit PSTeams haben Admins ein einfach handhabbares Tool zur Hand, um Alerts kombiniert mit einer Handlungs­option zu generieren. Ein solches Script könnte natürlich anschließend per Cron-Job oder Task-Scheduler in regelmäßigen Abständen automatisch laufen.

Das aufgeführte Beispiel zeigt einen einfachen Anwendungsfall, darüber hinaus gibt es sicher viele weitere. So könnten beispielsweise diverse RSS-Feeds von IT-Sicherheits­meldungen per PowerShell empfangen und in Teams gesammelt werden.

Der Button kann neben dem reinen Abrufen einer Website auch HTTP-POST-Requests senden, was nahezu unbeschränkte Möglichkeiten eröffnet. Alerts oder Meldungen ließen sich so durch die Teams-Mitglieder über das Betätigen eines Buttons an weitere Systeme weiter­reichen.

Tickets könnten auf diese Weise eröffnet oder geschlossen, Meldungen in der eigenen ToDo-Liste gespeichert und virtuelle Maschinen in der Cloud bzw. On-Premise gestartet oder gestoppt werden. Sämtliche Tasks, welche nicht vollständig automatisiert, sondern kontrolliert ausgeführt werden sollen, können somit eine Teilauto­matisierung erreichen, indem man über Teams Genehmigungs­schritte dazwischen­schaltet.