PowerShell Invoke-RestMethod für API-Aufrufe verwenden

Was ist eine REST-API?

Eine REST-API (Representational State Transfer Application Programming Interface) legt einen Standard für die Verwaltung von Daten und Vorgängen über standardisierte Aufrufe fest, wobei in der Regel JSON für die Datenkodierung verwendet wird.

Da REST-API-Aufrufe HTTPS (Hypertext Transfer Protocol Secure) verwenden, lassen sie sich leicht in verschiedenen Programmiersprachen, einschließlich PowerShell, implementieren.

Was ist der Unterschied zwischen Invoke-RestMethod und Invoke-WebRequest?

Invoke-RestMethod und Invoke-WebRequest sind zwar ähnlich und teilweise austauschbar, haben aber nicht den gleichen Zweck.

Das Cmdlet Invoke-WebRequest dient dazu, eine Webanforderung zu erstellen. Es wird in der Regel zum Abrufen von Dateien oder Webseiten verwendet, da die Ausgabe den Rohinhalt eines Aufrufs, zum Beispiel HTML (Hypertext Markup Language) oder Kopfzeilen, enthält.

Invoke-RestMethod arbeitet mit REST-API-Aufrufen mit integrierter Serialisierung, das heißt es konvertiert Daten automatisch von JSON – oder XML – in ein PowerShell-Objekt und umgekehrt. Diese Konvertierung erfolgt nur, wenn das Cmdlet Daten in einem Serialisierungsformat empfängt, aber Sie können den Accept-Header auf application/json festlegen, um die Übersetzung zu erzwingen.

Machen Sie sich mit der REST-API-Terminologie vertraut

Um effektiv mit REST-APIs zu arbeiten, sollten Sie sich mit den folgenden Begriffen vertraut machen:

• Uniform Resource Identifier (URI): Ähnlich wie eine URL ist das eine Adresse für eine einzelne Ressource im Internet.
• HTTP-Methoden: Diese bezeichnen eine bestimmte Art von Aktion, wie zum Beispiel die folgenden:
  • POST erzeugt eine neue Ressource.
  • GET ruft Daten über eine oder mehrere Ressourcen ab.
  • PUT aktualisiert eine vorhandene Ressource oder erstellt eine neue, falls sie noch nicht vorhanden ist.
  • DELETE löscht eine Ressource.

Wenn Sie einen REST-API-Aufruf tätigen, müssen Sie mindestens einen URI und eine Methode angeben.

Abbildung 1 zeigt einen Beispiel-URI, der auf die API von GitHub verweist.

Wie funktioniert die Authentifizierung bei einem API-Aufruf?

Zu den gängigen Authentifizierungsmethoden für REST-APIs gehören die Basis-Authentifizierung, OAuth 2.0, Bearer Token und API-Schlüssel. Beachten Sie bitte, dass Tokens aus Sicherheitsgründen nie in Klartext in Skripten gespeichert werden sollten. Stattdessen können Sie sie in Umgebungsvariablen, Secret Vaults oder per sicherer Abfrage einlesen.

Basis-Authentifizierung: Diese Standardauthentifizierung in HTTP umfasst eine Zeichenfolge, die aus dem Benutzernamen und dem Kennwort besteht, wobei die Zeichenfolge in Base64 kodiert und mit jeder Anforderung als Teil des URI gesendet wird. Da die Anmeldeinformationen im Klartext übertragen werden, gilt das nicht als sicher und sollte nur mit HTTPS verwendet werden.

OAuth 2.0: OAuth ist ein offener Autorisierungsstandard, bei dem ein Benutzer einer Anwendung die Erlaubnis zum Zugriff auf Daten mit einem Token anstelle der vollständigen Anmeldedaten erteilt. Das Token wird dann bei nachfolgenden Aufrufen verwendet. Wenn Sie mit Microsoft 365 oder Microsoft Azure arbeiten, ist meistens OAuth 2.0 erforderlich. Die Token erhalten Sie gewöhnlich über eine App-Registrierung in Azure AD. Sie können PowerShell-Module wie MSAL.PS oder Microsoft.Graph für den Abruf der Token nutzen:

Connect-MgGraph -Scopes "User.Read.All", "Group.ReadWrite.All"

Überbringer-Token (Bearer Token): Ein Bearer-Token wird nach der Überprüfung der Anmeldeinformationen des Benutzers an den Client ausgegeben und mit dem Authorization-Header an die REST-API weitergegeben:

$headers = @{
    Authorization = "Bearer $token"
    'Content-Type' = 'application/json'
}

API-Schlüssel: Ein API-Schlüssel (API Key) ist ein eindeutiger Bezeichner, der mit der für die API erforderlichen Methode an eine REST-API übergeben wird.

Wie man eine grundlegende Anfrage in einer REST-API stellt

Im folgenden Abschnitt wird erklärt, wie man einen REST-API-Aufruf mit PowerShell unter Verwendung des GitHub-Beispiels aus dem Abschnitt Terminologie durchführt.

Ich habe bereits ein persönliches Zugriffs-Token über die Einstellungen in meinem GitHub-Profil erstellt und dieses Token der Variablen $token zugewiesen. Ich übergeben das Token als Teil des Authorization-Headers. Achten Sie auf Header-Anforderung User-Agent. Fehlt diese, antwortet GitHub mit einem Fehlercode. Sie können PowerShell-Skript beispielsweise durch den Namen Ihres Tools oder Skripts ersetzen. So sieht die Anfrage aus:

$uri = 'https://api.github.com/issues?state=open'
$headers = @{
    # Tell the API that we want to receive JSON
    Accept = 'application/json'
    # Authenticate with our API token
    Authorization = "token $token"
    # GitHub requires a User-Agent header
    'User-Agent' = 'PowerShell-Script'
}
Invoke-RestMethod -Uri $uri -Headers $headers

Der Code fordert eine Liste offener Probleme von der GitHub-API an.

Das Cmdlet Invoke-RestMethod verwendet GET als Standardmethode, wenn keine angegeben wird.

So senden Sie Daten an eine REST-API

Für das Senden von Daten mit der REST-API verwenden Sie POST und PUT. Diese Methoden erfordern die Übermittlung von Daten in einem Format, das die API verwenden kann, wie zum Beispiel JSON.

Wir erstellen den Textkörper unter Verwendung der integrierten Typen von PowerShell und konvertieren ihn dann mit dem Cmdlet ConvertTo-Json in JSON. Wir fügen auch den Content-Type-Header hinzu, der der API mitteilt, wie die Daten serialisiert werden.

In diesem Beispiel weisen wir einen Benutzer einem GitHub-Problem mit der GitHub-API zu. Es handelt sich um eine einfache Anfrage, die ein Array von Benutzernamen als Anfragetext verwendet und einen längeren Endpunkt als zuvor erfordert:

$uri = 'https://api.github.com/repos/ThePoShWolf/specialk/issues/3/assignees'
$headers = @{
    # Tell the API that we want to receive JSON
    Accept = 'application/json'
    # Authenticate with our API token
    Authorization = "token $token"
    # Tell the API that we are sending JSON
    'Content-Type' = 'application/json'
    # GitHub requires a User-Agent header
    'User-Agent' = 'PowerShell-Script'
}
# Define request body
$data = @{
    assignees = @( 'ThePoShWolf' )
}
Invoke-RestMethod -Uri $uri -Method POST -Headers $headers -Body ($data | ConvertTo-Json -Compress)

Bei Erfolg gibt der API-Aufruf das Problemobjekt zurück. Wenn allerdings ein Fehler vorhanden ist, stoppt PowerShell. Durch einen Try-Catch-Block bekommen Sie die Fehler detailliert zurückgemeldet:

# Send the request in a try block
try {
    $response = Invoke-RestMethod -Uri $uri -Method POST -Headers $headers -Body ($data | ConvertTo-Json -Compress)
    Write-Output "Zuweisung erfolgreich: $($response | ConvertTo-Json -Depth 5)"
} catch {
    Write-Error "Fehler beim Senden der Zuweisung: $_"
}

Durch den Zusatz -Depth 5 werden die verschachtelten JSON-Objekte leichter lesbar dargestellt.

Warum sollten Admins lernen, mit API-Aufrufen in PowerShell zu arbeiten?

Administratoren, die lernen, mit APIs zu arbeiten, haben den Vorteil, tiefere Einblicke in ihre Umgebung zu erhalten und ihre Automatisierungsfähigkeit über die lokale Infrastruktur hinaus zu erweitern. Dieses Wissen kann SaaS-Produkte in Automatisierungs-Workflows integrieren, was Ihrer Organisation zugutekommt und Ihre Innovationsfähigkeit stärkt.

Die Microsoft Graph REST API bietet Administratoren die Möglichkeit, alle Aspekte der Microsoft-365-Plattform zu verwalten. Nehmen Sie sich etwas Zeit, um mit API-Aufrufen in PowerShell zu experimentieren, um Automatisierungsskripte für häufige Aufgaben zu erstellen, und sehen Sie, wie das Ihre Betriebsabläufe beschleunigt.