Hubs d'événements

Recevoir des événements clients depuis le serveur PowerShell Universal.

Les concentrateurs d'événements nécessitent une licence.

Les concentrateurs d'événements offrent la possibilité d'envoyer des commandes PowerShell aux agents PowerShell Universal connectés depuis le serveur PowerShell Universal. Les agents sont des services légers et multiplateformes qui peuvent s'exécuter sur des nœuds périphériques pour permettre à PowerShell Universal d'émettre des commandes à leur encontre.

Les concentrateurs d'événements fonctionnent soit en mode de communication un-à-un du serveur vers l'agent, soit en mode de diffusion un-à-plusieurs depuis un concentrateur d'événements du serveur vers tous les agents connectés. Les agents n'exécutent pas directement des tâches et nécessitent l'utilisation de Invoke-PSUCommand à partir d'autres scripts s'exécutant au sein du serveur PowerShell Universal. Vous pouvez considérer les concentrateurs d'événements comme un moyen d'effectuer la communication à distance PowerShell sans utiliser le transport de communication à distance standard.

À propos

PowerShell Universal exécute un serveur web avec un point de terminaison websocket qui écoutera les connexions des agents. C'est ce qu'on appelle le concentrateur d'événements. Vous pouvez configurer plusieurs concentrateurs d'événements par serveur PowerShell Universal avec des noms et des paramètres de sécurité différents. Une fois qu'un concentrateur d'événements est configuré sur le serveur, vous pouvez installer un agent sur n'importe quelle machine pouvant atteindre PowerShell Universal via les ports HTTP standard.

L'agent nécessite une configuration concernant l'emplacement et la manière de se connecter au serveur. Une fois cette opération effectuée, l'agent peut être démarré pour établir la connexion websocket au serveur. Une fois la connexion établie, le serveur est alors informé du client connecté. Il sera enregistré dans le hub et des événements pourront ensuite être envoyés du serveur aux agents.

Bien que vous ne puissiez pas planifier directement des tâches à exécuter sur les agents, vous pouvez exécuter des commandes contre les agents, dans des tâches, des API et des applications au sein du serveur.

Exemple de base

Par exemple, vous pouvez avoir un agent PowerShell Universal Linux s'exécutant dans votre centre de données aux États-Unis. Le serveur PowerShell Universal, s'exécutant dans votre centre de données en Europe, dispose d'un concentrateur d'événements configuré et nommé Linux. Sur le serveur, vous configureriez le hub en utilisant le fichier eventHubs.ps1 ou dans la console d'administration.

New-PSUEventHub -Name 'Linux'

Du côté de l'agent, vous configureriez ensuite un fichier agent.ps1 pour indiquer à l'agent où il doit se connecter au serveur.

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

Une fois le concentrateur d'événements créé et l'agent configuré, l'agent se connectera au serveur et pourra désormais accepter des commandes.

Dans le serveur, vous pouvez créer un script qui s'exécute contre l'agent. Bien que le script lui-même ne s'exécute pas sur l'agent, vous pouvez utiliser la cmdlet intégrée Invoke-PSUCommand pour ce faire. Dans votre script, vous pourriez recueillir des informations sur l'hôte. Étant donné que le paramètre -Computer est spécifié, cette commande sera exécutée directement contre l'agent et renverra le nom d'hôte au script s'exécutant sur le serveur.

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

De plus, vous pouvez effectuer des actions contre l'ensemble du hub d'agents connectés. Si vous souhaitiez, par exemple, redémarrer tous les agents connectés, vous pourriez diffuser la commande à l'ensemble du hub.

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

Création d'un concentrateur d'événements

Pour créer un concentrateur d'événements, cliquez sur APIs \ Event Hub, puis sur Create New Event Hub. Les concentrateurs d'événements sont nommés et peuvent être configurés pour appliquer l'authentification et l'autorisation.

Agent

Vous devrez installer et configurer l'agent PowerShell Universal pour utiliser les concentrateurs d'événements. L'agent est disponible sur plusieurs plateformes, sous forme de MSI installable sur Windows et d'image de conteneur Docker.

Si le journal de l'agent signale `Event Hub not found`, vérifiez d'abord que la valeur `Hub` dans `agent.json` correspond exactement à un concentrateur d'événements configuré sur l'instance PowerShell Universal cible. Dans les configurations courantes, cela signifie que l'agent a atteint le serveur mais que le hub nommé n'y existe pas encore ou que les noms ne correspondent pas.

Envoi d'événements

Depuis le serveur PowerShell Universal, vous pouvez envoyer des événements depuis un hub vers des clients connectés en utilisant la cmdlet Send-PSUEvent (Invoke-PSUCommand est un alias de Send-PSUEvent).

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

Le paramètre -Data accepte un objet qui sera sérialisé en CLIXML et envoyé au client. Les données seront désérialisées avant d'être transmises au bloc de script.

Vous pouvez également exécuter des commandes. Cela ne nécessite pas de définir un script sur le client du concentrateur d'événements. Vous pouvez également utiliser l'alias Invoke-PSUCommand pour imiter le comportement natif de PowerShell.

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

Inspecter les connexions actuelles

Utilisez Get-PSUEventHubConnection -Active pour voir les agents actuellement connectés.

Get-PSUEventHubConnection -Hub 'eventHub' -Active

La commande sans filtre peut également inclure d'anciennes connexions déconnectées ; par conséquent, -Active constitue la vue de dépannage la plus rapide lorsque vous souhaitez confirmer si un agent est actuellement en ligne. Si vous devez cibler un client spécifique, utilisez le ConnectionId retourné avec Send-PSUEvent.

Recevoir des données des clients

Cette fonctionnalité n'est disponible que lors de l'envoi de données à un client individuel, et non à l'ensemble des clients connectés à un hub.

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

Exemple : exécution de scripts sur des machines distantes

Cet exemple fournit un moyen d'exécuter des scripts sur des machines distantes sans avoir à installer une autre instance de PowerShell Universal.

Cet exemple permet d'envoyer des scripts vers des machines distantes et de les exécuter à l'aide d'un script de concentrateur d'événements générique.

Commencez par créer un concentrateur d'événements dans PowerShell Universal. Cet exemple n'utilise pas d'authentification.

Ensuite, installez l'agent PowerShell Universal sur la machine distante. Créez un fichier de configuration dans %ProgramData%\PowerShellUniversal\agent.json.

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

Ensuite, créez un script d'aide script.ps1 pour recevoir les données du concentrateur d'événements et traiter les demandes de PSU afin d'invoquer des scripts. Il crée un nouveau fichier PS1 temporaire et utilise le $EventData transmis par le message du concentrateur d'événements avec le contenu et les paramètres du script.

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

Dans PowerShell Universal, ajoutez un script que vous souhaitez exécuter sur la machine distante. Dans cet exemple, il démarre simplement un processus.

param($Name)

Start-Process $Name

Enfin, ajoutez un autre script qui envoie l'événement au client. Cela pourrait également provenir d'une API ou d'une application. Étant donné que le script sur l'agent est générique, il exécutera simplement tout ce qui lui est transmis.

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

À partir de là, vous pourriez même utiliser le script pour planifier des tâches à exécuter sur les machines distantes à l'aide de l'agent.