Endpunkte

Endpunkte werden durch ihre URI und HTTP-Methode definiert. Aufrufe an den Universal-Server, die mit Ihrem definierten API-Endpunkt und der Methode übereinstimmen, führen das API-Endpunktskript aus.

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

Um die obige Methode aufzurufen, können Sie Invoke-RestMethod verwenden.

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

Beim Definieren von Endpunkten in der Management-API können Sie den Aufruf von New-PSUEndpoint überspringen, da die Admin-Konsole ihn definiert.

API Properties

Der einzige Inhalt, den Sie im Editor angeben müssen, ist das Skript, das Sie aufrufen möchten.

API Content

Vermeiden Sie die Verwendung von Endpunkt-URLs, die mit internen PowerShell Universal Management-API-URLs übereinstimmen, da dies zu unerwartetem Verhalten führt. Sie können die OpenAPI-Dokumentation für die Management-API heranziehen, um zu überprüfen, dass keine der URLs übereinstimmt.

HTTP-Methoden

Endpunkte können eine oder mehrere HTTP-Methoden definiert haben. Um zu bestimmen, welche Methode von einem Endpunkt verwendet wird, verwenden Sie die integrierte Variable $Method.

New-PSUEndpoint -Url '/user' -Method @('GET', 'POST') -Endpoint {
    if ($Method -eq 'GET')
    {
       Get-User
    }
    else {
       New-User
    }
}

Variable URL

URLs können variable Segmente enthalten. Sie können ein variables Segment mit einem Doppelpunkt (:) kennzeichnen. Zum Beispiel würde die folgende URL eine Variable für die ID des Benutzers bereitstellen. Die Variable $Id wird innerhalb des Endpunkts definiert, wenn dieser ausgeführt wird. Variablen müssen in derselben Endpunkt-URL eindeutig sein.

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

Um diese API aufzurufen und die ID anzugeben, gehen Sie wie folgt vor:

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

Query-String-Parameter

Query-String-Parameter werden automatisch als Variablen an Endpunkte übergeben, auf die Sie dann zugreifen können. Wenn Sie beispielsweise einen Endpunkt haben, der eine $Id-Variable erwartet, können Sie diese im Query-String angeben.

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

Der resultierende Invoke-RestMethod-Aufruf muss dann den Query-String-Parameter enthalten.

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

Wenn Sie mehrere Query-String-Parameter verwenden, stellen Sie sicher, dass Ihre URL von Anführungszeichen umgeben ist, damit PowerShell sie korrekt übersetzt. Ein kaufmännisches Und (&) ohne Anführungszeichen verursacht sowohl in Windows PowerShell als auch in PowerShell 7 Probleme.

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

Sicherheitsüberlegungen

Wenn Sie Eingaben über Query-String-Parameter akzeptieren, sind Sie möglicherweise anfällig für CWE-914: Improper Control of Dynamically-Identified Variables. Erwägen Sie die Verwendung eines param-Blocks, um sicherzustellen, dass nur gültige Parameter an den Endpunkt übergeben werden.

Nachfolgend ein Beispiel für CWE-914. Fügen Sie einen $IsChallengePassed-Query-String-Parameter hinzu, um die Challenge zu umgehen.

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

Um dieses spezielle Problem zu vermeiden, können Sie einen param-Block verwenden.

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

Anfrage-Header sind in APIs über die Variable $Headers verfügbar. Die Variable ist eine Hashtabelle. Um auf einen Header zuzugreifen, verwenden Sie die folgende Syntax:

$Headers['Content-Type']

Cookies

Anfrage-Cookies sind in APIs über die Variable $Cookies verfügbar. Die Variable ist eine Hashtabelle. Um auf ein Cookie zuzugreifen, verwenden Sie die folgende Syntax:

$Cookies['Request-Cookie']

Senden Sie Anfrage-Cookies mit dem Cmdlet New-PSUApiResponse zurück. Verwenden Sie den Parameter -Cookies mit einer bereitgestellten Hashtabelle.

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

Body

Um auf einen Anfragekörper zuzugreifen, greifen Sie einfach auf die Variable $Body zu. Die Universal-Variable $Body ist eine Zeichenfolge. Wenn Sie JSON erwarten, sollten Sie ConvertFrom-Json verwenden.

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

Um den obigen Endpunkt aufzurufen, geben Sie den Body von Invoke-RestMethod an.

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

Live-Protokoll

Sie können die Live-Protokollinformationen für jeden Endpunkt anzeigen, indem Sie auf die Registerkarte „Log“ klicken. Live-Protokolle enthalten URL, HTTP-Methode, Quell-IP-Adresse, PowerShell-Streams, Statuscode, zurückgegebenen Content-Type und HTTP-Inhaltslänge.

Sie können mit Cmdlets wie Write-Host aus Ihren Endpunkten heraus in das Live-Protokoll schreiben.

Live-Protokoll des Endpunkts

Testen

Sie können die Registerkarte „Test“ im Endpunkt-Editor verwenden, um Ihre APIs zu testen. Mit diesem Testwerkzeug können Sie Header, den Query-String und den Body anpassen. Sie können auch die Authentifizierung und Autorisierung für den Test anpassen.

Registerkarte „Test“ des Endpunkts

Bei Verwendung der Registerkarte „Test“ führen alle Änderungen an den Werten des Tests zu einem aktualisierten Codeblock, den Sie dann in PowerShell verwenden können. Klicken Sie auf die Registerkarte „Code“, um den Testcode anzuzeigen.

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

Zusätzlich werden im Tester durchgeführte Tests 30 Tage lang gespeichert, um ein erneutes Testen zu ermöglichen, ohne alle Eigenschaften neu konfigurieren zu müssen. Ein Klick auf die Schaltfläche „Apply“ richtet das Testwerkzeug mit denselben Eigenschaften ein.

Testverlauf

Formulardaten

Sie können Daten als Formulardaten an einen Endpunkt übergeben. Formulardaten werden als Parameter an Ihren Endpunkt übergeben.

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

Sie können dann eine Hashtabelle mit Invoke-RestMethod verwenden, um Formulardaten zu übergeben.

Invoke-RestMethod http://localhost:5000/user -Method Post -Body @{ 
    UserName = "adriscoll"
    FirstName = "Adam"
    LastName = "Driscoll"
}

JSON-Daten

Sie können JSON-Daten an einen Endpunkt übergeben und sie werden automatisch an einen param-Block gebunden.

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

Sie können dann JSON-Daten an den Endpunkt senden.

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

Param-Block

Sie können innerhalb Ihres Skripts einen param-Block verwenden, um obligatorische Parameter zu erzwingen und Standardwerte für optionale Parameter wie Query-String-Parameter bereitzustellen. Variablen wie $Body, $Headers und $User werden automatisch bereitgestellt.

Im folgenden Beispiel ist der Parameter $Name obligatorisch und der Parameter $Role hat den Standardwert Default.

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

Wenn Sie den param-Block mit Routenparametern wie im obigen Beispiel verwenden, müssen Sie die Routenvariable in Ihrem Parameter angeben. Wird sie nicht angegeben, haben Sie keinen Zugriff auf diesen Wert.

Zum Beispiel ist die folgende Variable $Name immer $null. Der Endpunkt gibt immer false zurück.

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

Wenn Sie das Attribut CmdletBinding oder Parameter innerhalb Ihres param-Blocks verwenden, erzwingt der Endpunkt strikt, welche Parameter in den Endpunkt gelangen dürfen.

Zum Beispiel erzwingt das Folgende, dass der Parameter „name“ angegeben wird.

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

Allerdings können Sie dem Endpunkt keine zusätzlichen Parameter angeben. Das Folgende verursacht einen Fehler.

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

Wenn Sie Ihren Endpunkt so ändern, dass er das Attribut Parameter nicht verwendet, können Sie beliebig viele Parameter übergeben, die dann als Variablen und nicht als Parameter des Endpunkts gebunden werden.

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

Parametersätze für Methoden

Sie können Parametersätze mithilfe von Methodenparametern definieren. Standardmäßig untersucht PowerShell Universal den param-Block, um festzustellen, ob diese HTTP-Methodennamen Get, Put, Post, Delete oder andere angegeben sind, und bindet sie automatisch ein. Wenn Endpunkte mehrere Methoden akzeptieren, kann möglicherweise nicht anhand der bereitgestellten Daten bestimmt werden, welcher Parametersatz aufgerufen werden soll. Im Beispiel unten akzeptieren sowohl Get als auch Post den Parameter „name“. Es gibt außerdem keine Möglichkeit, das Post ohne einen Namen aufzurufen, sodass die Validierung fehlschlagen könnte.

Um dies zu beheben, fügen Sie die Parameter Post und Get hinzu, die Teil ihres jeweiligen Parametersatzes sind. PowerShell Universal bindet diesen Parameter ein, um sicherzustellen, dass der richtige Parametersatz aufgerufen wird.

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

Daten zurückgeben

Es wird angenommen, dass von Endpunkten zurückgegebene Daten JSON-Daten sind. Wenn Sie ein Objekt aus dem Endpunkt-Skriptblock zurückgeben, wird es automatisch in JSON serialisiert. Wenn Sie eine andere Art von Daten zurückgeben möchten, können Sie eine beliebig formatierte Zeichenfolge zurückgeben.

Dateien verarbeiten

Dateien hochladen

Sie können hochgeladene Dateien verarbeiten, indem Sie den Parameter $Data verwenden, um auf das Byte-Array der an den Endpunkt hochgeladenen Daten zuzugreifen.

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

Der Inhaltstyp The multipart/form-datawird für das Hochladen von Dateien zu APIs nicht unterstützt.

Sie können die Datei auch in einem Verzeichnis speichern.

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

Dateien herunterladen

Sie können Dateien mit dem Cmdlet New-PSUApiResponse senden.

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

Benutzerdefinierte Antworten zurückgeben

Sie können benutzerdefinierte Antworten aus Endpunkten zurückgeben, indem Sie das Cmdlet New-PSUApiResponse in Ihrem Endpunkt verwenden. Mit diesem Cmdlet können Sie den Statuscode und den Inhaltstyp festlegen und sogar die byte[]-Daten für den zurückzugebenden Inhalt angeben.

New-PSUEndpoint -Url '/file' -Method Get -Endpoint {
    New-PSUApiResponse -StatusCode 410
}

Sie können auch benutzerdefinierte Body-Daten mit dem Parameter -Body von New-PSUApiResponse zurückgeben.

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

Der Aufruf der REST-Methode gibt den benutzerdefinierten Fehlercode zurück.

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

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

Sie können den Inhaltstyp der zurückgegebenen Daten mit dem Parameter -ContentType steuern.

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

Sie können die Antwort-Header mit einer Hashtabelle von Werten steuern, die Sie an den Parameter -Headersübergeben.

New-PSUApiResponse -StatusCode 200 -Headers @{
    "Referrer-Policy" = "no-referrer"
}

Persistente Runspaces

Persistente Runspaces ermöglichen es Ihnen, den Runspace-Status zwischen API-Aufrufen beizubehalten. Dies ist wichtig für Benutzer, die innerhalb ihrer Endpunkte eine Art von Initialisierung durchführen, die sie bei nachfolgenden API-Aufrufen nicht ausführen möchten.

Standardmäßig werden Runspaces nach jeder Ausführung zurückgesetzt. Dadurch werden Variablen, Module und Funktionen entfernt, die während der Ausführung der API definiert wurden.

Um persistente Runspaces zu aktivieren, müssen Sie eine Umgebung für Ihre API konfigurieren. Setzen Sie den Parameter -PersistentRunspace, um diese Funktion zu aktivieren. Dies wird im Skript environments.ps1 konfiguriert.

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

Sie können die API-Umgebung dann im Skript settings.ps1 zuweisen.

Set-PSUSetting -ApiEnvironment 'Env'

Timeout

Standardmäßig laufen Endpunkte nicht ab. Um ein Timeout für Ihre Endpunkte festzulegen, können Sie den Parameter -Timeout von New-PSUEndpoint verwenden. Das Timeout wird in Sekunden angegeben.

Externer Endpunktinhalt

Sie können den Pfad zu einer externen Endpunktinhaltsdatei mit dem Parameter -Path von New-PSUEndpoint definieren. Der Pfad ist relativ zum Verzeichnis .universal im Repository.

Der Inhalt der Datei endpoints.ps1 lautet dann folgendermaßen:

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

C#-APIs

C#-APIs werden als Plugin aktiviert.

Es gibt keine Benutzeroberfläche zum Erstellen einer C#-API, daher müssen Sie dies über Konfigurationsdateien tun. Erstellen Sie zunächst eine .cs-Datei, die Ihre API ausführt.

Sie haben Zugriff auf einen request-Parameter, der alle Daten über die API-Anfrage enthält.

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

Sie haben außerdem Zugriff auf eine ServiceProvider-Eigenschaft, die Ihnen den Zugriff auf Dienste innerhalb von PowerShell Universal ermöglicht. Diese sind derzeit nicht gut dokumentiert, aber nachfolgend finden Sie ein Beispiel für den Neustart eines Dashboards.

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

Einige andere nützliche Dienste sind:

• IDatabase
• IApiService
• IConfigurationService
• IJobService

Sie können wählen, eine ApiResponse von Ihrem Endpunkt zurückzugeben.

return new ApiResponse {
    StatusCode = 404
};

Sobald Sie Ihre C#-Endpunktdatei definiert haben, können Sie sie durch Bearbeiten von endpoints.ps1 hinzufügen.

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

Der PowerShell Universal-Dienst kompiliert und führt C#-Endpunkte automatisch aus.

API

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

Siehe auch

• Devolutions Academy – Adding reset user password
• Devolutions Academy – User status/refresh user details
• Devolutions Academy – Adding user unlock feature
• Devolutions Academy – Creating a variable endpoint
• Devolutions Academy – Creating a query string endpoint