Points de terminaison

Configuration des points de terminaison pour les API Universal.

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.

New-PSUEndpoint -Url '/endpoint' -Method 'GET' -Endpoint {
   "Hello, world!"
}

Pour invoquer la méthode ci-dessus, vous pouvez utiliser Invoke-RestMethod.

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

Le seul contenu que vous devez fournir dans l'éditeur est le script que vous souhaitez appeler.

API Content

É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 de l'API de gestion pour vérifier qu'aucune des URL ne correspond.

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.

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.

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 :

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.

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.

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.

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. 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.

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.

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 :

$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 :

$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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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é.

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.

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.

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é.

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
    }
}

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.

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,…

Le type de contenu multipart/form-data n'est pas pris en charge pour le téléversement de fichiers vers les API.

Vous pouvez également enregistrer le fichier dans un répertoire.

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.

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.

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.

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é.

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.

New-PSUEndpoint -Url '/file' -Method Get -Endpoint {
    New-PSUApiResponse -Body "<xml><node>1</node><node2>2</node2></xml>" -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.

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 pour votre API. Définissez le paramètre -PersistentRunspace pour activer cette fonctionnalité. Cela est configuré dans le script environments.ps1.

New-PSUEnvironment -Name 'Env' -Path 'powershell.exe' -PersistentRunspace

Vous pouvez ensuite assigner l'environnement API dans le script settings.ps1.

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 :

New-PSUEndpoint -Url "/path" -Path "endpoint-path.ps1"

API C#

Les API C# sont activées en tant qu'extension.

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.

public class ApiRequest
{
    public long Id;
    public ICollection<KeyValue> Variables;
    public IEnumerable<ApiFile> Files { get; set; };
    public string Url;
    public ICollection<KeyValue> Headers;
    public byte[] Data;
    public int ErrorAction;
    public ICollection<KeyValue> Parameters;
    public string Method;
    public ICollection<KeyValue> 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.

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.

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.

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
• Get-PSUEndpoint
• Remove-PSUEndpoint
• New-PSUApiResponse
• Set-PSUSetting