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.

New-PSUEndpoint -Url '/endpoint' -Method 'GET' -Endpoint {
   "Hello, world!"
}

Per invocare il metodo sopra, può usare Invoke-RestMethod.

Invoke-RestMethod http://localhost:5000/endpoint

Quando definisce gli endpoint nell'API di gestione, può saltare la chiamata New-PSUEndpoint, poiché la console di amministrazione la definisce.

Proprietà API

L'unico contenuto che deve fornire nell'editor è lo script che desidera chiamare.

Contenuto API

Eviti di usare 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 della Management API per verificare che nessuno degli URL corrisponda.

Metodi HTTP

Gli endpoint possono avere uno o più metodi HTTP definiti. Per determinare quale metodo è usato da un endpoint, usi la variabile integrata $Method.

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. Può indicare un segmento variabile usando i due punti (:). Ad 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.

New-PSUEndpoint -Url '/user/:id' -Method 'GET' -Endpoint {
   Get-User -Id $Id
}

Per chiamare questa API e specificare l'ID, proceda come segue:

Invoke-RestMethod http://localhost:5000/user/123

Parametri della stringa di query

I parametri della stringa di query vengono passati automaticamente agli endpoint come variabili a cui può poi accedere. Ad esempio, se ha un endpoint che si aspetta una variabile $Id, può fornirla nella stringa di query.

New-PSUEndpoint -Url '/user' -Method 'GET' -Endpoint {
   Get-User -Id $Id
}

La chiamata Invoke-RestMethod risultante deve quindi includere il parametro della stringa di query.

Invoke-RestMethod http://localhost:5000/user?Id=123

Quando usa più parametri della stringa di query, si assicuri che l'URL sia racchiuso tra virgolette in modo che PowerShell lo interpreti correttamente. Includere una e commerciale (&) senza virgolette causerà problemi sia in Windows PowerShell sia in PowerShell 7.

Invoke-RestMethod "http://localhost:5000/user?Id=123&name=tim"

Considerazioni sulla sicurezza

Quando accetta input tramite parametri della stringa di query, potrebbe essere vulnerabile a CWE-914: Improper Control of Dynamically-Identified Variables. Consideri di usare un blocco param per garantire che vengano forniti all'endpoint solo parametri validi.

Di seguito è riportato un esempio di CWE-914. Includa un parametro della stringa di query $IsChallengePassed per bypassare la challenge.

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ò usare un blocco param.

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"
	}
}

Header

Gli header della richiesta sono disponibili nelle API tramite la variabile $Headers. La variabile è una hashtable. Per accedere a un header, usi la seguente sintassi:

$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, usi la seguente sintassi:

$Cookies['Request-Cookie']

Rimandi indietro i cookie della richiesta con il cmdlet New-PSUApiResponse. Usi il parametro -Cookies con una hashtable fornita.

New-PSUApiResponse -StatusCode 200 -Cookies @{
    ResponseCookie = '123'
}

Corpo

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 usare ConvertFrom-Json.

New-PSUEndpoint -Url '/user' -Method Post -Endpoint {
    $User = ConvertFrom-Json $Body 
    New-User $User
}

Per chiamare l'endpoint sopra, specifichi il corpo di Invoke-RestMethod.

Invoke-RestMethod http://localhost:5000/user -Method Post -Body "{'username': 'adam'}"

Log in tempo reale

Può visualizzare le informazioni del log in tempo reale per qualsiasi endpoint facendo clic sulla scheda del log. I log in tempo reale 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 in tempo reale dall'interno dei suoi endpoint con cmdlet come Write-Host.

Log in tempo reale dell'endpoint

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 stringa di query e il corpo. Può anche modificare l'autenticazione e l'autorizzazione per il test.

Scheda Test dell'endpoint

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.

Invoke-RestMethod -Uri 'http://localhost:5000/test-api?Page=1' -Headers @{'X-Custom-Header' = 'Value';} -Method 'POST'

Inoltre, i test eseguiti nel tester saranno archiviati per 30 giorni per consentire di ripetere il test senza dover riconfigurare tutte le proprietà. Facendo clic sul pulsante Apply si configurerà lo strumento di test con le stesse proprietà.

Cronologia dei test

Dati del form

Può passare dati a un endpoint come dati del form. I dati del form verranno passati al suo endpoint come parametri.

New-PSUEndpoint -Url '/user' -Method Post -Endpoint {
    param([Parameter(Mandatory)]$userName, $FirstName, $LastName)
     
    New-User $UserName -FirstName $FirstName -LastName $LastName
}

Può quindi usare una hashtable con Invoke-RestMethod per passare i dati del form.

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.

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.

Invoke-RestMethod http://localhost:5000/user -Method Post -Body (@{ 
    UserName = "adriscoll"
    FirstName = "Adam"
    LastName = "Driscoll"
} | ConvertTo-Json) -ContentType 'application/json'

Blocco param

Può usare un blocco param all'interno del suo script per imporre parametri obbligatori e fornire valori predefiniti per i parametri facoltativi come i parametri della stringa di query. Variabili come $Body, $Headers e $User vengono fornite automaticamente.

Nell'esempio seguente, il parametro $Name è obbligatorio e il parametro $Role ha un valore predefinito di Default.

New-PSUEndpoint -Url '/user/:name' -Endpoint {
    param([Parameter(Mandatory)$Name, $Role = "Default")
}

Quando usa il blocco param con parametri di route come nell'esempio sopra, deve includere la variabile di route nel suo parametro. Se non è specificata, non avrà accesso a quel valore.

Ad esempio, la seguente variabile $Name è sempre $null. L'endpoint restituisce sempre false.

New-PSUEndpoint -Url '/user/:name' -Endpoint {
    param($Role = "Default")
    
    $Name -eq 'Adam'
}

Se usa l'attributo CmdletBinding o Parameter all'interno del blocco param, l'endpoint imporrà rigorosamente quali parametri sono consentiti nell'endpoint.

Ad esempio, quanto segue impone che il parametro name sia specificato.

New-PSUEndpoint -Url '/user' -Endpoint {
    param([Parameter(Mandatory)$Name)
}

Detto questo, non può specificare parametri aggiuntivi all'endpoint. Fare quanto segue causerà un errore.

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 usare l'attributo Parameter, può passare un numero qualsiasi di parametri e saranno associati come variabili e non come parametri dell'endpoint.

New-PSUEndpoint -Url '/user' -Endpoint {
    param($Name)
}

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 di metodo 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 sia Post accettano il parametro name. Inoltre non c'è modo di chiamare Post senza un nome, quindi la convalida potrebbe fallire.

Per ovviare a questo, includa i parametri Post e Get che fanno parte dei rispettivi set di parametri. PowerShell Universal includerà questo parametro per garantire che venga chiamato il set di parametri corretto.

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
    }
}

Restituzione dei dati

Si presume che i dati restituiti dagli endpoint siano dati JSON. Se restituisce un oggetto dallo script block 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 usando il parametro $Data per accedere all'array di byte dei dati caricati nell'endpoint.

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,…

The multipart/form-datacontent type non è supportato per il caricamento di file nelle API.

Può anche salvare il file in una directory.

New-PSUEndpoint -Url '/file' -Method Post -Endpoint {
    [IO.File]::WriteAllBytes("tempfile.dat", $Data)
}

Download dei file

Può inviare i file usando il cmdlet New-PSUApiResponse.

New-PSUEndpoint -Url '/image' -Endpoint {
    $ImageData = [IO.File]::ReadAllBytes("image.jpeg")
    New-PSUApiResponse -ContentType 'image/jpg' -Data $ImageData
}

Restituire 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 content type e persino di specificare i dati byte[] per il contenuto da restituire.

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.

New-PSUEndpoint -Url '/file' -Method Get -Endpoint {
    New-PSUApiResponse -Body "Not what you're looking for." -StatusCode 404
}

L'invocazione del metodo REST restituisce il codice di errore personalizzato.

PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:8080/file

Invoke-RestMethod: Not what you're looking for.

Può controllare il content type dei dati restituiti con il parametro -ContentType.

New-PSUEndpoint -Url '/file' -Method Get -Endpoint {
    New-PSUApiResponse -Body "<xml><node>1</node><node2>2</node2></xml>" -ContentType 'text/xml'
}

Può controllare gli header della risposta con una hashtable di valori che passa al parametro -Headers.

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 per la sua API. Imposti il parametro -PersistentRunspace per abilitare questa funzionalità. Questo viene configurato nello script environments.ps1.

New-PSUEnvironment -Name 'Env' -Path 'powershell.exe' -PersistentRunspace

Può quindi assegnare l'ambiente API nello script settings.ps1.

Set-PSUSetting -ApiEnvironment 'Env'

Timeout

Per impostazione predefinita, gli endpoint non andranno in timeout. Per impostare un timeout per i suoi endpoint, può usare 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:

New-PSUEndpoint -Url "/path" -Path "endpoint-path.ps1"

API C#

Le API C# sono abilitate come plugin.

Non esiste un'interfaccia utente per creare un'API C#, quindi deve farlo usando 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.

public class ApiRequest
{
    public long Id;
    public ICollection<KeyValue> Variables;
    public IEnumerable<ApiFile> Files { get; set; };
    public string Url;
    public ICollection<KeyValue> Headers;
    public byte[] Data;
    public int ErrorAction;
    public ICollection<KeyValue> Parameters;
    public string Method;
    public ICollection<KeyValue> 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.

var dm = ServiceProvider.GetService(typeof(IDashboardManager));
var dashboard = dm.GetDashboard(1);
dm.Restart(dashboard);

Alcuni altri servizi utili includono:

• IDatabase
• IApiService
• IConfigurationService
• IJobService

Può scegliere di restituire un ApiResponse dal suo endpoint.

return new ApiResponse {
    StatusCode = 404
};

Una volta definito il file dell'endpoint C#, può aggiungerlo modificando endpoints.ps1.

New-PSUEndpoint -Url /csharp -Path endpoint.cs -Environment 'C#'

Il servizio PowerShell Universal compila ed esegue automaticamente gli endpoint C#.

API

• New-PSUEndpoint
• Get-PSUEndpoint
• Remove-PSUEndpoint
• New-PSUApiResponse
• Set-PSUSetting

Vedi anche

• Devolutions Academy – Aggiunta della reimpostazione della password utente
• Devolutions Academy – Stato utente/aggiornamento dei dettagli utente
• Devolutions Academy – Aggiunta della funzionalità di sblocco utente
• Devolutions Academy – Creazione di un endpoint variabile
• Devolutions Academy – Creazione di un endpoint con stringa di query