> 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/da/api/endpoints.md). # Slutpunkter Konfigurer API-slutpunkter i PowerShell Universal med New-PSUEndpoint, herunder URL-routing, headere, cookies, anmodningsbrødtekster, filuploads og brugerdefinerede svar. Slutpunkter defineres af deres URI og HTTP-metode. Kald til Universal-serveren, der matcher Deres definerede API-slutpunkt og metode, kører scriptet for API-slutpunktet. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/endpoint' -Method 'GET' -Endpoint { "Hello, world!" } ``` {% endcode %} For at kalde ovenstående metode kan De bruge `Invoke-RestMethod`. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/endpoint ``` {% endcode %} Når De definerer slutpunkter i administrations-API'en, kan De springe kaldet `New-PSUEndpoint` over, da admin console definerer det. Det eneste indhold, De skal angive i editoren, er det script, De ønsker at kalde. {% hint style="warning" %} Undgå at bruge slutpunkts-URL'er, der matcher interne URL'er for PowerShell Universal Management API, da dette forårsager uventet funktionsmåde. De kan se [OpenAPI-dokumentationen](/powershell-universal/da/api/openapi.md#management-api-documentation) for [Management API](/powershell-universal/da/config/management-api.md) for at kontrollere, at ingen af URL'erne matcher. {% endhint %} ## HTTP-metoder Slutpunkter kan have en eller flere HTTP-metoder defineret. Brug den indbyggede variabel `$Method` til at bestemme, hvilken metode et slutpunkt bruger. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method @('GET', 'POST') -Endpoint { if ($Method -eq 'GET') { Get-User } else { New-User } } ``` {% endcode %} ## Variabel URL URL'er kan indeholde variable segmenter. De kan angive et variabelt segment ved hjælp af et kolon (`:`). Følgende URL ville for eksempel angive en variabel for brugerens id. Variablen `$Id` defineres i slutpunktet, når det køres. Variabler skal være unikke i den samme slutpunkts-URL. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user/:id' -Method 'GET' -Endpoint { Get-User -Id $Id } ``` {% endcode %} For at kalde denne API og angive id'et skal De gøre følgende: {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user/123 ``` {% endcode %} ## Forespørgselsstrengparametre Query-strengparametre overføres automatisk til slutpunkter som variabler, som De derefter kan få adgang til. Hvis De f.eks. har et slutpunkt, der forventer variablen `$Id`, kan De angive den i query-strengen. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method 'GET' -Endpoint { Get-User -Id $Id } ``` {% endcode %} Det resulterende `Invoke-RestMethod`-kald skal derefter indeholde forespørgselsstrengparameteren. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user?Id=123 ``` {% endcode %} Når De bruger flere parametre i query-strengen, skal De sikre, at Deres URL er omgivet af anførselstegn, så PowerShell oversætter den korrekt. Hvis De medtager et og-tegn (&) uden anførselstegn, opstår der problemer i både Windows PowerShell og PowerShell 7. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod "http://localhost:5000/user?Id=123&name=tim" ``` {% endcode %} ### Sikkerhedsovervejelser Når De accepterer input via parametre i forespørgselsstrengen, kan De være sårbar over for [CWE-914: Improper Control of Dynamically-Identified Variables](https://cwe.mitre.org/data/definitions/914.html). Overvej at bruge en `param`-blok for at sikre, at kun gyldige parametre leveres til slutpunktet. Nedenfor er et eksempel på CWE-914. Medtag forespørgselsstrengparameteren `$IsChallengePassed` for at omgå udfordringen. {% 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 %} For at undgå dette bestemte problem kan De bruge en `param`-blok. {% 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 %} ## Headere Anmodningsheadere er tilgængelige i API'er via variablen `$Headers`. Variablen er en hashtable. Brug følgende syntaks for at få adgang til en header: {% code collapsedlinecount="10" %} ```powershell $Headers['Content-Type'] ``` {% endcode %} ## Cookies Anmodningscookies er tilgængelige i API'er via variablen `$Cookies`. Variablen er en hashtable. Brug følgende syntaks for at få adgang til en cookie: {% code collapsedlinecount="10" %} ```powershell $Cookies['Request-Cookie'] ``` {% endcode %} Send anmodningscookies tilbage med cmdletten `New-PSUApiResponse`. Brug parameteren `-Cookies` med en angivet hashtable. {% code collapsedlinecount="10" %} ```powershell New-PSUApiResponse -StatusCode 200 -Cookies @{ ResponseCookie = '123' } ``` {% endcode %} ## Brødtekst For at få adgang til anmodningsbrødteksten skal De blot bruge variablen `$Body`. Universal-variablen `$Body` vil være en streng. Hvis De forventer JSON, bør De bruge `ConvertFrom-Json`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method Post -Endpoint { $User = ConvertFrom-Json $Body New-User $User } ``` {% endcode %} For at kalde ovenstående slutpunkt skal De angive brødteksten for `Invoke-RestMethod`. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body "{'username': 'adam'}" ``` {% endcode %} ## Live Log De kan få vist live-logoplysningerne for ethvert slutpunkt ved at klikke på fanen log. Live-logge omfatter URL, HTTP-metode, kilde-IP-adresse, PowerShell-strømme, statuskode, returneret Content Type og HTTP-indholdslængde. De kan skrive til live-loggen inde fra Deres slutpunkter med cmdlets som `Write-Host`. ## Test De kan bruge fanen Test i Endpoint-editoren til at teste Deres API'er. Med dette Test-værktøj kan De justere headere, query-strengen og brødteksten. De kan også justere Authentication og Authorization for testen. Når De bruger fanen test, medfører alle ændringer af testens værdier en opdateret Code-blok, som De derefter kan bruge i PowerShell. Klik på fanen Code for at se testkoden. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod -Uri 'http://localhost:5000/test-api?Page=1' -Headers @{'X-Custom-Header' = 'Value';} -Method 'POST' ``` {% endcode %} Desuden gemmes test, der udføres i testeren, i 30 dage, så der kan testes igen uden at skulle konfigurere alle egenskaberne på ny. Når De klikker på knappen Apply, opsættes Test-værktøjet med de samme egenskaber. ## Formulardata De kan sende data til et slutpunkt som formulardata. Formulardata overføres til Deres slutpunkt som parametre. {% 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 %} De kan derefter bruge en hashtable med Invoke-RestMethod til at overføre formulardata. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body @{ UserName = "adriscoll" FirstName = "Adam" LastName = "Driscoll" } ``` {% endcode %} ## JSON-data De kan sende JSON-data til et slutpunkt, og de bindes automatisk til en param-blok. {% 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 %} De kan derefter sende JSON-data til slutpunktet. {% 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-blok De kan bruge en `param`-blok i Deres script til at gennemtvinge obligatoriske parametre og angive standardværdier for valgfrie parametre, f.eks. parametre i query-strengen. Variabler som `$Body`, `$Headers` og `$User` leveres automatisk. I nedenstående eksempel er parameteren `$Name` obligatorisk, og parameteren `$Role` har standardværdien Default. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user/:name' -Endpoint { param([Parameter(Mandatory)$Name, $Role = "Default") } ``` {% endcode %} Når De bruger `param`-blokken med ruteparametre som i ovenstående eksempel, skal De medtage rutevariablen i Deres parameter. Hvis den ikke er angivet, vil De ikke have adgang til den værdi. Følgende variabel `$Name` er for eksempel altid `$null`. Slutpunktet returnerer altid false. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user/:name' -Endpoint { param($Role = "Default") $Name -eq 'Adam' } ``` {% endcode %} Hvis De bruger attributten `CmdletBinding` eller `Parameter` i Deres param-blok, håndhæver slutpunktet strengt, hvilke parametre der er tilladt i slutpunktet. Følgende gennemtvinger for eksempel, at parameteren name er angivet. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Endpoint { param([Parameter(Mandatory)$Name) } ``` {% endcode %} Når det er sagt, kan De ikke angive yderligere parametre til slutpunktet. Hvis De gør følgende, opstår der en fejl. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body (@{ Name = "adriscoll" DisplayName = 'Adam' } | ConvertTo-Json) -ContentType 'application/json' ``` {% endcode %} Hvis De ændrer Deres slutpunkt for at undgå at bruge attributten `Parameter`, kan De overføre et vilkårligt antal params, og de bindes som variabler og ikke som parametre til slutpunktet. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Endpoint { param($Name) } ``` {% endcode %} ### Metodeparametersæt De kan definere parametersæt ved hjælp af metodeparametre. Som standard undersøger PowerShell Universal param-blokken for at afgøre, om disse `Get`, `Put`, `Post`, `Delete` eller andre HTTP-metodenavne er angivet, og medtager dem automatisk. Når slutpunkter accepterer flere metoder, kan PowerShell Universal muligvis ikke afgøre, hvilket parametersæt der skal kaldes, ud fra de angivne data. I eksemplet nedenfor accepterer både Get og Post name-parameteren. Der er heller ingen måde at kalde Post på uden et navn, så valideringen kan mislykkes. For at afhjælpe dette skal De medtage parametrene `Post` og `Get`, som er en del af deres respektive parametersæt. PowerShell Universal medtager denne parameter for at sikre, at det korrekte parametersæt kaldes. {% 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 %} ## Returnering af data Data, der returneres fra slutpunkter, antages at være JSON-data. Hvis De returnerer et objekt fra slutpunktets scriptblok, serialiseres det automatisk til JSON. Hvis De vil returnere en anden type data, kan De returnere en streng, der er formateret, som De vælger. ## Behandling af filer ### Upload af filer De kan behandle uploadede filer ved at bruge parameteren `$Data` til at få adgang til byte-arrayet af data, der er uploadet til slutpunktet. {% 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" %} `The multipart/form-data`indholdstypen understøttes ikke til upload af filer til API'er. {% endhint %} De kan også gemme filen i et katalog. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Post -Endpoint { [IO.File]::WriteAllBytes("tempfile.dat", $Data) } ``` {% endcode %} ### Download af filer De kan sende filer ned ved hjælp af cmdletten `New-PSUApiResponse`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/image' -Endpoint { $ImageData = [IO.File]::ReadAllBytes("image.jpeg") New-PSUApiResponse -ContentType 'image/jpg' -Data $ImageData } ``` {% endcode %} ## Returnering af brugerdefinerede svar De kan returnere brugerdefinerede svar fra slutpunkter ved hjælp af cmdletten `New-PSUApiResponse` i Deres slutpunkt. Denne cmdlet giver Dem mulighed for at angive statuskoden, indholdstypen og endda angive byte\[]-dataene for det indhold, der skal returneres. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Get -Endpoint { New-PSUApiResponse -StatusCode 410 } ``` {% endcode %} De kan også returnere brugerdefinerede brødtekstdata med parameteren `-Body` i `New-PSUApiResponse`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Get -Endpoint { New-PSUApiResponse -Body "Not what you're looking for." -StatusCode 404 } ``` {% endcode %} Kald af REST-metoden returnerer den brugerdefinerede fejlkode. {% code collapsedlinecount="10" %} ```powershell PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:8080/file Invoke-RestMethod: Not what you're looking for. ``` {% endcode %} De kan styre indholdstypen for de returnerede data med parameteren `-ContentType`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Get -Endpoint { New-PSUApiResponse -Body "12" -ContentType 'text/xml' } ``` {% endcode %} De kan styre svarheaderne med en hashtable med værdier, som De sender til `-Headers`parameteren. {% code collapsedlinecount="10" %} ```powershell New-PSUApiResponse -StatusCode 200 -Headers @{ "Referrer-Policy" = "no-referrer" } ``` {% endcode %} ## Vedvarende runspaces Vedvarende runspaces giver Dem mulighed for at bevare runspace-tilstanden mellem API-kald. Det er vigtigt for brugere, der udfører en form for initialisering i deres slutpunkter, som de ikke ønsker at udføre ved efterfølgende API-kald. Som standard nulstilles runspaces efter hver kørsel. Dette fjerner variabler, moduler og funktioner, der er defineret under kørslen af API'en. For at aktivere vedvarende runspaces skal De konfigurere et [miljø ](/powershell-universal/da/config/environments.md)til Deres API. Angiv parameteren `-PersistentRunspace` for at aktivere denne funktion. Dette konfigureres i scriptet `environments.ps1`. {% code collapsedlinecount="10" %} ```powershell New-PSUEnvironment -Name 'Env' -Path 'powershell.exe' -PersistentRunspace ``` {% endcode %} De kan derefter tildele API-miljøet i scriptet `settings.ps1`. {% code collapsedlinecount="10" %} ```powershell Set-PSUSetting -ApiEnvironment 'Env' ``` {% endcode %} ## Timeout Som standard får slutpunkter ikke timeout. For at angive en timeout for Deres slutpunkter kan De bruge parameteren `-Timeout` for `New-PSUEndpoint`. Timeouten angives i antal sekunder. ## Eksternt slutpunktsindhold De kan definere stien til en ekstern indholdsfil for et slutpunkt med parameteren `-Path` på `New-PSUEndpoint`. Stien er relativ til kataloget `.universal` i lageret. Indholdet af filen `endpoints.ps1` er derefter dette: {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url "/path" -Path "endpoint-path.ps1" ``` {% endcode %} ## C# API'er C#-API'er aktiveres som et [plugin](/powershell-universal/da/platform/plugins/c-api-endpoints.md). Der findes ingen brugergrænseflade til oprettelse af et C#-API, så De skal gøre det ved hjælp af konfigurationsfiler. Opret først en `.cs`-fil, der kører Deres API. De vil have adgang til en `request`-parameter, der indeholder alle data om API-anmodningen. {% 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 %} De har også adgang til egenskaben `ServiceProvider`, der giver Dem adgang til tjenester i PowerShell Universal. Disse er i øjeblikket ikke veldokumenterede, men nedenfor er et eksempel på genstart af et dashboard. {% code collapsedlinecount="10" %} ```csharp var dm = ServiceProvider.GetService(typeof(IDashboardManager)); var dashboard = dm.GetDashboard(1); dm.Restart(dashboard); ``` {% endcode %} Nogle andre nyttige tjenester omfatter: * IDatabase * IApiService * IConfigurationService * IJobService De kan vælge at returnere et `ApiResponse` fra Deres slutpunkt. {% code collapsedlinecount="10" %} ```powershell return new ApiResponse { StatusCode = 404 }; ``` {% endcode %} Når De har defineret Deres C#-slutpunktsfil, kan De tilføje den ved at redigere `endpoints.ps1`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url /csharp -Path endpoint.cs -Environment 'C#' ``` {% endcode %} PowerShell Universal-tjenesten kompilerer og kører C#-slutpunkter automatisk. ## API * [New-PSUEndpoint](/powershell-universal/da/powershell-kommandoer/new-psuendpoint.md) * [Get-PSUEndpoint](/powershell-universal/da/powershell-kommandoer/get-psuendpoint.md) * [Remove-PSUEndpoint](/powershell-universal/da/powershell-kommandoer/remove-psuendpoint.md) * [New-PSUApiResponse](/powershell-universal/da/powershell-kommandoer/new-psuapiresponse.md) * [Set-PSUSetting](/powershell-universal/da/powershell-kommandoer/set-psusetting.md) ### Se også * [Devolutions Academy – Tilføjelse af nulstilling af brugeradgangskode](https://academy.devolutions.net/student/activity/3546111-part-6-adding-reset-user-password) * [Devolutions Academy – Brugerstatus/opdater brugeroplysninger](https://academy.devolutions.net/student/activity/3546046-part-5-user-status-refresh-user-details) * [Devolutions Academy – Tilføjelse af funktion til oplåsning af bruger](https://academy.devolutions.net/student/activity/3546024-part-4-adding-user-unlock-feature) * [Devolutions Academy – Oprettelse af et variabelslutpunkt](https://academy.devolutions.net/student/activity/3466016-creating-a-variable-endpoint) * [Devolutions Academy – Oprettelse af et slutpunkt med forespørgselsstreng](https://academy.devolutions.net/student/activity/3466018-creating-a-query-string-endpoint) * [Devolutions Academy – Oprettelse af et slutpunkt, der accepterer en brødtekst](https://academy.devolutions.net/student/activity/3466020-creating-an-endpoint-that-accepts-a-body) * [Devolutions Academy – Forskellige rutemetoder](https://academy.devolutions.net/student/activity/3466022-different-route-methods) --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.devolutions.net/powershell-universal/da/api/endpoints.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.