> 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). # Terminaux Configurez les points de terminaison d'API PowerShell Universal avec New-PSUEndpoint, couvrant le routage d'URL, les en-têtes, les témoins, les corps de requête, les téléversements de fichiers et les Les points de terminaison sont définis par leur URI et leur méthode HTTP. Les appels effectués au serveur Universal qui correspondent au point de terminaison d'API et à la méthode que vous avez définis exécutent le script du point de terminaison d'API. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/endpoint' -Method 'GET' -Endpoint { "Hello, world!" } ``` {% endcode %} Pour invoquer la méthode ci-dessus, vous pouvez utiliser `Invoke-RestMethod`. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/endpoint ``` {% endcode %} Lors de la définition de points de terminaison dans l'API de gestion, vous pouvez omettre l'appel `New-PSUEndpoint`, car la console d'administration le définit. Le seul contenu que vous devez fournir dans l'éditeur est le script que vous souhaitez appeler. {% hint style="warning" %} Évitez d'utiliser des URL de point 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`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method @('GET', 'POST') -Endpoint { if ($Method -eq 'GET') { Get-User } else { New-User } } ``` {% endcode %} ## URL variable Les URL peuvent contenir des segments variables. Vous pouvez indiquer un segment variable à l'aide d'un deux-points (`:`). Par exemple, l'URL suivante fournirait une variable pour l'ID 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. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user/:id' -Method 'GET' -Endpoint { Get-User -Id $Id } ``` {% endcode %} Pour appeler cette API et spécifier l'ID, procédez comme suit : {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user/123 ``` {% endcode %} ## 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. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method 'GET' -Endpoint { Get-User -Id $Id } ``` {% endcode %} L'appel `Invoke-RestMethod` résultant doit alors inclure le paramètre de chaîne de requête. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user?Id=123 ``` {% endcode %} 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. Inclure une esperluette (&) sans guillemets causera des problèmes autant dans Windows PowerShell que dans PowerShell 7. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod "http://localhost:5000/user?Id=123&name=tim" ``` {% endcode %} ### Considérations de sécurité Lorsque vous acceptez des entrées via des paramètres de chaîne de requête, vous pourriez ê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 fournis 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. {% 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 %} Afin d'éviter ce problème particulier, vous pouvez utiliser un bloc `param`. {% 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 %} ## En-têtes Les en-têtes de requête sont disponibles dans les API à l'aide de la variable `$Headers`. La variable est une table de hachage. Pour accéder à un en-tête, utilisez la syntaxe suivante : {% code collapsedlinecount="10" %} ```powershell $Headers['Content-Type'] ``` {% endcode %} ## Témoins Les témoins de requête sont disponibles dans les API à l'aide de la variable `$Cookies`. La variable est une table de hachage. Pour accéder à un témoin, utilisez la syntaxe suivante : {% code collapsedlinecount="10" %} ```powershell $Cookies['Request-Cookie'] ``` {% endcode %} Renvoyez les témoins de requête avec l'applet de commande `New-PSUApiResponse`. Utilisez le paramètre `-Cookies` avec une table de hachage fournie. {% code collapsedlinecount="10" %} ```powershell New-PSUApiResponse -StatusCode 200 -Cookies @{ ResponseCookie = '123' } ``` {% endcode %} ## Corps Pour accéder au corps d'une requête, vous accéderez simplement à la variable `$Body`. La variable `$Body` d'Universal sera une chaîne. Si vous attendez du JSON, vous devriez utiliser `ConvertFrom-Json`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Method Post -Endpoint { $User = ConvertFrom-Json $Body New-User $User } ``` {% endcode %} Pour appeler le point de terminaison ci-dessus, spécifiez le corps de `Invoke-RestMethod`. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body "{'username': 'adam'}" ``` {% endcode %} ## Journal en direct Vous pouvez consulter les informations du journal en direct de n'importe quel point de terminaison en cliquant sur l'onglet du journal. Les journaux en direct comprennent l'URL, la méthode HTTP, l'adresse IP source, les flux PowerShell, le code d'état, le type de contenu retourné et la longueur du contenu HTTP. Vous pouvez écrire dans le journal en direct à partir de vos points de terminaison avec des applets de commande comme `Write-Host`. ## Tests Vous pouvez utiliser l'onglet Test dans l'éditeur de point de terminaison pour tester vos API. À l'aide de 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. Lorsque vous utilisez l'onglet Test, toute modification des valeurs du test entraînera la mise à jour d'un bloc de code que vous pourrez ensuite utiliser dans PowerShell. Cliquez sur l'onglet Code pour afficher le code de test. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod -Uri 'http://localhost:5000/test-api?Page=1' -Headers @{'X-Custom-Header' = 'Value';} -Method 'POST' ``` {% endcode %} De plus, les tests effectués dans l'outil de test seront conservés pendant 30 jours afin de permettre de refaire des tests sans avoir à reconfigurer toutes les propriétés. Cliquer sur le bouton Appliquer configurera l'outil de test avec les mêmes propriétés. ## 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 seront transmises à votre point de terminaison sous forme de paramètres. {% 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 %} Vous pouvez ensuite utiliser une table de hachage avec Invoke-RestMethod pour transmettre des données de formulaire. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body @{ UserName = "adriscoll" FirstName = "Adam" LastName = "Driscoll" } ``` {% endcode %} ## Données JSON Vous pouvez transmettre des données JSON à un point de terminaison et elles se lieront automatiquement à un bloc param. {% 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 %} Vous pouvez ensuite envoyer des données JSON au point de terminaison. {% 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 %} ## 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. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user/:name' -Endpoint { param([Parameter(Mandatory)$Name, $Role = "Default") } ``` {% endcode %} 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. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user/:name' -Endpoint { param($Role = "Default") $Name -eq 'Adam' } ``` {% endcode %} Si vous utilisez l'attribut `CmdletBinding` ou `Parameter` dans votre bloc param, le point de terminaison imposera strictement quels paramètres sont autorisés dans le point de terminaison. Par exemple, ce qui suit impose que le paramètre name soit spécifié. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Endpoint { param([Parameter(Mandatory)$Name) } ``` {% endcode %} Cela dit, vous ne pouvez pas spécifier de paramètres supplémentaires au point de terminaison. Faire ce qui suit provoquera une erreur. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/user -Method Post -Body (@{ Name = "adriscoll" DisplayName = 'Adam' } | ConvertTo-Json) -ContentType 'application/json' ``` {% endcode %} Si vous modifiez votre point de terminaison pour éviter d'utiliser l'attribut `Parameter`, vous pouvez transmettre un nombre quelconque de paramètres et ils seront liés en tant que variables et non en tant que paramètres du point de terminaison. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/user' -Endpoint { param($Name) } ``` {% endcode %} ### Ensembles de paramètres de méthode Vous pouvez définir des ensembles de paramètres à l'aide de paramètres de méthode. Par défaut, PowerShell Universal inspectera le bloc param pour déterminer si ces noms de méthodes HTTP `Get`, `Put`, `Post`, `Delete` ou autres sont spécifiés et les inclura automatiquement. Lorsque les points de terminaison acceptent plusieurs méthodes, il peut être impossible de déterminer quel ensemble de paramètres appeler en fonction des données fournies. Dans l'exemple ci-dessous, le Get et le Post acceptent tous deux le paramètre name. Il n'y a aussi aucun moyen d'appeler le Post sans un nom, donc la validation pourrait échouer. Pour remédier à cela, incluez des paramètres `Post` et `Get` qui font partie de leur ensemble de paramètres respectif. PowerShell Universal inclura ce paramètre pour s'assurer que le bon ensemble de paramètres est appelé. {% 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 %} ## Retourner des données Les données retournées par les points de terminaison sont présumé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 comme vous le souhaitez. ## Traitement des 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 des données téléversées vers le point de terminaison. {% 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" %} Le type de contenu `The 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. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Post -Endpoint { [IO.File]::WriteAllBytes("tempfile.dat", $Data) } ``` {% endcode %} ### Téléchargement de fichiers Vous pouvez envoyer des fichiers à l'aide de l'applet de commande `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 %} ## Retourner des réponses personnalisées Vous pouvez retourner des réponses personnalisées depuis les points de terminaison en utilisant l'applet de commande `New-PSUApiResponse` dans votre point de terminaison. Cette applet de commande vous permet de définir le code d'état, le type de contenu et même de spécifier les données byte\[] du contenu à retourner. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Get -Endpoint { New-PSUApiResponse -StatusCode 410 } ``` {% endcode %} Vous pouvez également retourner des données de corps personnalisées avec le paramètre `-Body` de `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 %} L'invocation de la méthode REST retourne le code d'erreur personnalisé. {% code collapsedlinecount="10" %} ```powershell PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:8080/file Invoke-RestMethod: Not what you're looking for. ``` {% endcode %} Vous pouvez contrôler le type de contenu des données retournées avec le paramètre `-ContentType`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url '/file' -Method Get -Endpoint { New-PSUApiResponse -Body "12" -ContentType 'text/xml' } ``` {% endcode %} 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`. {% code collapsedlinecount="10" %} ```powershell New-PSUApiResponse -StatusCode 200 -Headers @{ "Referrer-Policy" = "no-referrer" } ``` {% endcode %} ## Runspaces persistants Les runspaces persistants vous permettent de maintenir l'état du runspace entre les appels d'API. C'est important pour les utilisateurs qui effectuent une forme d'initialisation dans leurs points de terminaison qu'ils ne veulent pas exécuter lors des appels d'API subséquents. 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 pendant 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 se configure dans le script `environments.ps1`. {% code collapsedlinecount="10" %} ```powershell New-PSUEnvironment -Name 'Env' -Path 'powershell.exe' -PersistentRunspace ``` {% endcode %} Vous pouvez ensuite assigner l'environnement d'API dans le script `settings.ps1`. {% code collapsedlinecount="10" %} ```powershell Set-PSUSetting -ApiEnvironment 'Env' ``` {% endcode %} ## 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 dépôt. Le contenu du fichier `endpoints.ps1` est alors le suivant : {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url "/path" -Path "endpoint-path.ps1" ``` {% endcode %} ## API C\# Les API C# sont activées en tant que [module d'extension](/powershell-universal/fr/plateforme/plugins/c-api-endpoints.md). Il n'y a pas d'interface utilisateur pour créer une API C#, vous devez donc le faire à l'aide de fichiers de configuration. Créez d'abord un fichier `.cs` qui exécute votre API. Vous aurez accès à un paramètre `request` qui inclut toutes les données concernant la requête d'API. {% 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 %} 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. {% code collapsedlinecount="10" %} ```csharp var dm = ServiceProvider.GetService(typeof(IDashboardManager)); var dashboard = dm.GetDashboard(1); dm.Restart(dashboard); ``` {% endcode %} Voici d'autres services utiles : * IDatabase * IApiService * IConfigurationService * IJobService Vous pouvez choisir de retourner un `ApiResponse` depuis votre point de terminaison. {% code collapsedlinecount="10" %} ```powershell return new ApiResponse { StatusCode = 404 }; ``` {% endcode %} Une fois que vous avez défini votre fichier de point de terminaison C#, vous pouvez l'ajouter en modifiant `endpoints.ps1`. {% code collapsedlinecount="10" %} ```powershell New-PSUEndpoint -Url /csharp -Path endpoint.cs -Environment 'C#' ``` {% endcode %} Le service PowerShell Universal compile et exécute automatiquement les points de terminaison C#. ## API * [New-PSUEndpoint](/powershell-universal/fr/commandes-powershell/new-psuendpoint.md) * [Get-PSUEndpoint](/powershell-universal/fr/commandes-powershell/get-psuendpoint.md) * [Remove-PSUEndpoint](/powershell-universal/fr/commandes-powershell/remove-psuendpoint.md) * [New-PSUApiResponse](/powershell-universal/fr/commandes-powershell/new-psuapiresponse.md) * [Set-PSUSetting](/powershell-universal/fr/commandes-powershell/set-psusetting.md) ### Voir aussi * [Devolutions Academy – Ajout de la réinitialisation du mot de passe utilisateur](https://academy.devolutions.net/student/activity/3546111-part-6-adding-reset-user-password) * [Devolutions Academy – État de l'utilisateur/actualiser les détails de l'utilisateur](https://academy.devolutions.net/student/activity/3546046-part-5-user-status-refresh-user-details) * [Devolutions Academy – Ajout de la fonctionnalité de déverrouillage d'utilisateur](https://academy.devolutions.net/student/activity/3546024-part-4-adding-user-unlock-feature) * [Devolutions Academy – Créer un point de terminaison variable](https://academy.devolutions.net/student/activity/3466016-creating-a-variable-endpoint) * [Devolutions Academy – Créer un point de terminaison de chaîne de requête](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/fr/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.