PowerShell & Scripting

Invoke-RestMethod (REST-API-Aufrufe)

Allgemeine Infos

Invoke-RestMethod (Alias irm) sendet HTTP- und HTTPS-Anfragen an REST-Webdienste und wandelt JSON- oder XML-Antworten automatisch in Objekte um. Damit bindest Du Microsoft Graph, Azure-REST-APIs, Ticket-Systeme, Firewalls oder Monitoring-Lösungen direkt in Skripte ein, auch wenn es dafür kein PowerShell-Modul gibt.

Invoke-WebRequest ist das Gegenstück für die vollständige HTTP-Antwort: Es liefert ein Objekt mit StatusCode, Headers, Content und RawContent und eignet sich für Downloads, Header-Auswertung oder HTML-Seiten. Invoke-RestMethod gibt dagegen nur den bereits umgewandelten Inhalt zurück.

PowerShell 7 hat beide Cmdlets stark erweitert, unter anderem mit eingebauter Authentifizierung, Paginierung, Wiederholungen und Statuscode-Variablen. Seit 7.4 kodiert PowerShell Anfragen standardmäßig in UTF-8. Viele dieser Parameter gibt es in Windows PowerShell 5.1 nicht.

Funktionsweise & Details

Die wichtigsten Funktionen:

  1. Methode und Body: -Method GET, POST, PUT, PATCH oder DELETE. Bei GET hängt eine Hashtable in -Body ihre Werte als Query-Parameter an. Für JSON-Bodies wandelst Du die Daten mit ConvertTo-Json um und setzt -ContentType 'application/json'.
  2. Authentifizierung (ab 6.0): -Authentication Bearer oder OAuth mit -Token (SecureString), Basic mit -Credential. Über unverschlüsseltes HTTP verweigert PowerShell das ohne -AllowUnencryptedAuthentication.
  3. Paginierung (ab 6.0): -FollowRelLink folgt Link-Headern nach RFC 5988. Microsoft Graph nutzt stattdessen @odata.nextLink, das wertest Du in einer Schleife aus.
  4. Fehler und Wiederholungen: -MaximumRetryCount und -RetryIntervalSec wiederholen bei Statuscodes 400 bis 599, bei 429 mit Retry-After wird dieser Wert genutzt. Ab 7.0 speichert -StatusCodeVariable den Statuscode, -SkipHttpErrorCheck verhindert Ausnahmen bei Fehlerantworten.
  5. -ResponseHeadersVariable (ab 6.0) liefert die Antwort-Header, -SkipCertificateCheck (ab 6.0) überspringt die Zertifikatsprüfung und ist nur für Tests gedacht.

Vorteile & Nutzen

  • Integration ohne Modul: Jede REST-API lässt sich ansprechen, auch von Herstellern ohne PowerShell-Unterstützung
  • Objekte statt JSON-Text: Eigenschaften der Antwort stehen direkt für Filter, Schleifen und Exporte bereit
  • Robuste Automatisierung: Eingebaute Wiederholungen und Statuscodes fangen Drosselung (429) und kurze Ausfälle ab
  • Sichere Authentifizierung: Tokens werden als SecureString übergeben und nur über HTTPS gesendet

Praxisbeispiel

Ein Möbelhersteller mit 380 Mitarbeitenden nutzt ein cloudbasiertes Ticket-System ohne PowerShell-Modul. Bei jedem fehlgeschlagenen nächtlichen Backup soll automatisch ein Ticket entstehen. Der Admin ruft die REST-API des Ticket-Systems mit Invoke-RestMethod, Bearer-Token aus SecretManagement und einem JSON-Body auf. -MaximumRetryCount fängt kurze Ausfälle des Dienstes ab, über -StatusCodeVariable protokolliert das Skript Fehler. Fehlgeschlagene Sicherungen landen seitdem ohne manuelles Zutun im Ticket-System.

Worauf sollte man achten?

  • Tokens und API-Schlüssel nicht im Skript speichern, sondern aus SecretManagement oder Azure Key Vault laden
  • -SkipCertificateCheck nicht produktiv verwenden, es schaltet die gesamte Zertifikatsprüfung ab
  • Antworten mit mehreren Objekten kommen als ein Array durch die Pipeline, bei Bedarf in Klammern setzen oder an Write-Output übergeben
  • Für Microsoft Graph das Graph PowerShell SDK oder Invoke-MgGraphRequest bevorzugen, weil sie Token-Erneuerung übernehmen
  • In Skripten, die auch unter Windows PowerShell 5.1 laufen, auf Parameter wie -Authentication oder -StatusCodeVariable verzichten

Fazit

Invoke-RestMethod macht PowerShell zum Integrationswerkzeug für jede REST-API. Unter PowerShell 7 erledigen eingebaute Parameter für Authentifizierung, Wiederholung und Paginierung vieles, was früher eigener Code war.

Weiterführende Links

Verwandte Artikel