> 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. ```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 ``` 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. ![Propriétés de l'API](https://3889731354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwUiExB0UUkGzbColxNZX%2Fuploads%2Fgit-blob-632d5108b53fcbd362c47488410a013ad72fa8c0%2Fimage%20\(442\).png?alt=media) Le seul contenu que vous devez fournir dans l'éditeur est le script que vous souhaitez appeler. ![Contenu de l'API](https://3889731354-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwUiExB0UUkGzbColxNZX%2Fuploads%2Fgit-blob-d4878c92586d1f94974e20402ee3b699ca8727ca%2Fimage%20\(550\).png?alt=media) {% 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`. ```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 à 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 une même URL de point de terminaison. ```powershell New-PSUEndpoint -Url '/user/:id' -Method 'GET' -Endpoint { Get-User -Id $Id } ``` Pour appeler cette API et spécifier l'ID, 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 passés 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 causera des problèmes à la fois 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 par 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 fournis au point de terminaison. Voici un exemple de CWE-914. Incluez un paramètre de chaîne de requête `$IsChallengePassed` pour contourner l'épreuve. ```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" } } ``` Afin d'é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 à l'aide de 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'] ``` ## 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 : ```powershell $Cookies['Request-Cookie'] ``` 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. ```powershell New-PSUApiResponse -StatusCode 200 -Cookies @{ ResponseCookie = '123' } ``` ## 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`. ```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 de tout point de terminaison en cliquant sur l'onglet du journal. Les journaux en direct incluent 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 depuis vos points de terminaison avec des applets de commande comme `Write-Host`.

Journal en direct du point de terminaison

## Tests Vous pouvez utiliser l'onglet Test de 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 du test.

Onglet Test du point de terminaison

Lors de l'utilisation de 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 voir le code du 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 le testeur seront conservés pendant 30 jours afin de permettre de nouveaux 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.

Historique des tests

## Données de formulaire Vous pouvez passer des données à un point de terminaison sous forme de données de formulaire. Les données de formulaire seront passées à votre point de terminaison en tant que 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 passer 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 passer des données JSON à un point de terminaison et elles 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 aux paramètres optionnels tels que les paramètres de chaîne de requête. Les 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 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é. ```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. Faire ce qui suit causera 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 passer n'importe quel nombre de paramètres et ils seront liés comme variables et non comme paramètres du point de terminaison. ```powershell New-PSUEndpoint -Url '/user' -Endpoint { param($Name) } ``` ### Ensembles de paramètres de méthode Vous pouvez définir des ensembles de paramètres à l'aide des paramètres de méthode. Par défaut, PowerShell Universal inspectera le bloc param pour déterminer si ces noms de méthode 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 se peut qu'il ne puisse pas 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 également aucun moyen d'appeler le Post sans un name, 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" %} ```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 voulez retourner un autre type de données, vous pouvez retourner une chaîne formatée comme vous le souhaitez. ## 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 des 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 `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. ```powershell New-PSUEndpoint -Url '/file' -Method Post -Endpoint { [IO.File]::WriteAllBytes("tempfile.dat", $Data) } ``` ### Téléchargement de fichiers Vous pouvez envoyer des fichiers à l'aide de l'applet de commande `New-PSUApiResponse`. ```powershell New-PSUEndpoint -Url '/image' -Endpoint { $ImageData = [IO.File]::ReadAllBytes("image.jpeg") New-PSUApiResponse -ContentType 'image/jpg' -Data $ImageData } ``` ## 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. ```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 passez au paramètre `-Headers`. ```powershell New-PSUApiResponse -StatusCode 200 -Headers @{ "Referrer-Policy" = "no-referrer" } ``` ## Runspaces persistants Les runspaces persistants vous permettent de conserver l'état du runspace entre les appels d'API. Ceci 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é. Ceci est configuré dans le script `environments.ps1`. ```powershell New-PSUEnvironment -Name 'Env' -Path 'powershell.exe' -PersistentRunspace ``` Vous pouvez ensuite assigner l'environnement d'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 dépôt. 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 que [module d'extension](/powershell-universal/fr/plateforme/plugins.md#c-api-environment). Il n'y a pas d'interface pour créer une API C#, vous devez donc le faire à l'aide de fichiers de configuration. D'abord, créez 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. ```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); ``` Voici d'autres services utiles : * 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](/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 – Statut de l'utilisateur/actualisation des 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éation d'un point de terminaison variable](https://academy.devolutions.net/student/activity/3466016-creating-a-variable-endpoint) * [Devolutions Academy – Création d'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.