> 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/fr/api/endpoints.md). # Points de terminaison Les points de terminaison sont définis par leur URI et leur méthode HTTP. Les appels effectués vers le serveur Universal qui correspondent à votre point de terminaison API et à votre méthode définis exécutent le script du point de terminaison API. ```powershell New-PSUEndpoint -Url '/endpoint' -Method 'GET' -Endpoint { "Hello, world!" } ``` Pour invoquer la méthode ci-dessus, vous pouvez utiliser `Invoke-RestMethod`. ```powershell Invoke-RestMethod http://localhost:5000/endpoint ``` Lorsque vous définissez des points de terminaison dans l'API de gestion, vous pouvez omettre l'appel à `New-PSUEndpoint`, car la console d'administration le définit. ![API Properties](/files/nS5HMFyTKECGrzsC8g7u) Le seul contenu que vous devez fournir dans l'éditeur est le script que vous souhaitez appeler. ![API Content](/files/mA1ZwWnR3BN17eJnBK6z) {% hint style="warning" %} Évitez d'utiliser des URL de points de terminaison qui correspondent aux URL internes de l'API de gestion de PowerShell Universal, car cela entraîne un comportement inattendu. Vous pouvez consulter la [documentation OpenAPI](/powershell-universal/fr/api/openapi.md#management-api-documentation) de l'[API de gestion](/powershell-universal/fr/config/management-api.md) pour vérifier qu'aucune des URL ne correspond. {% endhint %} ## Méthodes HTTP Les points de terminaison peuvent avoir une ou plusieurs méthodes HTTP définies. Pour déterminer quelle méthode est utilisée par un point de terminaison, utilisez la variable intégrée `$Method`. ```powershell New-PSUEndpoint -Url '/user' -Method @('GET', 'POST') -Endpoint { if ($Method -eq 'GET') { Get-User } else { New-User } } ``` ## URL variable Les URL peuvent contenir des segments variables. Vous pouvez indiquer un segment variable en utilisant un deux-points (`:`). Par exemple, l'URL suivante fournit une variable pour l'identifiant de l'utilisateur. La variable `$Id` sera définie dans le point de terminaison lors de son exécution. Les variables doivent être uniques dans la même URL de point de terminaison. ```powershell New-PSUEndpoint -Url '/user/:id' -Method 'GET' -Endpoint { Get-User -Id $Id } ``` Pour appeler cette API en spécifiant l'identifiant, procédez comme suit : ```powershell Invoke-RestMethod http://localhost:5000/user/123 ``` ## Paramètres de chaîne de requête Les paramètres de chaîne de requête sont automatiquement transmis aux points de terminaison sous forme de variables auxquelles vous pouvez ensuite accéder. Par exemple, si vous avez un point de terminaison qui attend une variable `$Id`, vous pouvez la fournir dans la chaîne de requête. ```powershell New-PSUEndpoint -Url '/user' -Method 'GET' -Endpoint { Get-User -Id $Id } ``` L'appel `Invoke-RestMethod` résultant doit alors inclure le paramètre de chaîne de requête. ```powershell Invoke-RestMethod http://localhost:5000/user?Id=123 ``` Lorsque vous utilisez plusieurs paramètres de chaîne de requête, assurez-vous que votre URL est entourée de guillemets afin que PowerShell la traduise correctement. L'inclusion d'une esperluette (&) sans guillemets entraîne des problèmes dans Windows PowerShell et PowerShell 7. ```powershell Invoke-RestMethod "http://localhost:5000/user?Id=123&name=tim" ``` ### Considérations de sécurité Lorsque vous acceptez des entrées via des paramètres de chaîne de requête, vous pouvez être vulnérable à [CWE-914: Improper Control of Dynamically-Identified Variables](https://cwe.mitre.org/data/definitions/914.html). Envisagez d'utiliser un bloc `param` pour vous assurer que seuls des paramètres valides sont transmis au point de terminaison. Voici un exemple de CWE-914. Incluez un paramètre de chaîne de requête `$IsChallengePassed` pour contourner le défi. ```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" } } ``` Pour éviter ce problème particulier, vous pouvez utiliser un bloc `param`. ```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" } } ``` ## En-têtes Les en-têtes de requête sont disponibles dans les API via la variable `$Headers`. La variable est une table de hachage. Pour accéder à un en-tête, utilisez la syntaxe suivante : ```powershell $Headers['Content-Type'] ``` ## Cookies Les cookies de requête sont disponibles dans les API via la variable `$Cookies`. La variable est une table de hachage. Pour accéder à un cookie, utilisez la syntaxe suivante : ```powershell $Cookies['Request-Cookie'] ``` Renvoyez les cookies de requête avec la cmdlet `New-PSUApiResponse`. Utilisez le paramètre `-Cookies` avec une table de hachage fournie. ```powershell New-PSUApiResponse -StatusCode 200 -Cookies @{ ResponseCookie = '123' } ``` ## Corps Pour accéder au corps d'une requête, il vous suffit d'accéder à la variable `$Body`. La variable `$Body` de Universal est une chaîne. Si vous attendez du JSON, vous devez utiliser `ConvertFrom-Json`. ```powershell New-PSUEndpoint -Url '/user' -Method Post -Endpoint { $User = ConvertFrom-Json $Body New-User $User } ``` Pour appeler le point de terminaison ci-dessus, spécifiez le corps de `Invoke-RestMethod`. ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body "{'username': 'adam'}" ``` ## Journal en direct Vous pouvez consulter les informations du journal en direct pour n'importe quel point de terminaison en cliquant sur l'onglet des journaux. Les journaux en direct incluent l'URL, la méthode HTTP, l'adresse IP source, les flux PowerShell, le code de statut, le type de contenu retourné et la longueur du contenu HTTP. Vous pouvez écrire dans le journal en direct depuis vos points de terminaison avec des cmdlets telles que `Write-Host`.

Journal en direct du point de terminaison

## Test Vous pouvez utiliser l'onglet Test dans l'éditeur de point de terminaison pour tester vos API. Grâce à cet outil de test, vous pouvez ajuster les en-têtes, la chaîne de requête et le corps. Vous pouvez également ajuster l'authentification et l'autorisation pour le test.

Onglet Test du point de terminaison

Lorsque vous utilisez l'onglet Test, toute modification des valeurs du test entraîne la mise à jour d'un bloc de code que vous pouvez ensuite utiliser dans PowerShell. Cliquez sur l'onglet Code pour afficher le code de test. ```powershell Invoke-RestMethod -Uri 'http://localhost:5000/test-api?Page=1' -Headers @{'X-Custom-Header' = 'Value';} -Method 'POST' ``` De plus, les tests effectués dans l'outil de test sont conservés pendant 30 jours pour permettre des re-tests sans avoir à reconfigurer toutes les propriétés. Cliquer sur le bouton Appliquer configure l'outil de test avec les mêmes propriétés.

Historique des tests

## Données de formulaire Vous pouvez transmettre des données à un point de terminaison sous forme de données de formulaire. Les données de formulaire sont transmises à votre point de terminaison sous forme de paramètres. ```powershell New-PSUEndpoint -Url '/user' -Method Post -Endpoint { param([Parameter(Mandatory)]$userName, $FirstName, $LastName) New-User $UserName -FirstName $FirstName -LastName $LastName } ``` Vous pouvez ensuite utiliser une table de hachage avec `Invoke-RestMethod` pour transmettre des données de formulaire. ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body @{ UserName = "adriscoll" FirstName = "Adam" LastName = "Driscoll" } ``` ## Données JSON Vous pouvez transmettre des données JSON à un point de terminaison et celles-ci seront automatiquement liées à un bloc `param`. ```powershell New-PSUEndpoint -Url '/user' -Method Post -Endpoint { param([Parameter(Mandatory)]$userName, $FirstName, $LastName) New-User $UserName -FirstName $FirstName -LastName $LastName } ``` Vous pouvez ensuite envoyer des données JSON au point de terminaison. ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body (@{ UserName = "adriscoll" FirstName = "Adam" LastName = "Driscoll" } | ConvertTo-Json) -ContentType 'application/json' ``` ## Bloc Param Vous pouvez utiliser un bloc `param` dans votre script pour imposer des paramètres obligatoires et fournir des valeurs par défaut pour les paramètres facultatifs tels que les paramètres de chaîne de requête. Des variables telles que `$Body`, `$Headers` et `$User` sont fournies automatiquement. Dans l'exemple ci-dessous, le paramètre `$Name` est obligatoire et le paramètre `$Role` a une valeur par défaut de Default. ```powershell New-PSUEndpoint -Url '/user/:name' -Endpoint { param([Parameter(Mandatory)$Name, $Role = "Default") } ``` Lorsque vous utilisez le bloc `param` avec des paramètres de route comme dans l'exemple ci-dessus, vous devez inclure la variable de route dans votre paramètre. Si elle n'est pas spécifiée, vous n'aurez pas accès à cette valeur. Par exemple, la variable `$Name` suivante est toujours `$null`. Le point de terminaison retourne toujours false. ```powershell New-PSUEndpoint -Url '/user/:name' -Endpoint { param($Role = "Default") $Name -eq 'Adam' } ``` Si vous utilisez l'attribut `CmdletBinding` ou `Parameter` dans votre bloc `param`, le point de terminaison appliquera strictement les paramètres autorisés dans le point de terminaison. Par exemple, ce qui suit impose que le paramètre name soit spécifié. ```powershell New-PSUEndpoint -Url '/user' -Endpoint { param([Parameter(Mandatory)$Name) } ``` Cela dit, vous ne pouvez pas spécifier de paramètres supplémentaires au point de terminaison. Procéder comme suit entraîne une erreur. ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body (@{ Name = "adriscoll" DisplayName = 'Adam' } | ConvertTo-Json) -ContentType 'application/json' ``` Si vous modifiez votre point de terminaison pour éviter d'utiliser l'attribut `Parameter`, vous pouvez transmettre n'importe quel nombre de paramètres et ceux-ci seront liés en tant que variables et non en tant que paramètres du point de terminaison. ```powershell New-PSUEndpoint -Url '/user' -Endpoint { param($Name) } ``` ### Jeux de paramètres de méthode Vous pouvez définir des jeux de paramètres à l'aide de paramètres de méthode. Par défaut, PowerShell Universal inspecte le bloc `param` pour déterminer si les noms de méthodes HTTP `Get`, `Put`, `Post`, `Delete` ou autres sont spécifiés et les inclut automatiquement. Lorsque les points de terminaison acceptent plusieurs méthodes, il peut ne pas être en mesure de déterminer quel jeu de paramètres appeler en fonction des données fournies. Dans l'exemple ci-dessous, Get et Post acceptent tous les deux le paramètre name. Il n'y a également aucun moyen d'appeler le Post sans un name, ce qui pourrait entraîner un échec de validation. Pour remédier à cela, incluez les paramètres `Post` et `Get` qui font partie de leur jeu de paramètres respectif. PowerShell Universal inclura ce paramètre pour s'assurer que le jeu de paramètres approprié est appelé. {% 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 %} ## Retour de données Les données retournées par les points de terminaison sont supposées être des données JSON. Si vous retournez un objet depuis le bloc de script du point de terminaison, il est automatiquement sérialisé en JSON. Si vous souhaitez retourner un autre type de données, vous pouvez retourner une chaîne formatée selon votre choix. ## Traitement de fichiers ### Téléversement de fichiers Vous pouvez traiter les fichiers téléversés en utilisant le paramètre `$Data` pour accéder au tableau d'octets de données téléversées vers le point de terminaison. ```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" %} Le type de contenu `multipart/form-data` n'est pas pris en charge pour le téléversement de fichiers vers les API. {% endhint %} Vous pouvez également enregistrer le fichier dans un répertoire. ```powershell New-PSUEndpoint -Url '/file' -Method Post -Endpoint { [IO.File]::WriteAllBytes("tempfile.dat", $Data) } ``` ### Téléchargement de fichiers Vous pouvez envoyer des fichiers en utilisant la cmdlet `New-PSUApiResponse`. ```powershell New-PSUEndpoint -Url '/image' -Endpoint { $ImageData = [IO.File]::ReadAllBytes("image.jpeg") New-PSUApiResponse -ContentType 'image/jpg' -Data $ImageData } ``` ## Retour de réponses personnalisées Vous pouvez retourner des réponses personnalisées depuis des points de terminaison en utilisant la cmdlet `New-PSUApiResponse` dans votre point de terminaison. Cette cmdlet vous permet de définir le code de statut, le type de contenu et même de spécifier les données byte\[] pour le contenu à retourner. ```powershell New-PSUEndpoint -Url '/file' -Method Get -Endpoint { New-PSUApiResponse -StatusCode 410 } ``` Vous pouvez également retourner des données de corps personnalisées avec le paramètre `-Body` de `New-PSUApiResponse`. ```powershell New-PSUEndpoint -Url '/file' -Method Get -Endpoint { New-PSUApiResponse -Body "Not what you're looking for." -StatusCode 404 } ``` L'invocation de la méthode REST retourne le code d'erreur personnalisé. ```powershell PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:8080/file Invoke-RestMethod: Not what you're looking for. ``` Vous pouvez contrôler le type de contenu des données retournées avec le paramètre `-ContentType`. ```powershell New-PSUEndpoint -Url '/file' -Method Get -Endpoint { New-PSUApiResponse -Body "12" -ContentType 'text/xml' } ``` Vous pouvez contrôler les en-têtes de réponse avec une table de hachage de valeurs que vous transmettez au paramètre `-Headers`. ```powershell New-PSUApiResponse -StatusCode 200 -Headers @{ "Referrer-Policy" = "no-referrer" } ``` ## Runspaces persistants Les runspaces persistants vous permettent de maintenir l'état du runspace entre les appels API. Ceci est important pour les utilisateurs qui effectuent une sorte d'initialisation dans leurs points de terminaison et qu'ils ne souhaitent pas exécuter lors des appels API suivants. Par défaut, les runspaces sont réinitialisés après chaque exécution. Cela supprime les variables, les modules et les fonctions définis lors de l'exécution de l'API. Pour activer les runspaces persistants, vous devrez configurer un [environnement](/powershell-universal/fr/config/environments.md) pour votre API. Définissez le paramètre `-PersistentRunspace` pour activer cette fonctionnalité. Cela est configuré dans le script `environments.ps1`. ```powershell New-PSUEnvironment -Name 'Env' -Path 'powershell.exe' -PersistentRunspace ``` Vous pouvez ensuite assigner l'environnement API dans le script `settings.ps1`. ```powershell Set-PSUSetting -ApiEnvironment 'Env' ``` ## Délai d'expiration Par défaut, les points de terminaison n'expirent pas. Pour définir un délai d'expiration pour vos points de terminaison, vous pouvez utiliser le paramètre `-Timeout` de `New-PSUEndpoint`. Le délai d'expiration est défini en nombre de secondes. ## Contenu de point de terminaison externe Vous pouvez définir le chemin vers un fichier de contenu de point de terminaison externe avec le paramètre `-Path` de `New-PSUEndpoint`. Le chemin est relatif au répertoire `.universal` dans le référentiel. Le contenu du fichier `endpoints.ps1` est alors le suivant : ```powershell New-PSUEndpoint -Url "/path" -Path "endpoint-path.ps1" ``` ## API C\# Les API C# sont activées en tant qu'[extension](/powershell-universal/fr/plateforme/plugins.md#c-api-environment). Il n'existe pas d'interface utilisateur pour créer une API C#, vous devez donc le faire à l'aide de fichiers de configuration. Commencez par créer un fichier `.cs` qui exécute votre API. Vous aurez accès à un paramètre `request` qui inclut toutes les données sur la requête API. ```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; } ``` Vous aurez également accès à une propriété `ServiceProvider` qui vous permet d'accéder aux services dans PowerShell Universal. Ceux-ci ne sont pas encore bien documentés, mais voici un exemple de redémarrage d'un tableau de bord. ```csharp var dm = ServiceProvider.GetService(typeof(IDashboardManager)); var dashboard = dm.GetDashboard(1); dm.Restart(dashboard); ``` Parmi les autres services utiles, on trouve : * IDatabase * IApiService * IConfigurationService * IJobService Vous pouvez choisir de retourner un `ApiResponse` depuis votre point de terminaison. ```powershell return new ApiResponse { StatusCode = 404 }; ``` Une fois que vous avez défini votre fichier de point de terminaison C#, vous pouvez l'ajouter en modifiant `endpoints.ps1`. ```powershell New-PSUEndpoint -Url /csharp -Path endpoint.cs -Environment 'C#' ``` Le service PowerShell Universal compile et exécute automatiquement les points de terminaison C#. ## API * [New-PSUEndpoint](https://github.com/Devolutions/doc-gitbook/blob/master/translations/fr/powershell-universal/cmdlets/New-PSUEndpoint.txt) * [Get-PSUEndpoint](https://github.com/Devolutions/doc-gitbook/blob/master/translations/fr/powershell-universal/cmdlets/Get-PSUEndpoint.txt) * [Remove-PSUEndpoint](https://github.com/Devolutions/doc-gitbook/blob/master/translations/fr/powershell-universal/cmdlets/Remove-PSUEndpoint.txt) * [New-PSUApiResponse](https://github.com/Devolutions/doc-gitbook/blob/master/translations/fr/powershell-universal/cmdlets/New-PSUApiResponse.txt) * [Set-PSUSetting](https://github.com/Devolutions/doc-gitbook/blob/master/translations/fr/powershell-universal/cmdlets/Set-PSUSetting.txt) --- # 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: ``` GET https://docs.devolutions.net/powershell-universal/fr/api/endpoints.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.