> 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/endpoints.md). # Endpoint Configuri gli endpoint API di PowerShell Universal con New-PSUEndpoint, con informazioni su routing degli URL, header, cookie, corpi delle richieste, caricamenti di file e risposte personalizzate. Gli endpoint sono definiti dal loro URI e dal metodo HTTP. Le chiamate effettuate al server Universal che corrispondono all'endpoint API e al metodo definiti eseguono lo script dell'endpoint API. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/endpoint' -Method 'GET' -Endpoint { "Hello, world!" } ``` {% endcode %} Per richiamare il metodo precedente, può usare `Invoke-RestMethod`. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/endpoint ``` {% endcode %} Quando definisce gli endpoint nell'API di gestione, può omettere la chiamata a `New-PSUEndpoint`, poiché la console di amministrazione la definisce. Il solo contenuto che deve fornire nell'editor è lo script che desidera chiamare. {% hint style="warning" %} Eviti di usare URL degli endpoint che corrispondono agli URL interni dell'API di gestione di PowerShell Universal, poiché questo causa comportamenti inattesi. Può consultare la [documentazione OpenAPI](/powershell-universal/it/api/openapi.md#management-api-documentation) dell'[API di gestione](/powershell-universal/it/config/management-api.md) per verificare che nessuno degli URL corrisponda. {% endhint %} ## Metodi HTTP Gli endpoint possono avere uno o più metodi HTTP definiti. Per determinare quale metodo viene usato da un endpoint, usi la variabile integrata `$Method`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method @('GET', 'POST') -Endpoint { if ($Method -eq 'GET') { Get-User } else { New-User } } ``` {% endcode %} ## URL variabile Gli URL possono contenere segmenti variabili. Può indicare un segmento variabile usando i due punti (`:`). Per esempio, il seguente URL fornirebbe una variabile per l'ID dell'utente. La variabile `$Id` sarà definita all'interno dell'endpoint quando viene eseguito. Le variabili devono essere univoche nello stesso URL dell'endpoint. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user/:id' -Method 'GET' -Endpoint { Get-User -Id $Id } ``` {% endcode %} Per chiamare questa API e specificare l'ID, proceda come segue: {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user/123 ``` {% endcode %} ## Parametri della query string I parametri della query string vengono passati automaticamente negli endpoint come variabili a cui può poi accedere. Per esempio, se ha un endpoint che si aspetta una variabile `$Id`, può fornirla nella query string. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method 'GET' -Endpoint { Get-User -Id $Id } ``` {% endcode %} La chiamata `Invoke-RestMethod` risultante deve quindi includere il parametro della query string. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user?Id=123 ``` {% endcode %} Quando usa più parametri della query string, si assicuri che l'URL sia racchiuso tra virgolette in modo che PowerShell lo interpreti correttamente. L'inclusione di una e commerciale (&) senza virgolette causerà problemi sia in Windows PowerShell sia in PowerShell 7. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod "http://localhost:5000/user?Id=123&name=tim" ``` {% endcode %} ### Considerazioni sulla sicurezza Quando accetta input tramite parametri della query string, potrebbe essere vulnerabile a [CWE-914: Improper Control of Dynamically-Identified Variables](https://cwe.mitre.org/data/definitions/914.html). Consideri l'uso di un blocco `param` per garantire che all'endpoint vengano forniti solo parametri validi. Di seguito è riportato un esempio di CWE-914. Includa un parametro della query string `$IsChallengePassed` per aggirare il challenge. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url "/api/v1.0/CWE914Test" -Description "Vulnerable to CWE-914" -Endpoint { if($ChallengeInputData -eq "AcceptableInput") { $IsChallengePassed = $true } if($IsChallengePassed) { "Challenge passed. Here is Sensitive Information" } else { "Challenge not passed" } } ``` {% endcode %} Per evitare questo particolare problema, può usare un blocco `param`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url "/api/v1.0/CWE914Test" -Description "Not Vulnerable to CWE-914" -Endpoint { Param( $ChallengeInputData ) if($ChallengeInputData -eq "AcceptableInput") { $IsChallengePassed = $true } if($IsChallengePassed) { "Challenge passed. Here is Sensitive Information" } else { "Challenge not passed" } } ``` {% endcode %} ## Header Gli header delle richieste sono disponibili nelle API tramite la variabile `$Headers`. La variabile è una hashtable. Per accedere a un header, usi la sintassi seguente: {% code collapsedlinecount="10" %} ```powershell $Headers['Content-Type'] ``` {% endcode %} ## Cookie I cookie delle richieste sono disponibili nelle API tramite la variabile `$Cookies`. La variabile è una hashtable. Per accedere a un cookie, usi la sintassi seguente: {% code collapsedlinecount="10" %} ```powershell $Cookies['Request-Cookie'] ``` {% endcode %} Rimandi i cookie della richiesta con il cmdlet `New-PSUApiResponse`. Usi il parametro `-Cookies` con una hashtable fornita. {% code collapsedlinecount="10" %} ```powershell New-PSUApiResponse -StatusCode 200 -Cookies @{ ResponseCookie = '123' } ``` {% endcode %} ## Body Per accedere al corpo di una richiesta, accederà semplicemente alla variabile `$Body`. La variabile `$Body` di Universal sarà una stringa. Se si aspetta JSON, dovrebbe usare `ConvertFrom-Json`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method Post -Endpoint { $User = ConvertFrom-Json $Body New-User $User } ``` {% endcode %} Per chiamare l'endpoint precedente, specifichi il body di `Invoke-RestMethod`. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body "{'username': 'adam'}" ``` {% endcode %} ## Log live Può visualizzare le informazioni del log live per qualsiasi endpoint facendo clic sulla scheda del log. I log live includono URL, metodo HTTP, indirizzo IP di origine, stream di PowerShell, codice di stato, Content Type restituito e lunghezza del contenuto HTTP. Può scrivere nel log live dall'interno dei suoi endpoint con cmdlet come `Write-Host`. ## Test Può usare la scheda Test nell'editor degli endpoint per testare le sue API. Usando questo strumento di test, può modificare gli header, la query string e il body. Può anche modificare l'autenticazione e l'autorizzazione per il test. Quando usa la scheda Test, qualsiasi modifica ai valori del test comporterà un blocco di codice aggiornato che potrà poi usare in PowerShell. Faccia clic sulla scheda Code per visualizzare il codice del test. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod -Uri 'http://localhost:5000/test-api?Page=1' -Headers @{'X-Custom-Header' = 'Value';} -Method 'POST' ``` {% endcode %} Inoltre, i test eseguiti nel tester verranno conservati per 30 giorni per consentire di ripetere il test senza dover riconfigurare tutte le proprietà. Facendo clic sul pulsante Apply, lo strumento di test verrà configurato con le stesse proprietà. ## Dati del form Può passare dati a un endpoint come dati del form. I dati del form verranno passati nel suo endpoint come parametri. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method Post -Endpoint { param([Parameter(Mandatory)]$userName, $FirstName, $LastName) New-User $UserName -FirstName $FirstName -LastName $LastName } ``` {% endcode %} Può quindi usare una hashtable con Invoke-RestMethod per passare i dati del form. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body @{ UserName = "adriscoll" FirstName = "Adam" LastName = "Driscoll" } ``` {% endcode %} ## Dati JSON Può passare dati JSON a un endpoint e questi si associeranno automaticamente a un blocco param. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method Post -Endpoint { param([Parameter(Mandatory)]$userName, $FirstName, $LastName) New-User $UserName -FirstName $FirstName -LastName $LastName } ``` {% endcode %} Può quindi inviare dati JSON all'endpoint. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body (@{ UserName = "adriscoll" FirstName = "Adam" LastName = "Driscoll" } | ConvertTo-Json) -ContentType 'application/json' ``` {% endcode %} ## Blocco param Può usare un blocco `param` all'interno del suo script per imporre parametri obbligatori e fornire valori predefiniti per parametri opzionali come i parametri della query string. Variabili come `$Body`, `$Headers` e `$User` vengono fornite automaticamente. Nell'esempio seguente, il parametro `$Name` è obbligatorio e il parametro `$Role` ha un valore predefinito pari a Default. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user/:name' -Endpoint { param([Parameter(Mandatory)$Name, $Role = "Default") } ``` {% endcode %} Quando usa il blocco `param` con parametri di route come nell'esempio precedente, deve includere la variabile di route nel suo parametro. Se non viene specificata, non avrà accesso a quel valore. Per esempio, la seguente variabile `$Name` è sempre `$null`. L'endpoint restituisce sempre false. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user/:name' -Endpoint { param($Role = "Default") $Name -eq 'Adam' } ``` {% endcode %} Se usa l'attributo `CmdletBinding` o `Parameter` all'interno del blocco param, l'endpoint imporrà in modo rigoroso quali parametri sono consentiti nell'endpoint. Per esempio, il seguente impone che il parametro name sia specificato. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Endpoint { param([Parameter(Mandatory)$Name) } ``` {% endcode %} Detto questo, non può specificare parametri aggiuntivi all'endpoint. Procedere come segue causerà un errore. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body (@{ Name = "adriscoll" DisplayName = 'Adam' } | ConvertTo-Json) -ContentType 'application/json' ``` {% endcode %} Se modifica il suo endpoint per evitare di usare l'attributo `Parameter`, può passare un numero qualsiasi di parametri e questi verranno associati come variabili e non come parametri dell'endpoint. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Endpoint { param($Name) } ``` {% endcode %} ### Set di parametri dei metodi Può definire set di parametri usando i parametri dei metodi. Per impostazione predefinita, PowerShell Universal ispezionerà il blocco param per determinare se sono specificati i nomi dei metodi HTTP `Get`, `Put`, `Post`, `Delete` o altri e li includerà automaticamente. Quando gli endpoint accettano più metodi, potrebbe non essere in grado di determinare quale set di parametri chiamare in base ai dati forniti. Nell'esempio seguente, sia il Get sia il Post accettano il parametro name. Inoltre non c'è modo di chiamare il Post senza un nome, quindi la convalida potrebbe non riuscire. Per ovviare a questo, includa i parametri `Post` e `Get` che fanno parte del rispettivo set di parametri. PowerShell Universal includerà questo parametro per garantire che venga chiamato il set di parametri corretto. {% code overflow="wrap" collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method @("Get", "Post") -Endpoint { param( [Parameter(ParameterSetName = "GET")] [Parameter(ParameterSetName = "POST", Mandatory)] $Name, [Parameter(ParameterSetName = "GET")] [Switch]$Get, [Parameter(ParameterSetName = "POST")] [Switch]$Post ) if ($Get) { # Get User } if ($Post) { # Create User } } ``` {% endcode %} ## Restituzione dei dati Si presume che i dati restituiti dagli endpoint siano dati JSON. Se restituisce un oggetto dal blocco di script dell'endpoint, viene serializzato automaticamente in JSON. Se desidera restituire un altro tipo di dati, può restituire una stringa formattata come preferisce. ## Elaborazione dei file ### Caricamento dei file Può elaborare i file caricati usando il parametro `$Data` per accedere all'array di byte dei dati caricati nell'endpoint. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Post -Endpoint { $Data } PS C:\Users\adamr> iwr http://localhost:5000/file -method post -InFile '.\Desktop\add-dashboard.png' StatusCode : 200 StatusDescription : OK Content : [137,80,78,71,13,10,26,10,0,0,0,13,73,72,68,82,0,0,2,17,0,0,1,92,8,2,0,0,0,249,210,123,106,0,0,0,1, 115,82,71,66,0,174,206,28,233,0,0,0,4,103,65,77,65,0,0,177,143,11,252,97,5,0,0,0,9,112,72,89,115,0, 0,… ``` {% endcode %} {% hint style="warning" %} Il tipo di contenuto `The multipart/form-data`non è supportato per il caricamento di file nelle API. {% endhint %} Può anche salvare il file in una directory. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Post -Endpoint { [IO.File]::WriteAllBytes("tempfile.dat", $Data) } ``` {% endcode %} ### Download dei file Può inviare i file usando il cmdlet `New-PSUApiResponse`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/image' -Endpoint { $ImageData = [IO.File]::ReadAllBytes("image.jpeg") New-PSUApiResponse -ContentType 'image/jpg' -Data $ImageData } ``` {% endcode %} ## Restituzione di risposte personalizzate Può restituire risposte personalizzate dagli endpoint usando il cmdlet `New-PSUApiResponse` nel suo endpoint. Questo cmdlet le consente di impostare il codice di stato, il tipo di contenuto e persino di specificare i dati byte\[] per il contenuto da restituire. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Get -Endpoint { New-PSUApiResponse -StatusCode 410 } ``` {% endcode %} Può anche restituire dati del body personalizzati con il parametro `-Body` di `New-PSUApiResponse`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Get -Endpoint { New-PSUApiResponse -Body "Not what you're looking for." -StatusCode 404 } ``` {% endcode %} Richiamare il metodo REST restituisce il codice di errore personalizzato. {% code collapsedlinecount="10" %} ```powershell PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:8080/file Invoke-RestMethod: Not what you're looking for. ``` {% endcode %} Può controllare il tipo di contenuto dei dati restituiti con il parametro `-ContentType`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Get -Endpoint { New-PSUApiResponse -Body "12" -ContentType 'text/xml' } ``` {% endcode %} Può controllare gli header della risposta con una hashtable di valori che passa al parametro `-Headers`. {% code collapsedlinecount="10" %} ```powershell New-PSUApiResponse -StatusCode 200 -Headers @{ "Referrer-Policy" = "no-referrer" } ``` {% endcode %} ## Runspace persistenti I runspace persistenti le consentono di mantenere lo stato del runspace tra le chiamate API. Questo è importante per gli utenti che eseguono una qualche forma di inizializzazione all'interno dei loro endpoint che non desiderano eseguire nelle chiamate API successive. Per impostazione predefinita, i runspace vengono reimpostati dopo ogni esecuzione. Questo rimuove variabili, moduli e funzioni definiti durante l'esecuzione dell'API. Per abilitare i runspace persistenti, dovrà configurare un [ambiente ](/powershell-universal/it/config/environments.md)per la sua API. Imposti il parametro `-PersistentRunspace` per abilitare questa funzionalità. Questo viene configurato nello script `environments.ps1`. {% code collapsedlinecount="10" %} ```powershell New-PSUEnvironment -Name 'Env' -Path 'powershell.exe' -PersistentRunspace ``` {% endcode %} Può quindi assegnare l'ambiente dell'API nello script `settings.ps1`. {% code collapsedlinecount="10" %} ```powershell Set-PSUSetting -ApiEnvironment 'Env' ``` {% endcode %} ## Timeout Per impostazione predefinita, gli endpoint non scadranno. Per impostare un timeout per i suoi endpoint, può usare il parametro `-Timeout` di `New-PSUEndpoint`. Il timeout è impostato in numero di secondi. ## Contenuto esterno dell'endpoint Può definire il percorso di un file di contenuto dell'endpoint esterno con il parametro `-Path` di `New-PSUEndpoint`. Il percorso è relativo alla directory `.universal` in Repository. Il contenuto del file `endpoints.ps1` è quindi questo: {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url "/path" -Path "endpoint-path.ps1" ``` {% endcode %} ## API C\# Le API C# sono abilitate come [plugin](/powershell-universal/it/piattaforma/plugins/c-api-endpoints.md). Non esiste un'interfaccia utente per creare un'API C#, quindi deve farlo usando i file di configurazione. Per prima cosa, crei un file `.cs` che esegue la sua API. Avrà accesso a un parametro `request` che include tutti i dati relativi alla richiesta API. {% code collapsedlinecount="10" %} ```csharp public class ApiRequest { public long Id; public ICollection Variables; public IEnumerable Files { get; set; }; public string Url; public ICollection Headers; public byte[] Data; public int ErrorAction; public ICollection Parameters; public string Method; public ICollection Cookies; public string ClaimsPrincipal; public string ContentType; } ``` {% endcode %} Avrà inoltre accesso a una proprietà `ServiceProvider` che le consente di accedere ai servizi all'interno di PowerShell Universal. Attualmente questi non sono ben documentati, ma di seguito è riportato un esempio di riavvio di una dashboard. {% code collapsedlinecount="10" %} ```csharp var dm = ServiceProvider.GetService(typeof(IDashboardManager)); var dashboard = dm.GetDashboard(1); dm.Restart(dashboard); ``` {% endcode %} Alcuni altri servizi utili includono: * IDatabase * IApiService * IConfigurationService * IJobService Può scegliere di restituire una `ApiResponse` dal suo endpoint. {% code collapsedlinecount="10" %} ```powershell return new ApiResponse { StatusCode = 404 }; ``` {% endcode %} Una volta definito il file dell'endpoint C#, può aggiungerlo modificando `endpoints.ps1`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url /csharp -Path endpoint.cs -Environment 'C#' ``` {% endcode %} Il servizio PowerShell Universal compila ed esegue automaticamente gli endpoint C#. ## API * [New-PSUEndpoint](/powershell-universal/it/comandi-powershell/new-psuendpoint.md) * [Get-PSUEndpoint](/powershell-universal/it/comandi-powershell/get-psuendpoint.md) * [Remove-PSUEndpoint](/powershell-universal/it/comandi-powershell/remove-psuendpoint.md) * [New-PSUApiResponse](/powershell-universal/it/comandi-powershell/new-psuapiresponse.md) * [Set-PSUSetting](/powershell-universal/it/comandi-powershell/set-psusetting.md) ### Vedere anche * [Devolutions Academy – Aggiunta della reimpostazione della password utente](https://academy.devolutions.net/student/activity/3546111-part-6-adding-reset-user-password) * [Devolutions Academy – Stato utente/aggiornamento dei dettagli utente](https://academy.devolutions.net/student/activity/3546046-part-5-user-status-refresh-user-details) * [Devolutions Academy – Aggiunta della funzionalità di sblocco utente](https://academy.devolutions.net/student/activity/3546024-part-4-adding-user-unlock-feature) * [Devolutions Academy – Creazione di un endpoint variabile](https://academy.devolutions.net/student/activity/3466016-creating-a-variable-endpoint) * [Devolutions Academy – Creazione di un endpoint con query string](https://academy.devolutions.net/student/activity/3466018-creating-a-query-string-endpoint) --- # 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/endpoints.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.