Microsoft PowerShell Connector

Die Funktionen des Microsoft PowerShell Connectors basieren auf dem generischen Python Script Connector . Die Funktionalität wird durch das Python-Skript powershell-event.py implementiert , das ab Version 2026.1 von Matrix42 bereitgestellt wird. Dieses Skript ruft PowerShell-Skripte von Kunden über eine SSH-Verbindung von einem entfernten Windows-Server auf.

Bei der Verwendung des Microsoft PowerShell Connectors ist Folgendes erforderlich:

• Der Kunde besitzt einen eigenen Windows-Server, auf dem diese PowerShell-Skripte aufgerufen werden.
• Auf diesem Windows-Server muss ein SSH-Server installiert und für die Unterstützung der privaten/öffentlichen Schlüsselauthentifizierung konfiguriert sein (andere Authentifizierungsmethoden werden nicht unterstützt).
• Der Kunde hat einen Windows-Benutzer mit den erforderlichen Berechtigungen zum Ausführen von MS PowerShell-Skripten und zum Anmelden am Server über SSH erstellt.
• Die Konnektordetails sind erfüllt und die ereignisbasierte Aufgabe ist für die Auslösung von PowerShell konfiguriert.
• Der Workflow muss einen Orchestrierungsknoten enthalten, um die ereignisbasierte Aufgabe aufzurufen und auszulösen.
• Matrix42 erstellt ein privates/öffentliches Schlüsselpaar und sendet den öffentlichen Schlüssel an den Kunden. Dieser öffentliche Schlüssel muss auf dem SSH-Server konfiguriert werden. Matrix42 konfiguriert außerdem den privaten Schlüssel in der Connector-Konfiguration.

Funktionen, die nicht unterstützt werden

• PowerShell kann nicht über geplante Aufgaben mithilfe dieses Python-Skripts powershell-event.py ausgelöst werden.

Konnektor konfigurieren

Für den Zugriff auf die Konnektorverwaltung benötigt der Benutzer Berechtigungen zur Plattformkonfiguration.

1. Öffnen Sie den Administrationsbereich (Zahnradsymbol).
2. Ansicht „Anschlüsse öffnen“ öffnen.
3. Wählen Sie „+ neuer Anschluss“.

4. Wählen Sie als Datenquellentyp Generic Python Script aus.

5. Informationen vervollständigen

• Geben Sie einen eindeutigen Namen für den Konnektor ein.
• Wählen Sie powershell-event.py aus. Skript aus dem Bereitstellungsskriptfeld.
• Das Parameterverschlüsselungspasswort wird benötigt, um Parameter nach dem Speichern des Konnektors auszublenden/einzublenden (denken Sie daran, das Passwort an einem sicheren Ort aufzubewahren).
  
  Beispielhafter Linux-Befehl zum Generieren eines privaten/öffentlichen Schlüsselpaares:
  ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_windows_automation
  Lassen Sie das Passwort leer.
  
  Die Parameter müssen genau dieses Format haben:
  { "ssh": {"private_key": "-----BEGIN OPENSSH PRIVATE KEY-----\nb4ClbnNzaC1rZXktdjEAbbAABG5vbmUAAAAxxxxxxQAAAAAAAAABAAAAMwAAAAtzc2gtZW\nQyNTUxOQAAACB2zQv/80M8ICgv95iT7jCIxnn/YL1tzLvm6S+QaC3bDAAAALBayLNTWsiz\nUwAAAAtzc2gtZWQyNTUxOQAAACB2zQv/80M8ICgv95iT7jCIxnn/YL1tzLvm6S+QaC3bDA\nAAAEAeY5TsWlBuSeX+3Sz/tJTqJU+XgpHHr7QjfRlbr/f7RHbNC//zRXsgKC/3mJPuMIjG\nef9gvW3Mu+bpL5BoLdsMAAABKXJpa3BuaWVtaW5lbkBSaWt1cy1NYWNCb29rLVByby0yMD\nI0LmxvY2FsAQIDAB==\n-----END OPENSSH PRIVATE KEY-----", "user": "MATRIX42\\sshrunneruser", "host": "1.2.3.4", "timeout": 30,    "remote_command": { "executable": "powershell.exe", "arguments": ["-No Pro file" ]  } }, "redirect_stderr_to_stdout": true}
  
  Zeilenumbrüche im Wert private_key müssen wie im obigen Beispiel durch \n ersetzt werden. Dieser private Schlüssel dient user am Windows-Server über SSH.
  user ist der Benutzer, der zum Anmelden am Windows-Server und zum Ausführen von PowerShell-Skripten verwendet wird.
  host ist die IP-Adresse oder der Hostname des Windows-Servers, der diese PowerShell-Skripte enthält.
  timeout kann wie im obigen Beispiel auf den Standardwert 30 belassen werden.
  remote_command sollte genau wie im obigen Beispiel aussehen.

• WebAPI Benutzer wird benötigt, wenn der Connector Daten in die Kundenlösung schreibt.
• WebAPI Passwort wird benötigt, wenn der Connector Daten in die Kundenlösung schreibt.

6. Speichern Sie den Konnektor über die Schaltfläche „Speichern“. Der Konnektor ist nun konfiguriert und Sie können mit der Konfiguration der ereignisbasierten Aufgabe fortfahren.

Ereignisbasierte Aufgabe konfigurieren

Neue ereignisbasierte Aufgabe erstellen

1. Legen Sie einen beschreibenden Aufgabennamen fest
2. Aufgabenverwendung auswählen: Ereignis
3. Zuordnungstyp festlegen: Generische Vorlage
4. Zielvorlage festlegen: von der Daten an diese Ereignisaufgabe gesendet werden
5. Zielordner festlegen: aus dem Daten an diese Ereignisaufgabe gesendet werden

6. Zuordnungen erstellen

Sie benötigen immer mindestens eine Zuordnung: ps_script_path_and_name, die einem Attribut zugeordnet werden muss, das diese Informationen enthält. Andernfalls weiß die Ereignisaufgabe nicht, welches PowerShell-Skript ausgelöst werden soll.

Zusätzlich können Sie einen oder mehrere Parameter angeben. Diese müssen Sie in einer Zuordnungstabelle mit genau den gleichen Namen wie im Beispiel festlegen: Parameter1, Parameter2, Parameter3 usw., je nachdem, wie viele Parameter Ihr PowerShell-Skript erwartet.

7. Ereignisaufgabe speichern.
8. Als Nächstes müssen Sie einen Workflow mit einem Orchestrierungsknoten erstellen, der diese Ereignisaufgabe aufruft.

Ereignisaufgabe aus dem Workflow aufrufen

Fügen Sie Ihrem Workflow einen Orchestrierungsknoten hinzu.

1. Name - beschreibender Name
2. Beschreibung
3. Orchestrate – Native Konnektoren
4. Datenquelle – Generisches Python Script
5. Aktivität – Aufgabe „Ereignis ausführen“
6. Ziel – Wählen Sie die Ereignisaufgabe aus, die Sie zuvor für diesen Zweck erstellt haben.
7. Antwort – Wählen Sie das Attribut aus, das zum Speichern der erfolgreich ausgeführten PowerShell-Ausgabe verwendet wird.
8. Pro : Wählen Sie das Attribut aus, das zum Speichern von Fehlermeldungen fehlgeschlagener PowerShell-Aufrufe verwendet wird.

Vom Microsoft PowerShell-Connector unterstütztes PowerShell-Skriptformat

• Liest Skriptparameter als Zeichenkettenparameter (wie im Beispiel).
• Kann 0 bis n Parameter enthalten.
• Das Skript wird mit dem Exit-Code 0 beendet, wenn es erfolgreich ausgeführt wurde. Alternativ kann eine Erfolgsmeldung im JSON-Format zurückgegeben und im Antwortfeld des Knotens der Datenkarte gespeichert werden.
• Bei einem Fehler wird das Programm mit einem Exit-Code größer als 0 beendet. Die Fehlermeldung kann auch als JSON-Datei zurückgegeben und im Feld „Bereitstellungsausnahme“ der Datenkarte gespeichert werden.

Das Beispiel prüft, ob zwei Parameter angegeben wurden, und schreibt diese anschließend in eine Datei auf dem Windows-Rechner. Wenn der erste Parameter „failuretest“ lautet, gibt es einen Fehlercode und eine Fehlermeldung an den Workflow zurück.

param (
    [string]$Param1,
    [string]$Param2
)

# Validate required parameters
if ([string]::IsNullOrEmpty($Param1) -or [string]::IsNullOrEmpty($Param2)) {
    $errorJson = @{ error = "Wrong number of attributes for Powershell script" } | ConvertTo-Json -Compress
    Write-Output $errorJson
    exit 1
}

# Folder where this script is located
$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition
$file = Join-Path $scriptDir "pstest.txt"

# Failure case
if ($Param1 -eq "failuretest") {
    $errorJson = @{ error = "Calling powershell FAILED" } | ConvertTo-Json -Compress
    Write-Output $errorJson
    exit 1
}

# Success case: write file
"$Param1`n$Param2" | Out-File -FilePath $file -Encoding UTF8 -Force

$successJson = @{ response = "Calling powershell successfull" } | ConvertTo-Json -Compress
Write-Output $successJson
exit 0