> 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
Endpunkte werden durch ihre URI und HTTP-Methode definiert. Aufrufe an den Universal-Server, die Ihrem definierten API-Endpunkt und Ihrer Methode entsprechen, führen das API-Endpunktskript aus.
```powershell
New-PSUEndpoint -Url '/endpoint' -Method 'GET' -Endpoint {
"Hello, world!"
}
```
Um die obige Methode aufzurufen, können Sie `Invoke-RestMethod` verwenden.
```powershell
Invoke-RestMethod http://localhost:5000/endpoint
```
Beim Definieren von Endpunkten in der Management-API können Sie den `New-PSUEndpoint`-Aufruf ü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 Endpunkt-URLs, die mit internen PowerShell Universal Management API-URLs ü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`.
```powershell
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 er ausgeführt wird. Variablen müssen innerhalb derselben Endpunkt-URL eindeutig sein.
```powershell
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:
```powershell
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 zum Beispiel einen Endpunkt haben, der eine `$Id`-Variable erwartet, können Sie diese im Query-String angeben.
```powershell
New-PSUEndpoint -Url '/user' -Method 'GET' -Endpoint {
Get-User -Id $Id
}
```
Der resultierende `Invoke-RestMethod`-Aufruf muss dann den Query-String-Parameter enthalten.
```powershell
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 umsetzt. Ein Ampersand (&) ohne Anführungszeichen verursacht Probleme sowohl in Windows PowerShell als auch in PowerShell 7.
```powershell
Invoke-RestMethod "http://localhost:5000/user?Id=123&name=tim"
```
### Sicherheitsüberlegungen
Wenn Sie Eingaben über Query-String-Parameter akzeptieren, können Sie anfällig für [CWE-914: Improper Control of Dynamically-Identified Variables](https://cwe.mitre.org/data/definitions/914.html) sein. 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 ein, um die Challenge zu umgehen.
```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"
}
}
```
Um dieses spezielle Problem zu vermeiden, können Sie einen `param`-Block verwenden.
```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"
}
}
```
## 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:
```powershell
$Headers['Content-Type']
```
## 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:
```powershell
$Cookies['Request-Cookie']
```
Senden Sie Anfrage-Cookies mit dem Cmdlet `New-PSUApiResponse` zurück. Verwenden Sie den Parameter `-Cookies` mit einer bereitgestellten Hashtable.
```powershell
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.
```powershell
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.
```powershell
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 Protokoll klicken. Live-Protokolle enthalten URL, HTTP-Methode, Quell-IP-Adresse, PowerShell-Streams, Statuscode, zurückgegebenen Content-Type und HTTP-Content-Length.
Sie können mit Cmdlets wie `Write-Host` aus Ihren Endpunkten heraus in das Live-Protokoll schreiben.
Endpunkt-Live-Protokoll
## 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 auch die Authentifizierung und Autorisierung für den Test anpassen.
Registerkarte Endpunkt-Test
Bei Verwendung der Registerkarte Test führen Änderungen an den Werten des Tests zu einem aktualisierten Codeblock, den Sie dann innerhalb von PowerShell verwenden können. Klicken Sie auf die Registerkarte Code, um den Testcode anzuzeigen.
```powershell
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 Anwenden richtet das Test-Tool mit den gleichen Eigenschaften ein.
Testverlauf
## Formulardaten
Sie können Daten als Formulardaten an einen Endpunkt übergeben. Formulardaten werden als Parameter an Ihren Endpunkt übergeben.
```powershell
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 Hashtable mit Invoke-RestMethod verwenden, um Formulardaten zu übergeben.
```powershell
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.
```powershell
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.
```powershell
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.
```powershell
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 einbeziehen. Wenn sie nicht angegeben wird, haben Sie keinen Zugriff auf diesen Wert.
Zum Beispiel ist die folgende `$Name`-Variable immer `$null`. Der Endpunkt gibt immer false zurück.
```powershell
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 streng, welche Parameter in den Endpunkt zugelassen sind.
Zum Beispiel erzwingt das Folgende, dass der Parameter name angegeben wird.
```powershell
New-PSUEndpoint -Url '/user' -Endpoint {
param([Parameter(Mandatory)$Name)
}
```
Allerdings können Sie keine zusätzlichen Parameter für den Endpunkt angeben. Das Folgende verursacht einen Fehler.
```powershell
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 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.
```powershell
New-PSUEndpoint -Url '/user' -Endpoint {
param($Name)
}
```
### Methoden-Parametersätze
Sie können Parametersätze mithilfe von Methodenparametern definieren. Standardmäßig untersucht PowerShell Universal den Param-Block, um zu bestimmen, 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 möglicherweise nicht anhand der bereitgestellten Daten bestimmen, welcher Parametersatz aufgerufen werden soll. Im nachstehenden Beispiel 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` ein, die Teil ihres jeweiligen Parametersatzes sind. PowerShell Universal schließt diesen Parameter ein, um sicherzustellen, dass der richtige Parametersatz aufgerufen wird.
{% 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 %}
## 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 einen anderen Datentyp 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.
```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" %}
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.
```powershell
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.
```powershell
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 von Endpunkten zurückgeben, indem Sie das Cmdlet `New-PSUApiResponse` in Ihrem Endpunkt verwenden. Dieses Cmdlet erlaubt Ihnen, den Statuscode und den Content-Type festzulegen und sogar die byte\[]-Daten für den zurückzugebenden Inhalt anzugeben.
```powershell
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.
```powershell
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.
```powershell
PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:8080/file
Invoke-RestMethod: Not what you're looking for.
```
Sie können den Content-Type der zurückgegebenen Daten mit dem Parameter `-ContentType` steuern.
```powershell
New-PSUEndpoint -Url '/file' -Method Get -Endpoint {
New-PSUApiResponse -Body "12" -ContentType 'text/xml'
}
```
Sie können die Antwort-Header mit einer Hashtable von Werten steuern, die Sie an den Parameter `-Headers`übergeben.
```powershell
New-PSUApiResponse -StatusCode 200 -Headers @{
"Referrer-Policy" = "no-referrer"
}
```
## Persistente Runspaces
Persistente Runspaces erlauben Ihnen, den Runspace-Zustand 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.
```powershell
New-PSUEnvironment -Name 'Env' -Path 'powershell.exe' -PersistentRunspace
```
Sie können dann die API-Umgebung im Skript `settings.ps1` zuweisen.
```powershell
Set-PSUSetting -ApiEnvironment 'Env'
```
## Timeout
Standardmäßig läuft für Endpunkte kein Timeout 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` ist dann dieser:
```powershell
New-PSUEndpoint -Url "/path" -Path "endpoint-path.ps1"
```
## C#-APIs
C#-APIs werden als [Plugin](/powershell-universal/de/plattform/plugins.md#c-api-environment) 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.
```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;
}
```
Sie haben außerdem Zugriff auf eine `ServiceProvider`-Eigenschaft, die Ihnen den Zugriff auf Dienste innerhalb von PowerShell Universal erlaubt. Diese sind derzeit nicht gut dokumentiert, aber nachfolgend finden Sie ein Beispiel für den Neustart eines Dashboards.
```csharp
var dm = ServiceProvider.GetService(typeof(IDashboardManager));
var dashboard = dm.GetDashboard(1);
dm.Restart(dashboard);
```
Einige weitere nützliche Dienste sind:
* IDatabase
* IApiService
* IConfigurationService
* IJobService
Sie können wählen, eine `ApiResponse` von Ihrem Endpunkt zurückzugeben.
```powershell
return new ApiResponse {
StatusCode = 404
};
```
Sobald Sie Ihre C#-Endpunktdatei definiert haben, können Sie sie hinzufügen, indem Sie `endpoints.ps1` bearbeiten.
```powershell
New-PSUEndpoint -Url /csharp -Path endpoint.cs -Environment 'C#'
```
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)
---
# 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.