> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/it/api/event-hubs.md). # Event Hubs {% hint style="info" %} Gli Event Hubs richiedono una [licenza](/powershell-universal/it/licensing.md). {% endhint %} Gli Event Hubs offrono la possibilità di inviare comandi PowerShell agli [agent PowerShell Universal](/powershell-universal/it/config/agent.md) connessi dal server PowerShell Universal. Gli agent sono servizi leggeri e multipiattaforma che possono essere eseguiti sui nodi edge per consentire a PowerShell Universal di impartire comandi verso di essi. Gli Event Hubs funzionano con un metodo di comunicazione uno-a-uno dal server all'agent oppure con un metodo di comunicazione fan out uno-a-molti da un event hub sul server verso tutti gli agent connessi. Gli agent non eseguono direttamente i job e richiedono l'uso di `Invoke-PSUCommand` da altri script in esecuzione all'interno del server PowerShell Universal. Può considerare gli event hub come un modo per effettuare PowerShell Remoting senza usare il trasporto di remoting standard. ## Informazioni PowerShell Universal esegue un server web con un endpoint websocket che rimane in ascolto in attesa che gli agent si connettano. Questo viene definito event hub. È possibile configurare più event hub per ogni server PowerShell Universal con nomi e impostazioni di sicurezza differenti. Una volta configurato un event hub sul server, è possibile installare un agent su qualsiasi macchina in grado di raggiungere PowerShell Universal tramite le porte HTTP standard. L'agent richiede alcune configurazioni relative a dove e come connettersi al server. Una volta fatto questo, l'agent può essere avviato per stabilire la connessione websocket con il server. Dopo che la connessione è stata stabilita, il server è a conoscenza del client connesso. Verrà registrato all'interno dell'hub e gli eventi potranno quindi essere inviati dal server agli agent. Sebbene non sia possibile pianificare l'esecuzione di job direttamente sugli agent, è possibile eseguire comandi verso gli agent, all'interno di job, API e app nel server. ## Esempio di base Ad esempio, potrebbe avere un agent PowerShell Universal Linux in esecuzione nel suo datacenter statunitense. Il server PowerShell Universal, in esecuzione nel suo datacenter europeo, ha un event hub configurato denominato Linux. Sul server, configurerebbe l'hub utilizzando il file `eventHubs.ps1` oppure tramite la console di amministrazione. ```powershell New-PSUEventHub -Name 'Linux' ``` Sul lato agent, configurerebbe quindi un file `agent.ps1` per indicare all'agent dove deve connettersi al server. ```json { "Connections": [ { "Url": "http://eu.mycompany.local", "Hub": "Linux" } ] } ``` Con l'event hub creato e l'agent configurato, l'agent si connetterà al server e potrà ora accettare comandi. All'interno del server, può creare uno script che viene eseguito verso l'agent. Sebbene lo script stesso non venga eseguito sull'agent, può utilizzare il cmdlet integrato `Invoke-PSUCommand` per farlo. All'interno del suo script, potrebbe raccogliere informazioni sull'host. Poiché è specificato il parametro `-Computer`, questo comando verrà eseguito direttamente sull'agent e restituirà il nome host allo script in esecuzione nel server. ```powershell Invoke-PSUCommand -Command "hostname" -Computer "linuxhost-12" ``` Inoltre, può intraprendere azioni verso l'intero hub di agent connessi. Se, ad esempio, volesse riavviare tutti gli agent connessi, potrebbe estendere l'operazione a tutto l'hub. ```powershell Invoke-PSUCommand -Command "reboot" -Hub "Linux" ``` ## Creazione di un event hub Per creare un event hub, faccia clic su API \ Event Hub e faccia clic su Create New Event Hub. Gli Event Hubs hanno un nome e possono scegliere di applicare autenticazione e autorizzazione. ## Agent Sarà necessario installare e configurare l'[agent PowerShell Universal](/powershell-universal/it/config/agent.md) per utilizzare gli Event Hubs. L'agent è disponibile su più piattaforme, come MSI installabile su Windows e come immagine di container Docker. {% hint style="warning" %} Se il log dell'agent riporta \`Event Hub not found\`, verifichi innanzitutto che il valore \`Hub\` in \`agent.json\` corrisponda esattamente a un Event Hub configurato sull'istanza PowerShell Universal di destinazione. Nelle configurazioni più comuni, ciò significa che l'agent ha raggiunto il server ma l'hub con quel nome non esiste ancora oppure i nomi non corrispondono. {% endhint %} ## Invio di eventi All'interno del server PowerShell Universal, può inviare eventi da un hub ai client connessi utilizzando il cmdlet `Send-PSUEvent` (`Invoke-PSUCommand` è un alias di `Send-PSUEvent`). ```powershell Send-PSUEvent -Hub 'MyHub' -Data "Hello!" ``` Il parametro `-Data` accetta un oggetto che verrà serializzato utilizzando CLIXML e inviato al client. I dati verranno deserializzati prima di essere passati allo script block. Può anche eseguire comandi. Ciò non richiede la definizione di uno script sul client dell'event hub. Può inoltre utilizzare l'alias `Invoke-PSUCommand` per riprodurre il comportamento nativo di PowerShell. ```powershell Invoke-PSUCommand -Hub "MyHub" -Command "Start-Process" -Parameters @{ FilePath = "Notepad" } ``` ### Ispezione delle connessioni correnti Utilizzi `Get-PSUEventHubConnection -Active` per visualizzare gli agent attualmente connessi. ```powershell Get-PSUEventHubConnection -Hub 'eventHub' -Active ``` Il comando senza filtri può includere anche connessioni disconnesse meno recenti, quindi `-Active` è la vista di risoluzione dei problemi più rapida quando desidera verificare se un agent è attualmente online. Se deve indirizzare un client specifico, utilizzi il `ConnectionId` restituito con `Send-PSUEvent`. ## Ricezione di dati dai client Questa funzionalità è disponibile solo quando si inviano dati a un singolo client, anziché a tutti i client connessi a un hub. ```powershell $Connection = Get-PSUEventHubConnection | Where-Object UserName -eq 'Admin' $Result = Send-PSUEvent -Hub 'Hub' -Data 'Say Hello!' -Connectionid $Connection.ConnectionId Show-UDToast $Result ``` ## Esempio: esecuzione di script su macchine remote {% hint style="info" %} Questo esempio offre un modo per eseguire script su macchine remote senza dover installare un'altra istanza di PowerShell Universal. {% endhint %} Questo esempio consente di inviare script a macchine remote ed eseguirli con uno script generico dell'event hub. Innanzitutto, crei un event hub in PowerShell Universal. Questo esempio non utilizza l'autenticazione. Successivamente, installi l'agent PowerShell Universal sulla macchina remota. Crei un file di configurazione in `%ProgramData%\PowerShellUniversal\agent.json`. ```json { "Connections": [ { "Url": "http://localhost:5000", "Hub": "eventHub", "ScriptPath": "script.ps1" } ] } ``` Successivamente, crei uno script di supporto script.ps1 per ricevere i dati dell'event hub ed elaborare le richieste da PSU per invocare gli script. Crea un nuovo file PS1 temporaneo e utilizza `$EventData` passato dal messaggio dell'event hub con il contenuto e i parametri per lo script. ```powershell $TempFile = (New-TemporaryFile).FullName + ".ps1" $EventData.Contents | Out-File -FilePath $TempFile $Parameters = $EventData.Parameters & $TempFile @Parameters ``` In PowerShell Universal, aggiunga uno script che desidera eseguire sulla macchina remota. In questo esempio, avvia semplicemente un processo. ```powershell param($Name) Start-Process $Name ``` Infine, aggiunga un altro script che invii l'evento al client. Questo potrebbe provenire anche da un'API o da un'app. Poiché lo script sull'agent è generico, eseguirà semplicemente qualsiasi cosa gli venga passata. ```powershell param($TargetComputer, $ProcessName) Send-PSUEvent -Computer $TargetComputer -Data @{ Contents = Get-Content StartAProcess.ps1 -Raw Parameters = @{ Name = $ProcessName } } ``` Da qui potrebbe persino utilizzare lo script per pianificare l'esecuzione di job sulle macchine remote tramite l'agent. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/powershell-universal/it/api/event-hubs.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.