> 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
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.
```powershell
New-PSUEndpoint -Url '/endpoint' -Method 'GET' -Endpoint {
"Hello, world!"
}
```
Per richiamare il metodo sopra riportato, può utilizzare `Invoke-RestMethod`.
```powershell
Invoke-RestMethod http://localhost:5000/endpoint
```
Quando si definiscono gli endpoint nell'API di gestione, è possibile saltare la chiamata `New-PSUEndpoint`, poiché la console di amministrazione la definisce.
L'unico contenuto che deve fornire nell'editor è lo script che desidera chiamare.
{% hint style="warning" %}
Eviti di utilizzare URL di endpoint che corrispondono agli URL interni dell'API di gestione di PowerShell Universal, poiché ciò causa comportamenti imprevisti. Può fare riferimento alla [documentazione OpenAPI](/powershell-universal/it/api/openapi.md#management-api-documentation) per l'[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 utilizzato da un endpoint, utilizzi la variabile integrata `$Method`.
```powershell
New-PSUEndpoint -Url '/user' -Method @('GET', 'POST') -Endpoint {
if ($Method -eq 'GET')
{
Get-User
}
else {
New-User
}
}
```
## URL variabile
Gli URL possono contenere segmenti variabili. È possibile indicare un segmento variabile utilizzando i due punti (`:`). Ad esempio, l'URL seguente 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.
```powershell
New-PSUEndpoint -Url '/user/:id' -Method 'GET' -Endpoint {
Get-User -Id $Id
}
```
Per chiamare questa API e specificare l'ID, proceda come segue:
```powershell
Invoke-RestMethod http://localhost:5000/user/123
```
## Parametri della query string
I parametri della query string vengono passati automaticamente agli endpoint come variabili a cui può quindi accedere. Ad esempio, se ha un endpoint che si aspetta una variabile `$Id`, può fornirla nella query string.
```powershell
New-PSUEndpoint -Url '/user' -Method 'GET' -Endpoint {
Get-User -Id $Id
}
```
La chiamata `Invoke-RestMethod` risultante deve quindi includere il parametro della query string.
```powershell
Invoke-RestMethod http://localhost:5000/user?Id=123
```
Quando si utilizzano 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 che in PowerShell 7.
```powershell
Invoke-RestMethod "http://localhost:5000/user?Id=123&name=tim"
```
### Considerazioni sulla sicurezza
Quando si accettano input tramite parametri della query string, si potrebbe essere vulnerabili a [CWE-914: Improper Control of Dynamically-Identified Variables](https://cwe.mitre.org/data/definitions/914.html). Valuti 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 bypassare la sfida.
```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"
}
}
```
Per evitare questo particolare problema, può utilizzare un blocco `param`.
```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"
}
}
```
## Intestazioni
Le intestazioni della richiesta sono disponibili nelle API tramite la variabile `$Headers`. La variabile è una hashtable. Per accedere a un'intestazione, utilizzi la sintassi seguente:
```powershell
$Headers['Content-Type']
```
## Cookie
I cookie della richiesta sono disponibili nelle API tramite la variabile `$Cookies`. La variabile è una hashtable. Per accedere a un cookie, utilizzi la sintassi seguente:
```powershell
$Cookies['Request-Cookie']
```
Rimandi indietro i cookie della richiesta con il cmdlet `New-PSUApiResponse`. Utilizzi il parametro `-Cookies` con una hashtable fornita.
```powershell
New-PSUApiResponse -StatusCode 200 -Cookies @{
ResponseCookie = '123'
}
```
## Body
Per accedere al corpo di una richiesta, dovrà semplicemente accedere alla variabile `$Body`. La variabile `$Body` di Universal sarà una stringa. Se si aspetta JSON, dovrebbe utilizzare `ConvertFrom-Json`.
```powershell
New-PSUEndpoint -Url '/user' -Method Post -Endpoint {
$User = ConvertFrom-Json $Body
New-User $User
}
```
Per chiamare l'endpoint sopra riportato, specifichi il corpo di `Invoke-RestMethod`.
```powershell
Invoke-RestMethod http://localhost:5000/user -Method Post -Body "{'username': 'adam'}"
```
## 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 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`.
Log live dell'endpoint
## Test
Può utilizzare la scheda Test nell'editor degli endpoint per testare le sue API. Utilizzando questo strumento di test, può regolare le intestazioni, la query string e il corpo. Può anche regolare l'autenticazione e l'autorizzazione per il test.
Scheda Test dell'endpoint
Quando si utilizza la scheda Test, qualsiasi modifica ai valori del test comporterà un blocco di codice aggiornato che potrà quindi utilizzare in PowerShell. Faccia clic sulla scheda Codice per visualizzare il codice del test.
```powershell
Invoke-RestMethod -Uri 'http://localhost:5000/test-api?Page=1' -Headers @{'X-Custom-Header' = 'Value';} -Method 'POST'
```
Inoltre, i test eseguiti all'interno del tester verranno conservati per 30 giorni per consentire di ripetere il test senza dover riconfigurare tutte le proprietà. Facendo clic sul pulsante Applica si configurerà lo strumento di test con le stesse proprietà.
Cronologia dei test
## Dati del modulo
Può passare dati a un endpoint come dati del modulo. I dati del modulo verranno passati al suo endpoint come parametri.
```powershell
New-PSUEndpoint -Url '/user' -Method Post -Endpoint {
param([Parameter(Mandatory)]$userName, $FirstName, $LastName)
New-User $UserName -FirstName $FirstName -LastName $LastName
}
```
Può quindi utilizzare una hashtable con Invoke-RestMethod per passare i dati del modulo.
```powershell
Invoke-RestMethod http://localhost:5000/user -Method Post -Body @{
UserName = "adriscoll"
FirstName = "Adam"
LastName = "Driscoll"
}
```
## Dati JSON
Può passare dati JSON a un endpoint e verranno associati automaticamente a un blocco param.
```powershell
New-PSUEndpoint -Url '/user' -Method Post -Endpoint {
param([Parameter(Mandatory)]$userName, $FirstName, $LastName)
New-User $UserName -FirstName $FirstName -LastName $LastName
}
```
Può quindi inviare dati JSON all'endpoint.
```powershell
Invoke-RestMethod http://localhost:5000/user -Method Post -Body (@{
UserName = "adriscoll"
FirstName = "Adam"
LastName = "Driscoll"
} | ConvertTo-Json) -ContentType 'application/json'
```
## Blocco param
Può utilizzare un blocco `param` all'interno del suo script per imporre parametri obbligatori e fornire valori predefiniti per i parametri facoltativi, 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.
```powershell
New-PSUEndpoint -Url '/user/:name' -Endpoint {
param([Parameter(Mandatory)$Name, $Role = "Default")
}
```
Quando si utilizza il blocco `param` con parametri di route come nell'esempio precedente, è necessario includere la variabile di route nel parametro. Se non viene specificata, non avrà accesso a quel valore.
Ad esempio, la seguente variabile `$Name` è sempre `$null`. L'endpoint restituisce sempre false.
```powershell
New-PSUEndpoint -Url '/user/:name' -Endpoint {
param($Role = "Default")
$Name -eq 'Adam'
}
```
Se utilizza l'attributo `CmdletBinding` o `Parameter` all'interno del blocco param, l'endpoint imporrà rigorosamente quali parametri sono ammessi nell'endpoint.
Ad esempio, quanto segue impone che il parametro name sia specificato.
```powershell
New-PSUEndpoint -Url '/user' -Endpoint {
param([Parameter(Mandatory)$Name)
}
```
Detto questo, non può specificare parametri aggiuntivi per l'endpoint. Eseguendo quanto segue si verificherà un errore.
```powershell
Invoke-RestMethod http://localhost:5000/user -Method Post -Body (@{
Name = "adriscoll"
DisplayName = 'Adam'
} | ConvertTo-Json) -ContentType 'application/json'
```
Se modifica il suo endpoint per evitare di utilizzare l'attributo `Parameter`, può passare un numero qualsiasi di parametri e verranno associati come variabili e non come parametri dell'endpoint.
```powershell
New-PSUEndpoint -Url '/user' -Endpoint {
param($Name)
}
```
### Set di parametri dei metodi
È possibile definire set di parametri utilizzando i parametri dei metodi. Per impostazione predefinita, PowerShell Universal ispeziona 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 Get che Post accettano il parametro name. Inoltre non c'è modo di chiamare 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" %}
```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 automaticamente serializzato 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 utilizzando il parametro `$Data` per accedere all'array di byte dei dati caricati nell'endpoint.
```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,…
```
{% 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.
```powershell
New-PSUEndpoint -Url '/file' -Method Post -Endpoint {
[IO.File]::WriteAllBytes("tempfile.dat", $Data)
}
```
### Download dei file
Può inviare i file utilizzando il cmdlet `New-PSUApiResponse`.
```powershell
New-PSUEndpoint -Url '/image' -Endpoint {
$ImageData = [IO.File]::ReadAllBytes("image.jpeg")
New-PSUApiResponse -ContentType 'image/jpg' -Data $ImageData
}
```
## Restituzione di risposte personalizzate
Può restituire risposte personalizzate dagli endpoint utilizzando 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.
```powershell
New-PSUEndpoint -Url '/file' -Method Get -Endpoint {
New-PSUApiResponse -StatusCode 410
}
```
Può anche restituire dati del corpo personalizzati con il parametro `-Body` di `New-PSUApiResponse`.
```powershell
New-PSUEndpoint -Url '/file' -Method Get -Endpoint {
New-PSUApiResponse -Body "Not what you're looking for." -StatusCode 404
}
```
Richiamando il metodo REST viene restituito il codice di errore personalizzato.
```powershell
PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:8080/file
Invoke-RestMethod: Not what you're looking for.
```
Può controllare il tipo di contenuto dei dati restituiti con il parametro `-ContentType`.
```powershell
New-PSUEndpoint -Url '/file' -Method Get -Endpoint {
New-PSUApiResponse -Body "12" -ContentType 'text/xml'
}
```
Può controllare le intestazioni di risposta con una hashtable di valori che passa al parametro `-Headers`.
```powershell
New-PSUApiResponse -StatusCode 200 -Headers @{
"Referrer-Policy" = "no-referrer"
}
```
## Runspace persistenti
I runspace persistenti le consentono di mantenere lo stato del runspace tra le chiamate API. Questo è importante per gli utenti che eseguono un qualche tipo 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. Ciò 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`.
```powershell
New-PSUEnvironment -Name 'Env' -Path 'powershell.exe' -PersistentRunspace
```
Può quindi assegnare l'ambiente API nello script `settings.ps1`.
```powershell
Set-PSUSetting -ApiEnvironment 'Env'
```
## Timeout
Per impostazione predefinita, gli endpoint non vanno in timeout. Per impostare un timeout per i suoi endpoint, può utilizzare il parametro `-Timeout` di `New-PSUEndpoint`. Il timeout è impostato in numero di secondi.
## Contenuto dell'endpoint esterno
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` nel Repository.
Il contenuto del file `endpoints.ps1` è quindi il seguente:
```powershell
New-PSUEndpoint -Url "/path" -Path "endpoint-path.ps1"
```
## API C\#
Le API C# sono abilitate come [plugin](/powershell-universal/it/piattaforma/plugins.md#c-api-environment).
Non esiste un'interfaccia utente per creare un'API C#, quindi deve farlo utilizzando i file di configurazione. Innanzitutto, crei un file `.cs` che esegue la sua API.
Avrà accesso a un parametro `request` che include tutti i dati sulla richiesta API.
```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;
}
```
Avrà anche accesso a una proprietà `ServiceProvider` che le consente di accedere ai servizi all'interno di PowerShell Universal. Attualmente non sono ben documentati, ma di seguito è riportato un esempio di riavvio di una dashboard.
```csharp
var dm = ServiceProvider.GetService(typeof(IDashboardManager));
var dashboard = dm.GetDashboard(1);
dm.Restart(dashboard);
```
Altri servizi utili includono:
* IDatabase
* IApiService
* IConfigurationService
* IJobService
Può scegliere di restituire una `ApiResponse` dal suo endpoint.
```powershell
return new ApiResponse {
StatusCode = 404
};
```
Una volta definito il file dell'endpoint C#, può aggiungerlo modificando `endpoints.ps1`.
```powershell
New-PSUEndpoint -Url /csharp -Path endpoint.cs -Environment 'C#'
```
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)
---
# 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.