Event Hubs

Event Hubs erfordern eine Lizenz.

Event Hubs bieten die Möglichkeit, PowerShell-Befehle vom PowerShell Universal-Server an verbundene PowerShell Universal Agents zu senden. Agents sind leichtgewichtige, plattformübergreifende Dienste, die auf Edge-Knoten ausgeführt werden können, damit PowerShell Universal Befehle an sie ausgeben kann.

Event Hubs arbeiten entweder über eine Eins-zu-eins-Kommunikationsmethode vom Server zum Agent oder über eine Fan-out-Eins-zu-viele-Kommunikationsmethode von einem Event Hub am Server zu allen verbundenen Agents. Agents führen Aufträge nicht direkt aus und erfordern die Verwendung von Invoke-PSUCommand aus anderen Skripten, die innerhalb des PowerShell Universal-Servers ausgeführt werden. Sie können sich Event Hubs als eine Möglichkeit vorstellen, PowerShell Remoting ohne Verwendung des standardmäßigen Remoting-Transports durchzuführen.

Über

PowerShell Universal betreibt einen Webserver mit einem Websocket-Endpunkt, der darauf wartet, dass sich Agents verbinden. Dies wird als Event Hub bezeichnet. Sie können mehrere Event Hubs pro PowerShell Universal-Server mit unterschiedlichen Namen und Sicherheitseinstellungen konfigurieren. Sobald ein Event Hub am Server konfiguriert ist, können Sie einen Agent auf jedem Computer installieren, der PowerShell Universal über die Standard-HTTP-Ports erreichen kann.

Der Agent benötigt einige Konfigurationen dazu, wo und wie er sich mit dem Server verbinden soll. Sobald dies erledigt ist, kann der Agent gestartet werden, um die Websocket-Verbindung zum Server herzustellen. Nachdem die Verbindung aufgebaut ist, ist der Server über den verbundenen Client informiert. Er wird innerhalb des Hubs registriert und Events können dann vom Server an die Agents gesendet werden.

Sie können Aufträge nicht so planen, dass sie direkt auf Agents ausgeführt werden, aber Sie können Befehle gegen Agents innerhalb von Aufträgen, APIs und Apps im Server ausführen.

Einfaches Beispiel

Als Beispiel könnte ein Linux-PowerShell Universal-Agent in Ihrem US-Rechenzentrum laufen. Der PowerShell Universal-Server, der in Ihrem EU-Rechenzentrum läuft, hat einen konfigurierten Event Hub mit dem Namen Linux. Auf dem Server würden Sie den Hub über die Datei eventHubs.ps1 oder in der Admin-Konsole konfigurieren.

New-PSUEventHub -Name 'Linux'

Auf der Agent-Seite würden Sie dann eine agent.ps1-Datei konfigurieren, um dem Agent mitzuteilen, wo er sich mit dem Server verbinden soll.

{
    "Connections": [
        {
            "Url": "http://eu.mycompany.local",
            "Hub": "Linux"
        }
    ]
}

Nachdem der Event Hub erstellt und der Agent konfiguriert ist, verbindet sich der Agent mit dem Server und kann nun Befehle annehmen.

Innerhalb des Servers können Sie ein Skript erstellen, das gegen den Agent ausgeführt wird. Obwohl das Skript selbst nicht auf dem Agent ausgeführt wird, können Sie dazu das integrierte Cmdlet Invoke-PSUCommand verwenden. In Ihrem Skript könnten Sie Host-Informationen sammeln. Da der Parameter -Computer angegeben ist, wird dieser Befehl direkt gegen den Agent ausgeführt und gibt den Hostnamen an das im Server ausgeführte Skript zurück.

Invoke-PSUCommand -Command "hostname" -Computer "linuxhost-12" 

Zusätzlich können Sie Aktionen gegen den gesamten Hub verbundener Agents durchführen. Wenn Sie zum Beispiel alle verbundenen Agents neu starten möchten, könnten Sie dies über den gesamten Hub hinweg tun.

Invoke-PSUCommand -Command "reboot" -Hub "Linux"

Einen Event Hub erstellen

Um einen Event Hub zu erstellen, klicken Sie auf APIs \ Event Hub und dann auf Create New Event Hub. Event Hubs werden benannt und können Authentifizierung und Autorisierung erzwingen.

Agent

Sie müssen den PowerShell Universal Agent installieren und konfigurieren, um Event Hubs zu verwenden. Der Agent wird für mehrere Plattformen bereitgestellt, als installierbare MSI unter Windows und als Docker-Container-Image.

Wenn das Agent-Protokoll `Event Hub not found` meldet, überprüfen Sie zunächst, ob der Wert `Hub` in `agent.json` genau mit einem auf der Ziel-PowerShell Universal-Instanz konfigurierten Event Hub übereinstimmt. In üblichen Konfigurationen bedeutet dies, dass der Agent den Server erreicht hat, der benannte Hub dort aber noch nicht existiert oder die Namen nicht übereinstimmen.

Events senden

Innerhalb des PowerShell Universal-Servers können Sie mit dem Cmdlet Send-PSUEvent Events von einem Hub an verbundene Clients senden (Invoke-PSUCommand ist ein Alias für Send-PSUEvent).

Send-PSUEvent -Hub 'MyHub' -Data "Hello!"

Der Parameter -Data akzeptiert ein Objekt, das mit CLIXML serialisiert und an den Client gesendet wird. Die Daten werden deserialisiert, bevor sie an den Skriptblock übergeben werden.

Sie können auch Befehle ausführen. Dies erfordert nicht die Definition eines Skripts auf dem Event Hub-Client. Sie können auch den Alias Invoke-PSUCommand verwenden, um das native PowerShell-Verhalten nachzuahmen.

Invoke-PSUCommand -Hub "MyHub" -Command "Start-Process" -Parameters @{
    FilePath = "Notepad"
}

Aktuelle Verbindungen prüfen

Verwenden Sie Get-PSUEventHubConnection -Active, um die derzeit verbundenen Agents anzuzeigen.

Get-PSUEventHubConnection -Hub 'eventHub' -Active

Der ungefilterte Befehl kann auch ältere, getrennte Verbindungen enthalten, daher ist -Active die schnellste Ansicht zur Fehlerbehebung, wenn Sie überprüfen möchten, ob ein Agent gerade online ist. Wenn Sie einen bestimmten Client ansprechen müssen, verwenden Sie die zurückgegebene ConnectionId mit Send-PSUEvent.

Daten von Clients empfangen

Diese Funktion ist nur verfügbar, wenn Daten an einen einzelnen Client gesendet werden, und nicht an alle mit einem Hub verbundenen Clients.

$Connection = Get-PSUEventHubConnection | Where-Object UserName -eq 'Admin'
$Result = Send-PSUEvent -Hub 'Hub' -Data 'Say Hello!' -Connectionid $Connection.ConnectionId
Show-UDToast $Result

Beispiel: Skripte auf Remote-Computern ausführen

Dieses Beispiel bietet eine Möglichkeit, Skripte auf Remote-Computern auszuführen, ohne eine weitere Instanz von PowerShell Universal installieren zu müssen.

Dieses Beispiel ermöglicht das Senden von Skripten an Remote-Computer und deren Ausführung mit einem generischen Event Hub-Skript.

Erstellen Sie zunächst einen Event Hub in PowerShell Universal. Dieses Beispiel verwendet keine Authentifizierung.

Installieren Sie anschließend den PowerShell Universal Agent auf dem Remote-Computer. Erstellen Sie eine Konfigurationsdatei unter %ProgramData%\PowerShellUniversal\agent.json.

{
    "Connections": [
        {
            "Url": "http://localhost:5000",
            "Hub": "eventHub",
            "ScriptPath": "script.ps1"
        }
    ]
}

Erstellen Sie als Nächstes ein Hilfsskript script.ps1, um die Event Hub-Daten zu empfangen und Anfragen von PSU zum Aufrufen von Skripten zu verarbeiten. Es erstellt eine neue temporäre PS1-Datei und verwendet die aus der Event Hub-Nachricht übergebenen $EventData mit dem Inhalt und den Parametern für das Skript.

$TempFile = (New-TemporaryFile).FullName + ".ps1"
$EventData.Contents | Out-File -FilePath $TempFile
$Parameters = $EventData.Parameters
& $TempFile @Parameters

Fügen Sie in PowerShell Universal ein Skript hinzu, das Sie auf dem Remote-Computer ausführen möchten. In diesem Beispiel startet es einfach einen Prozess.

param($Name)

Start-Process $Name

Fügen Sie schließlich ein weiteres Skript hinzu, das das Event an den Client sendet. Dies könnte auch von einer API oder einer App aus erfolgen. Da das Skript auf dem Agent generisch ist, führt es einfach alles aus, was an es übergeben wird.

param($TargetComputer, $ProcessName)
 
Send-PSUEvent -Computer $TargetComputer -Data @{
    Contents = Get-Content StartAProcess.ps1 -Raw
    Parameters = @{
        Name = $ProcessName
    }
}

Von hier aus könnten Sie das Skript sogar verwenden, um Aufträge zu planen, die mithilfe des Agents auf den Remote-Computern ausgeführt werden.