> 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/de/api/endpoints.md). # Endpunkte Konfigurieren Sie PowerShell Universal API-Endpunkte mit New-PSUEndpoint – behandelt URL-Routing, Header, Cookies, Anfragekörper, Datei-Uploads und benutzerdefinierte Antworten. 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-Endpunkt-Skript aus. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/endpoint' -Method 'GET' -Endpoint { "Hello, world!" } ``` {% endcode %} Um die obige Methode aufzurufen, können Sie `Invoke-RestMethod` verwenden. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/endpoint ``` {% endcode %} Wenn Sie Endpunkte in der Management-API definieren, können Sie den Aufruf von `New-PSUEndpoint` überspringen, da die Admin-Konsole ihn definiert. Der einzige Inhalt, den Sie im Editor angeben müssen, ist das Skript, das Sie aufrufen möchten. {% hint style="warning" %} Vermeiden Sie die Verwendung von Endpunkt-URLs, die mit internen URLs der PowerShell Universal Management-API übereinstimmen, da dies unerwartetes Verhalten verursacht. Sie können die [OpenAPI-Dokumentation](/powershell-universal/de/api/openapi.md#management-api-documentation) für die [Management-API](/powershell-universal/de/config/management-api.md) heranziehen, um zu überprüfen, dass keine der URLs übereinstimmt. {% endhint %} ## 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`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method @('GET', 'POST') -Endpoint { if ($Method -eq 'GET') { Get-User } else { New-User } } ``` {% endcode %} ## 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 innerhalb derselben Endpunkt-URL eindeutig sein. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user/:id' -Method 'GET' -Endpoint { Get-User -Id $Id } ``` {% endcode %} Um diese API aufzurufen und die ID anzugeben, gehen Sie wie folgt vor: {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user/123 ``` {% endcode %} ## Query-String-Parameter Query-String-Parameter werden automatisch als Variablen an Endpunkte übergeben, auf die Sie dann zugreifen können. Wenn Sie zum Beispiel einen Endpunkt haben, der eine `$Id`-Variable erwartet, können Sie sie im Query-String angeben. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method 'GET' -Endpoint { Get-User -Id $Id } ``` {% endcode %} Der resultierende `Invoke-RestMethod`-Aufruf muss dann den Query-String-Parameter enthalten. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user?Id=123 ``` {% endcode %} Wenn Sie mehrere Query-String-Parameter verwenden, stellen Sie sicher, dass Ihre URL von Anführungszeichen umgeben ist, damit PowerShell sie richtig übersetzt. Ein Kaufmanns-Und (&) ohne Anführungszeichen führt sowohl in Windows PowerShell als auch in PowerShell 7 zu Problemen. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod "http://localhost:5000/user?Id=123&name=tim" ``` {% endcode %} ### 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](https://cwe.mitre.org/data/definitions/914.html). Erwägen Sie die Verwendung eines `param`-Blocks, um sicherzustellen, dass nur gültige Parameter an den Endpunkt übergeben werden. Unten finden Sie ein Beispiel für CWE-914. Fügen Sie einen `$IsChallengePassed`-Query-String-Parameter hinzu, um die Challenge zu umgehen. {% 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 %} Um dieses spezielle Problem zu vermeiden, können Sie einen `param`-Block verwenden. {% 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 Anfrage-Header sind in APIs über die Variable `$Headers` verfügbar. Die Variable ist eine Hashtable. Um auf einen Header zuzugreifen, verwenden Sie die folgende Syntax: {% code collapsedlinecount="10" %} ```powershell $Headers['Content-Type'] ``` {% endcode %} ## Cookies Anfrage-Cookies sind in APIs über die Variable `$Cookies` verfügbar. Die Variable ist eine Hashtable. Um auf ein Cookie zuzugreifen, verwenden Sie die folgende Syntax: {% code collapsedlinecount="10" %} ```powershell $Cookies['Request-Cookie'] ``` {% endcode %} Senden Sie Anfrage-Cookies mit dem Cmdlet `New-PSUApiResponse` zurück. Verwenden Sie den Parameter `-Cookies` mit einer bereitgestellten Hashtable. {% code collapsedlinecount="10" %} ```powershell New-PSUApiResponse -StatusCode 200 -Cookies @{ ResponseCookie = '123' } ``` {% endcode %} ## 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. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method Post -Endpoint { $User = ConvertFrom-Json $Body New-User $User } ``` {% endcode %} Um den obigen Endpunkt aufzurufen, geben Sie den Body von `Invoke-RestMethod` an. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body "{'username': 'adam'}" ``` {% endcode %} ## Live-Protokoll Sie können die Live-Protokollinformationen für jeden Endpunkt anzeigen, indem Sie auf die Registerkarte Protokoll 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. ## Testen Sie können die Registerkarte Test im Endpunkt-Editor verwenden, um Ihre APIs zu testen. Mit diesem Test-Tool können Sie Header, den Query-String und den Body anpassen. Sie können außerdem die Authentifizierung und Autorisierung für den Test anpassen. Wenn Sie die Registerkarte Test verwenden, 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. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod -Uri 'http://localhost:5000/test-api?Page=1' -Headers @{'X-Custom-Header' = 'Value';} -Method 'POST' ``` {% endcode %} Zusätzlich werden im Tester durchgeführte Tests 30 Tage lang gespeichert, um erneute Tests zu ermöglichen, ohne alle Eigenschaften neu konfigurieren zu müssen. Ein Klick auf die Schaltfläche Anwenden richtet das Test-Tool mit denselben Eigenschaften ein. ## Formulardaten Sie können Daten als Formulardaten an einen Endpunkt übergeben. Formulardaten werden als Parameter an Ihren Endpunkt übergeben. {% 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 %} Sie können dann eine Hashtable mit Invoke-RestMethod verwenden, um Formulardaten zu übergeben. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body @{ UserName = "adriscoll" FirstName = "Adam" LastName = "Driscoll" } ``` {% endcode %} ## JSON-Daten Sie können JSON-Daten an einen Endpunkt übergeben, und sie werden automatisch an einen param-Block gebunden. {% 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 %} Sie können dann JSON-Daten an den Endpunkt senden. {% 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 %} ## Param-Block Sie können innerhalb Ihres Skripts einen `param`-Block verwenden, um erforderliche 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` erforderlich und der Parameter `$Role` hat den Standardwert Default. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user/:name' -Endpoint { param([Parameter(Mandatory)$Name, $Role = "Default") } ``` {% endcode %} Wenn Sie den `param`-Block mit Routenparametern wie im obigen Beispiel verwenden, müssen Sie die Routenvariable in Ihrem Parameter angeben. Wenn sie nicht angegeben ist, haben Sie keinen Zugriff auf diesen Wert. Zum Beispiel ist die folgende Variable `$Name` immer `$null`. Der Endpunkt gibt immer false zurück. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user/:name' -Endpoint { param($Role = "Default") $Name -eq 'Adam' } ``` {% endcode %} Wenn Sie das Attribut `CmdletBinding` oder `Parameter` innerhalb Ihres param-Blocks verwenden, erzwingt der Endpunkt strikt, welche Parameter im Endpunkt zulässig sind. Zum Beispiel erzwingt das Folgende, dass der Parameter name angegeben wird. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Endpoint { param([Parameter(Mandatory)$Name) } ``` {% endcode %} Allerdings können Sie dem Endpunkt keine zusätzlichen Parameter übergeben. Das Folgende führt zu einem Fehler. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body (@{ Name = "adriscoll" DisplayName = 'Adam' } | ConvertTo-Json) -ContentType 'application/json' ``` {% endcode %} Wenn Sie Ihren Endpunkt so ändern, dass das Attribut `Parameter` nicht verwendet wird, können Sie beliebig viele Parameter übergeben, und sie werden als Variablen und nicht als Parameter des Endpunkts gebunden. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Endpoint { param($Name) } ``` {% endcode %} ### Parametersätze für Methoden Sie können Parametersätze mithilfe von Methodenparametern definieren. Standardmäßig prüft PowerShell Universal den param-Block, um festzustellen, ob diese HTTP-Methodennamen `Get`, `Put`, `Post`, `Delete` oder andere angegeben sind, und schließt sie automatisch ein. Wenn Endpunkte mehrere Methoden akzeptieren, kann es unter Umständen nicht anhand der bereitgestellten Daten bestimmen, welcher Parametersatz aufgerufen werden soll. Im folgenden Beispiel akzeptieren sowohl Get als auch Post den Parameter name. Es gibt außerdem keine Möglichkeit, 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 berücksichtigt diesen Parameter, um sicherzustellen, dass der richtige Parametersatz aufgerufen wird. {% 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 %} ## Daten zurückgeben Von Endpunkten zurückgegebene Daten werden als JSON-Daten angenommen. 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. {% 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" %} Der Inhaltstyp `The multipart/form-data`wird für das Hochladen von Dateien an APIs nicht unterstützt. {% endhint %} Sie können die Datei auch in einem Verzeichnis speichern. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Post -Endpoint { [IO.File]::WriteAllBytes("tempfile.dat", $Data) } ``` {% endcode %} ### Dateien herunterladen Sie können Dateien mit dem Cmdlet `New-PSUApiResponse` übertragen. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/image' -Endpoint { $ImageData = [IO.File]::ReadAllBytes("image.jpeg") New-PSUApiResponse -ContentType 'image/jpg' -Data $ImageData } ``` {% endcode %} ## Benutzerdefinierte Antworten zurückgeben Sie können benutzerdefinierte Antworten von Endpunkten zurückgeben, indem Sie das Cmdlet `New-PSUApiResponse` in Ihrem Endpunkt verwenden. Mit diesem Cmdlet können Sie den Statuscode, den Inhaltstyp und sogar die byte\[]-Daten für den zurückzugebenden Inhalt angeben. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Get -Endpoint { New-PSUApiResponse -StatusCode 410 } ``` {% endcode %} Sie können auch benutzerdefinierte Body-Daten mit dem Parameter `-Body` von `New-PSUApiResponse` zurückgeben. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Get -Endpoint { New-PSUApiResponse -Body "Not what you're looking for." -StatusCode 404 } ``` {% endcode %} Der Aufruf der REST-Methode gibt den benutzerdefinierten Fehlercode zurück. {% code collapsedlinecount="10" %} ```powershell PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:8080/file Invoke-RestMethod: Not what you're looking for. ``` {% endcode %} Sie können den Inhaltstyp der zurückgegebenen Daten mit dem Parameter `-ContentType` steuern. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Get -Endpoint { New-PSUApiResponse -Body "12" -ContentType 'text/xml' } ``` {% endcode %} Sie können die Antwort-Header mit einer Hashtable von Werten steuern, die Sie an den Parameter `-Headers`übergeben. {% code collapsedlinecount="10" %} ```powershell New-PSUApiResponse -StatusCode 200 -Headers @{ "Referrer-Policy" = "no-referrer" } ``` {% endcode %} ## 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 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 ](/powershell-universal/de/config/environments.md)für Ihre API konfigurieren. Setzen Sie den Parameter `-PersistentRunspace`, um diese Funktion zu aktivieren. Dies wird im Skript `environments.ps1` konfiguriert. {% code collapsedlinecount="10" %} ```powershell New-PSUEnvironment -Name 'Env' -Path 'powershell.exe' -PersistentRunspace ``` {% endcode %} Sie können die API-Umgebung dann im Skript `settings.ps1` zuweisen. {% code collapsedlinecount="10" %} ```powershell Set-PSUSetting -ApiEnvironment 'Env' ``` {% endcode %} ## Timeout Standardmäßig haben Endpunkte kein Timeout. 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 Endpunkt-Inhalt Sie können den Pfad zu einer externen Endpunkt-Inhaltsdatei mit dem Parameter `-Path` von `New-PSUEndpoint` definieren. Der Pfad ist relativ zum Verzeichnis `.universal` im Repository. Der Inhalt der Datei `endpoints.ps1` ist dann dieser: {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url "/path" -Path "endpoint-path.ps1" ``` {% endcode %} ## C#-APIs C#-APIs werden als [Plugin](/powershell-universal/de/plattform/plugins/c-api-endpoints.md) 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 zur API-Anfrage enthält. {% 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 %} Sie haben außerdem Zugriff auf eine Eigenschaft `ServiceProvider`, mit der Sie auf Dienste innerhalb von PowerShell Universal zugreifen können. Diese sind derzeit nicht gut dokumentiert, aber unten finden Sie ein Beispiel für den Neustart eines Dashboards. {% code collapsedlinecount="10" %} ```csharp var dm = ServiceProvider.GetService(typeof(IDashboardManager)); var dashboard = dm.GetDashboard(1); dm.Restart(dashboard); ``` {% endcode %} Einige weitere nützliche Dienste sind: * IDatabase * IApiService * IConfigurationService * IJobService Sie können wählen, eine `ApiResponse` von Ihrem Endpunkt zurückzugeben. {% code collapsedlinecount="10" %} ```powershell return new ApiResponse { StatusCode = 404 }; ``` {% endcode %} Sobald Sie Ihre C#-Endpunktdatei definiert haben, können Sie sie hinzufügen, indem Sie `endpoints.ps1` bearbeiten. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url /csharp -Path endpoint.cs -Environment 'C#' ``` {% endcode %} Der PowerShell Universal-Dienst kompiliert und führt C#-Endpunkte automatisch aus. ## API * [New-PSUEndpoint](/powershell-universal/de/powershell-befehle/new-psuendpoint.md) * [Get-PSUEndpoint](/powershell-universal/de/powershell-befehle/get-psuendpoint.md) * [Remove-PSUEndpoint](/powershell-universal/de/powershell-befehle/remove-psuendpoint.md) * [New-PSUApiResponse](/powershell-universal/de/powershell-befehle/new-psuapiresponse.md) * [Set-PSUSetting](/powershell-universal/de/powershell-befehle/set-psusetting.md) ### Siehe auch * [Devolutions Academy – Zurücksetzen des Benutzerpassworts hinzufügen](https://academy.devolutions.net/student/activity/3546111-part-6-adding-reset-user-password) * [Devolutions Academy – Benutzerstatus/Benutzerdetails aktualisieren](https://academy.devolutions.net/student/activity/3546046-part-5-user-status-refresh-user-details) * [Devolutions Academy – Funktion zum Entsperren von Benutzern hinzufügen](https://academy.devolutions.net/student/activity/3546024-part-4-adding-user-unlock-feature) * [Devolutions Academy – Einen variablen Endpunkt erstellen](https://academy.devolutions.net/student/activity/3466016-creating-a-variable-endpoint) * [Devolutions Academy – Einen Query-String-Endpunkt erstellen](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/de/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.