Benutzung der neuen MOVEit 2018 REST API mit PowerShell

Die MOVEit-Konsole oder –Webschnittstelle funktioniert wunderbar für alltägliche Verwaltungsaufgaben oder um einmalige Workflows zu erstellen, aber es gibt Situationen, in denen man besser MOVEit Automation für die Automation benutzt.

Vielleicht haben Sie einen einfachen MOVEit externen Prozess, von dem aus Sie ein MOVEit-Task anstoßen möchten. Oder vielleicht ist MOVEit Automation nur eine Komponente in einem viel größeren vielschrittigen Prozess. Wie auch immer dem sei, eine API ist unabdingbar, um die Funktionen eines Produktes aus der Ferne aufzurufen, ohne die Notwendigkeit einer grafischen Benutzeroberfläche.

MOVEit  Automation hatte schon immer eine API, aber sie war nicht immer so einfach zu benutzen. MOVEit Automation 2018 bietet nun eine moderne REST API. Eine REST API macht es möglich, mit MOVEit Automation via HTTP zu interagieren. Bezüglich des Clients gibt es keine nenneswerten Restriktionen. Das bedeutet, dass man Code in seiner bevorzugten Sprache schreiben kann und dann mit verschiedenen Dingen in MOVEit arbeiten kann.

Dieser Artikel konzentriert sich auf die Benutzung von PowerShell mit der REST API von MOVEit. Wie Sie in weiteren Artikeln sehen werden, muss man nicht unbedingt PowerShell verwenden, um mit der API zu arbeiten, es ist aber eine beliebte Wahl unter IT-Fachleuten, die Skripte für MOVEit Automation schreiben möchten.

Um zu verstehen, wie man PowerShell verwenden kann, um Skripte für MOVEit Automation zu schreiben, müssen Sie erst einmal die PowerShell-Kommandos kennen, die dies möglich machen. Diese Kommandos müssen HTTP-Anfragen mit verschiedenen Verben wie GET, POST, PUT, usw. machen können, die die MOVEit API verstehen kann.

PowerShell kann auf zwei Arten HTTP-Anfragen schicken: Invoke-RestMethod und Invoke-WebRequest. Beide schicken HTTP-Anfragen zur API auf die gleiche Art, aber Invoke-RestMethod hat einige Extra-Funktionalitäten, wie das Parsing von jeglichem Output, den die REST API zurückgibt. Beide Kommandos können benutzt werden, aber wenn Sie gerade erst anfangen, ist es wahrscheinlich besser Invoke-RestMethod zu benutzen. Dieses Kommando ist das Hauptkommando, das alle Aktivitäten von und zu MOVEits REST API koordinieren wird. Der Rest des Codes bereitet nur auf die Aufrufe vor.

Genug mit der Theorie, schauen wir den Code an.

Zuerst einmal ist es immer gut, einige gemeingültige Attribute als Variablen am Anfang des Skripts zu deklarieren und diese dann im Skript zu referenzieren. Um mit der MOVEit REST API zu arbeiten, müssen Sie erst einmal einen Zugangs-Token erhalten und diesen Zugangs-Token während der gesamten Zeit, in der Sie mit der API arbeiten, zur Authentifizierung benutzen. Um den Zugangs-Token zu erhalten, müssen Sie die Authorization Token API benutzen. Diese API benötigt drei Attribute – einen Benutzernamen, ein Passwort und eine Methode, die Sie authentifizieren.

Ich habe erwähnt, dass die Variablen im Skript gespeichert werden können, aber dann auch, dass man ein Passwort braucht. Wir brauchen ein Passwort und es muss im Skript referenziert werden, aber es muss nicht in einfachem Text gespeichert werden. Um das zu umgehen, kann man die PowerShell-Referenzen einmal auf der Festplatte ablegen und dann so viele Male wie nötig referenzieren.

Zuerst speichert man den MOVEit-Benutzernamen und das Passwort auf der Festplatte. Dies muss nur einmal gemacht werden. Dies wird nicht in ihrem Skript stehen.

PS> Get-Credential | Export-CliXml -Path 'C:\MOVEitAutomationCred.xml'

Wenn Sie Benutzernamen und Passwort angeben, werden diese auf der Festplatte gespeichert sein. Sie können sie jetzt durch das Skript referenzieren.

Nun zum Skript: Zuerst einmal muss man Benutzernamen und Passwort entschlüsseln. Dafür erstelle ich eine Hashtabelle von Attributen, um sie dort zusammen mit den anderen Attributen, die ich brauche, zu speichern.

PS> $cred = Import-CliXml -Path 'C:\MOVEitAutomationCred.xml'
 PS> $apiConfig = @{
 >>>    UserName = $cred.UserName
 >>>    Password = $cred.GetNetworkCredential().Password
 >>>    GrantType = 'password'
 >>>    MoveItHost = ''
 >>> }

Von den Attributen in der Hashtabelle kann man alle anderen Komponenten, die man braucht, ableiten. Zuerst muss ich die entsprechende HTTP-Endpunkt-URL erstellen, um den Zugangs-Token zu erhalten.

PS> $authEndpointUrl = "https://$($apiConfig.MoveItHost)/webadmin/api/v1/token"
 PS> $authHttpBody = "grant_type=$($apiConfig.GrantType)&username=$($apiConfig.UserName)&password=$($apiConfig.Password)"

Wenn ich alle Attribute erstellt habe, kann ich den ersten Aufruf zu der MOVEit API machen, um den Zugangs-Token zu erhalten. Bevor ich das aber machen kann, muss ich PowerShell “tricksen”, um mit meiner Demo-API zu interagieren, da sie ein selbstsigniertes Zertifikat benutzt.

Da MOVEit Automations API mit einem Zertifikat SSL-verschlüsselt ist, muss man eine HTTPS URL benutzen.  In einigen Instanzen (meiner Demo-Umgebung zum Beispiel) ist das Zertifikat auf dem MOVEit Automation Server selbstsigniert.  Das bedeutet, dass mein Client (PowerShell) ihm nicht vertraut. In einer Produktionsumgebung wird dies wahrscheinlich keine Rolle spielen. Aber hier muss ich einen .NET Trick benutzen, um in dieser Demonstration das Arbeiten mit MOVEit REST API zu zeigen.

PS> [System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true }

Sobald ich die Benutzung eines selbstsignierten Zertifikats erlaube, kann ich meinen ersten Aufruf zur Authentifikations-API machen, um meinen Zugangs-Token zu erhalten. Sie können hier unten sehen, dass ich die Methode HTTP POST benutze, um eine POST-Anfrage zum Endpunkt zu schicken.

PS> $token = Invoke-RestMethod  -Uri $authEndpointUrl -Method 'POST' -Body $authHttpBody
 PS> $token = $token.access_token

Nun habe ich einen Zugangs-Token und kann jede beliebige API aufrufen. Man muss nur daran denken, den Zugangs-Token in jedem API-Aufruf anzugeben, oder das System wird nicht erkennen, von wem der Aufruf kommt. Dieser Zugangs-Token muss als HTTP-Header angegeben werden. Das kann man auf einfache Weise machen, indem man eine Hashtabelle mit einem Headers-Parameter erstellt, den Invoke-RestMethod benötigt und dies zu jeder Refenzierung durch Splatting angeben.

PS> $authParam = @{
 >>>    Headers = @{ 'Authorization' = "Bearer $token" }
 >>> }

Da wir nun den Parameter erstellt haben, der zu Invoke-RestMethod gegeben werden soll, ziehe ich zur Demonstration alle Tasks in MOVEit Automation ein. Diese API hat einen spezifischen Endpunkt und HTTP-Methode (wie alle APIs), also gebe ich diese mit Invoke-RestMethod direkt an und verteile die Authorisierungs-Parameter via Splatting.

PS> $tasks = Invoke-RestMethod @authParam -Uri "https://$($apiConfig.MoveItHost)/webadmin/api/v1/tasks" -Method GET
 PS> $tasks
 paging                                                    sorting                                items
 ------                                                    -------                                -----
 @{page=1; perPage=2147483647; totalItems=3; totalPages=1} {@{sortField=Name; sortDirection=asc}} {@{Group=System.Object[]; I...

An diesem Punkt sind alle Tasks im Merkmal des Objekts gespeichert. Wenn Sie den Output in JSON sehen möchten, könnten Sie die Objekte mit dem Kommando ConvertTo-Json zu JSON konvertieren.

PS> $tasks | ConvertTo-Json
 {
     "paging":  {
                    "page":  1,
                    "perPage":  2147483647,
                    "totalItems":  3,
                    "totalPages":  1
                },
     "sorting":  [
                     {
                         "sortField":  "Name",
                         "sortDirection":  "asc"
                     }
                 ],
     "items":  [
                   {
                       "Group":  "",
                       "ID":  "222223",
                       "Name":  "Tamper Check",
                       "Info":  "@{Description=\n\t\t\t\t; Notes=\n\t\t\t\t}",
                       "Parameters":  "",
                       "Schedules":  "@{Schedule=System.Object[]}",
                       "steps":  "",
                       "Active":  1,
                       "CacheNames":  "random",
                       "NextEID":  15
                   }
     ]
 }

Das waren die Grundlagen, um mit MOVEit REST API zu arbeiten. Sie müssen immer einen Zugangs-Token erhalten und diesen Token für alle API-Calls angeben. Halten Sie Ausschau nach weiteren Blog Posts zum Thema MOVEit Automation!

Tipp: Lesen Sie dazu auch das Whitepaper Automatisieren mit PowerShell oder laden Sie sich kostenfrei eine Testversion von MOVEit Automation, Software für die Automatisierung der sicheren Dateiübertragung, herunter.