Comment manipuler une API en PowerShell ?
Sommaire
I. Présentation
Aujourd'hui, les API pullulent littéralement sur Internet. Vous en utilisez même parfois sans vous en rendre compte. Les applications web modernes sont découpées en microservices autonomes, plus simples à développer et maintenir. Et devinez comment ces microservices dialoguent entre eux ?
Bingo ! Via les API.
C'est d'ailleurs ce qui permet à des outils tels que Zapier ou Integromat de coupler des applications entre elles.
Dans cet article, nous allons nous concentrer sur une API simple, afin de voir comment manipuler les appels aux API, et la gestion des données en retour en PowerShell.
Et pour ça, j'ai sélectionné l'API du site motdepasse.xyz, qui vous permet de générer des mots de passe en blocs, selon vos critères de complexité. Prêt à manipuler une API avec PowerShell ? Alors allons-y...
II. Prérequis
Pour suivre cet article, vous pourrez aussi bien utiliser PowerShell 5.1 (Windows PowerShell, également appelée version Desktop), ou alors PowerShell version 7 (également appelé PowerShell Core).
III. Comment fonctionne l'API de motdepasse.xyz ?
L'API de motdepasse.xyz accepte un certain nombre de paramètres dans l'URI à envoyer, que voici :
Je vous laisse consulter la documentation de l'API pour savoir à quoi correspondent plus en détail ces paramètres.
Concrètement, on appelle l'API via l'URL suivante :
https://api.motdepasse.xyz/create/?
On passe ensuite après le ? les paramètres choisis, ce qui peut par exemple donner :
https://api.motdepasse.xyz/create/?include_lowercase&password_length=12&quantity=1
IV. Appeler l'API en PowerShell
Comme on vient de le voir, pour dialoguer avec une API, il est nécessaire de passer un certain nombre de paramètres dans l'URL envoyée au serveur web.
Pour cela, on utilise en PowerShell Invoke-RestMethod, qui est un équivalent de Curl sous Linux.
Comme il n'y a rien de mieux qu'une démonstration par l'exemple, on va contacter l'API de motdepasse.xyz pour lui demander :
- De générer 1 mot de passe de 12 caractères, uniquement avec des minuscules
- De générer 3 mots de passe de 12 caractères chacun, contenant minuscules et chiffres
Invoke-RestMethod -Uri "https://api.motdepasse.xyz/create/?include_lowercase&password_length=12&quantity=1" Invoke-RestMethod -Uri "https://api.motdepasse.xyz/create/?include_lowercase&include_digits&password_length=12&quantity=3"
Le serveur web nous renvoie les informations demandées au format JSON. Heureusement pour nous, PowerShell est suffisamment intelligent pour transformer cette réponse en objet, facilement manipulable.
On peut voir sur la capture d'écran que l'API nous renvoie :
- Les mots de passe générés sous forme de tableau
- La date et l'heure à laquelle la réponse est envoyée
- La version actuelle de l'API
- La dernière date de modification de cette API
Afin d'exploiter plus facilement les données envoyées, on va stocker le retour de l'API dans une variable, puis on va afficher uniquement le contenu de la propriété passwords de cette variable :
$var = Invoke-RestMethod -Uri "https://api.motdepasse.xyz/create/?include_lowercase&password_length=12&quantity=2" $var.passwords
Note : Vous pouvez bien sûr naviguer dans les différents mots de passe générés comme dans un tableau classique PowerShell. Le premier mot de passe est accessible via $var.passwords[0], le second via $var.passwords[1], etc...
A ce stade, vous êtes déjà en capacité de générer vous-même et à la demande de nouveaux mots de passe utilisateurs. Mais en fonction des besoins (caractères spéciaux ou non, chiffres, majuscules, etc) vous êtes obligés de modifier manuellement l'URL avant d'envoyer votre appel API.
Pas terrible pour intégrer ça tel quel dans un script. Non ?
V. Fonction PowerShell avancée
Je ne sais pas vous, mais moi j'adore automatiser tout ce qu'il est possible d'automatiser. Et dans notre cas, j'ai cherché à voir comment automatiser la génération de l'URL envoyée à l'API en fonction des besoins.
J'ai codé une fonction qui permet de faire tout ça : vous lui passez en paramètre ce que vous attendez, l'URL est générée, l'API est contactée, et PAF! ça fait des chocapics.
Voyez plutôt :
On va détailler tout ça ensemble, et comme d'habitude vous pourrez retrouver ce script sur mon espace Github.
A. Déclaration de la fonction
Premièrement, on déclare la fonction, comme d'habitude en respectant les verbes autorisés officiellement pour nommer la fonction.
On déclare également 5 paramètres, qui vous permettront en fonction de ce que vous choisissez de personnaliser l'appel à l'API :
- Length : la taille du mot de passe. C'est obligatoire. Sinon comment l'API pourrait vous générer un mot de passe ? 😉
- Quantity : Si vous ne précisez pas de quantité, la fonction demandera à l'API de générer un seul et unique mot de passe.
- Digits, Uppercase, et SpecialCharacters sont déclarés comme des switchs et ne sont pas obligatoires. Par défaut donc, le mot de passe généré contiendra uniquement des minuscules.
Note : un paramètre de type switch fonctionne presque comme un booléen. Vous appelez la fonction avec -Digits, le switch a donc la valeur $true, et mon code derrière en tiendra compte. Vous ne mettez pas le paramètre, cela sera considéré comme un $false.
Pour le moment, voici notre fonction :
Function Invoke-ApiMotdepassexyz {
[CmdletBinding()]
Param (
[Parameter(Mandatory=$true)][int]$Length,
[Parameter(Mandatory=$false)][int]$Quantity=1,
[Parameter(Mandatory=$false)][switch]$Digits,
[Parameter(Mandatory=$false)][switch]$Uppercase,
[Parameter(Mandatory=$false)][switch]$SpecialCharacters
)
B. Construction de l'URI
On va maintenant construire l'URI à envoyer à l'API en fonction des paramètres que l'on passe ou non lorsqu'on appelle notre fonction.
On vérifie tout d'abord que la longueur demandée est comprise entre 4 et 512 caractères, et que le nombre de mots de passe à générer est compris entre 1 et 30, afin de se conformer à la documentation API.
On construit ensuite l'URI en fonction des différents paramètres.
Begin {
#Building Uri
if (!(($Length -ge 4) -and ($Length -le 512))) {
Write-Error "Password length should be between 4 and 512 characters"
break
}
if (!(($Quantity -ge 1) -and ($Quantity -le 30))) {
Write-Error "Quantity should be between 1 and 30 passwords to generate."
break
}
$Uri = "https://api.motdepasse.xyz/create/?include_lowercase&password_length=$Length&quantity=$Quantity"
if ($Digits) {
$Uri += "&include_digits"
}
if ($Uppercase) {
$Uri += "&include_uppercase"
}
if ($SpecialCharacters) {
$Uri += "&include_special_characters"
}
$Passwords = @()
}
Pour générer un mot de passe de 12 caractères, comprenant minuscules, chiffres et caractères spéciaux, cela nous donnera donc l'URI suivante: https://api.motdepasse.xyz/create/?include_lowercase&password_length=12&quantity=1&include_special_characters&include_digits
C. Appel API + Récupération du résultat
Dans le bloc Process{}, on appelle notre API en lui envoyant l'URI précédemment construite, et on catche toute exception qui pourrait se passer afin de la logguer dans la console PowerShell.
Enfin, dans le bloc End{}, on ne garde que les mots de passe générés, que l'on insère dans un tableau, avant de le renvoyer pour qu'il puisse être utilisé ultérieurement dans un script.
Process {
Try {
$ApiResult = Invoke-RestMethod -Uri $Uri
}
Catch {
Write-Outut $_.Exception
Break
}
}
End {
For($i=0;$i -lt $Length;$i++) {
$Passwords += $ApiResult.passwords[$i]
}
Return $Passwords
}
D. Fonction complète
Il ne vous reste plus qu'à appeler la fonction dans un script, par exemple de la manière suivante :
$array= Invoke-ApiMotdepassexyz -Length 15 -Quantity 5 -Digits -SpecialCharacters -Uppercase
Vous demandez donc à générer 5 mots de passe de 15 caractères chacun, contenant minuscules, majuscules, chiffres et caractères spéciaux.
Ces mots de passe sont générés puis stockés dans un tableau nommé $array, que vous pourrez réutiliser à votre guise.
Voici la fonction complète :
Function Invoke-ApiMotdepassexyz {
[CmdletBinding()]
Param (
[Parameter(Mandatory=$true)][int]$Length,
[Parameter(Mandatory=$false)][int]$Quantity=1,
[Parameter(Mandatory=$false)][switch]$Digits,
[Parameter(Mandatory=$false)][switch]$Uppercase,
[Parameter(Mandatory=$false)][switch]$SpecialCharacters
)
Begin {
#Building Uri
if (!(($Length -ge 4) -and ($Length -le 512))) {
Write-Error "Password length should be between 4 and 512 characters"
break
}
if (!(($Quantity -ge 1) -and ($Quantity -le 30))) {
Write-Error "Quantity should be between 1 and 30 passwords to generate."
break
}
$Uri = "https://api.motdepasse.xyz/create/?include_lowercase&password_length=$Length&quantity=$Quantity"
if ($Digits) {
$Uri += "&include_digits"
}
if ($Uppercase) {
$Uri += "&include_uppercase"
}
if ($SpecialCharacters) {
$Uri += "&include_special_characters"
}
$Passwords = @()
}
Process {
Try {
$ApiResult = Invoke-RestMethod -Uri $Uri
}
Catch {
Write-Outut $_.Exception
Break
}
}
End {
For($i=0;$i -lt $Length;$i++) {
$Passwords += $ApiResult.passwords[$i]
}
Return $Passwords
}
}
VI. Conclusion
Vous savez maintenant manipuler des APIs simples via PowerShell, et en prime vous avez découvert comment générer de manière automatique de nouveaux mots de passe pour vos utilisateurs.
Elle n’est pas belle la vie ? 😉
➡ Si vous souhaitez générer des mots de passe complexes en PowerShell sans utiliser un API, lisez cet article : comment générer des mots de passe avec PowerShell ?
Bonjour
Je trouve ton tuto bien fait.
Je dois interroger un API RestFul en Https standard et auto signer en PowerShell.
Il me retourne une erreur de certificat.
Comment faire.
Cordialement
JP