L'utilisation de l'API REST pour étendre vos scripts est une fonctionnalité utile à implémenter. Vous pouvez accéder à de nouvelles fonctionnalités et les possibilités de créer de nouveaux scripts plus avancés sont étendues.
Mais l'expérience pour beaucoup lorsqu'ils commencent à utiliser l'API REST dans les scripts est que cela semble assez maladroit et contre nature. Dans cet article, nous discutons:
- Qu'est-ce qu'une API REST
- Comment lire la forme de documentation la plus courante
- Comment utiliser une API REST avec PowerShell
- Quelques trucs et astuces pour en faire une expérience meilleure et plus facile
Qu'est-ce que REST?
DU REPOS, o API RESTful, est une API qui utilise des requêtes HTTP pour rechercher, ajouter, supprimer ou manipuler des données dans différents services.
Ce que nous voulons faire avec les données est généralement décidé par ce que Méthode HTTP Qu'est ce que tu utilises. Voici une liste récapitulative des méthodes HTTP et de leur utilisation dans une API REST:
- OBTENIR - Lire
- PUBLIER: créer
- PIÈCE: actualisation / modification partielle
- METTRE: mettre à jour ou remplacer
- EFFACER: Supprimer
Les données renvoyées par une API REST sont généralement renvoyées au format JSON.
Maintenant, commençons par notre premier appel API!
Lire la doc
Apprendre à lire et interpréter la documentation des différentes API REST est essentiel pour les utiliser. Par chance, si vous savez lire un style de doc, peut rapidement apprendre à lire les autres.
Nous utilisons petstore.swagger.io dans ce post, puisqu'il utilise le populaire Se pavaner cadre assez courant dans le monde réel.
L'image ci-dessus montre les informations les plus essentielles sur les points de terminaison de l'API REST:
- Méthode HTTP: AVOIR / PUBLIER / EFFACER, etc.
- URL relative au point de terminaison de l'API REST (l'URL de base est généralement présentée en haut de la page de documentation)
- Une brève description
Entrez dans les détails
La première page de la documentation est excellente et, comme d'habitude, vous pouvez effectuer la plupart des appels qui nécessitent la méthode http get avec ces informations. mais les méthodes telles que post et set vous obligent généralement à cliquer et à développer la ligne pour en savoir plus.
Si vous cliquez sur l’une des lignes, des informations similaires à celles-ci vous sont présentées:
Ici, nous introduisons le point de terminaison REST qui peut créer un nouvel objet animal de compagnie. Spécifie à quoi le JSON qui a été fourni dans le corps du POST doit ressembler et quel type de contenu il accepte. D'autres points de terminaison REST spécifient leurs différents paramètres, quel type de données devrait-il être, etc.
C'est les bases pour lire la documentation. Maintenant que c'est clair, il est temps de commencer à utiliser les API REST avec PowerShell.
AVOIR (chose) vos premières données
L’utilisation des API REST avec PowerShell est généralement assez simple et vous utilisez des applets de commande intégrées, donc aucun module supplémentaire n’est nécessaire. Vous obtiendrez des données via la méthode GET dans / Animal domestique / {petId} extrémité.
Si vous développez le / Animal domestique / {petId} point final dans la documentation, peut voir que {petId} est en fait un paramètre qui prend un entier.
Cela rend l'url pour rechercher l'objet animal de compagnie avec id 1: https://petstore.swagger.io/v2/pet/1
La documentation de l'API SWAGGER REST présente généralement l'URL de base en haut de la page.
Maintenant, commençons par PowerShell. Ouvrez une fenêtre de terminal et entrez:
PS51 > Invoke-RestMethod -Method GET -ContentType "application/json" -Uri "https://petstore.swagger.io/v2/pet/1"
id : 1
category : @{id=0; name=string}
name : doggie
photoUrls : {string}
tags : {@{id=0; name=string}}
status : availableInvocar-RestMethod convertit le JSON renvoyé automatiquement en objet, puisque le type de contenu “application / json” est renvoyé dans la solution serveur.
Error 404 - Not foundsignifie généralement que l'objet est introuvable, pas que l'url soit mal orthographié.
Vous avez maintenant effectué avec succès votre premier appel d'API REST. Mais seulement pouvoir OBTENIR des données est assez limitatif, créons donc quelque chose avec la méthode POST.
Créer un objet avec la méthode POST
La méthode POST est le plus souvent utilisée pour créer, comment créer des utilisateurs ou des entrées, etc. Une requête POST envoie un BODY contenant des informations au point de terminaison REST, généralement au format JSON, mais il peut aussi s'agir d'une forme codée en URL.
Vous apprendrez à créer un objet JSON que vous pouvez POSTER sur le /mascotte extrémité.
Vous pouvez voir à quoi le JSON est censé ressembler si vous développez le PUBLIER / mascotte ligne dans la documentation.
Commençons par créer une table de hachage que nous pourrons plus tard convertir en objet JSON. Le JSON brut doit être évité dans les scripts PowerShell car il limite ses capacités.
$Body = @{
id = 19
category = @{
id = 45
name = "Whatever"
}
name = "Dawg"
photoUrls = @(
"string"
)
tags = @(
@{
id = 0
name = "string"
}
)
status = "available"
}si vous avez des difficultés à créer une table de hachage qui se convertit en json souhaité, installer le PsdKit et utilisez la commande:
$JsonString | ConvertTo-Psd
Vous disposez maintenant d’une table de hachage que vous pouvez convertir en chaîne JSON et POST dans le /mascotte extrémité:
$JsonBody = $Body | ConvertTo-Json
$Uri = "https://petstore.swagger.io/v2/pet"
Invoke-RestMethod -ContentType "application/json" -Uri $Uri -Method Artículo -Body $JsonBody
id : 19
category : @{id=45; name=Whatever}
name : Dawg
photoUrls : {string}
tags : {@{id=0; name=string}}
status : availableLorsque l’objet est créé, reçoit régulièrement l’objet qui a été créé pour confirmation.
Utilisation de DELETE
La méthode DELETE supprime les données, et la façon de le faire est assez similaire à la méthode get comme indiqué ici:
PS51 > Invoke-RestMethod -Method DELETE -ContentType "application/json" -Uri "https://petstore.swagger.io/v2/pet/1"Gardez simplement à l’esprit que vous ne supprimez rien de ce dont vous pourriez avoir besoin.
Utilisation de PUT
La méthode PUT met à jour les données existantes. ceci est fait de la même manière que la méthode post, envoi d’un objet JSON complet ou partiel:
PS51> $Body = [PSCustomObject]@{
id = 19
name = "Dawg with a new name"
}
PS51> $JsonBody = $Body | ConvertTo-Json
PS51> $Uri = "https://petstore.swagger.io/v2/pet"
PS51> Invoke-RestMethod -ContentType "application/json" -Uri $Uri -Method PUT -Body $JsonBody
id name photoUrls tags
-- ---- --------- ----
19 Dawg with a new name {} {}En général, l’API REST renvoie un objet JSON avec les données utilisées et / ou mis à jour. vous pouvez voir que l’objet a été mis à jour à l’aide de la méthode get pour celui-ci:
PS 51> Invoke-RestMethod -ContentType "application/json" -Uri "https://petstore.swagger.io/v2/pet/19"
id : 19
category : @{id=45; name=Whatever}
name : Dawg with a new name
photoUrls : {string}
tags : {@{id=0; name=string}}
status : availableCréation de fonctions
L'écriture de ces commandes en l'état peut devenir assez fastidieuse et n'est pas vraiment évolutive. Si nous appelons un point final plus d'une fois, créer une fonction pour lui. C'est assez simple et seulement quelques lignes sont nécessaires:
Function Get-PetstorePet {
[cmdletbinding()]
param(
# Id of the pet
[Parameter(Mandatory,ValueFromPipeline)]
[int]$Id
)
Begin{}
Process{
$RestMethodParams = @{
Uri = "https://petstore.swagger.io/v2/pet/$Id"
ContentType = "application/json"
Method = "GET"
}
Invoke-RestMethod @RestMethodParams
}
End{}
}Après avoir créé votre rôle, tu peux l'appeler dans ton script:
PS51> Get-PetstorePet -Id 1
id name photoUrls tags
-- ---- --------- ----
1 Doggie {http://picture.dirección url} {} Vous pouvez le faire pour la méthode POST et pour créer un nouvel animal de compagnie dans l'animalerie:
Function Add-PetstorePet {
[cmdletbinding()]
param(
# Id of the pet
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[int]$Id,
# Name of the pet
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[string]$Name,
# Status of the pet (available, sold etc)
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[string]$Status,
# Id of the pet category
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[int]$CategoryId,
# Name of the pet category
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[string]$CategoryName,
# URLs to photos of the pet
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[string[]]$PhotoUrls,
# Tags of the pets as hashtable array: @{Id=1;Name="Dog"}
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[Hashtable[]]$Tags
)
Begin{}
Process{
$Body = @{
id = $Id
category = @{
id = $CategoryId
name = $CategoryName
}
name = $Name
photoUrls = $PhotoUrls
tags = $Tags
status = $Status
}
$BodyJson = $Body | ConvertTo-Json
$RestMethodParams = @{
Uri = "https://petstore.swagger.io/v2/pet/"
ContentType = "application/json"
Method = "Artículo"
Body = $BodyJson
}
Invoke-RestMethod @RestMethodParams
}
End{}
}Et appeler cette fonction PowerShell par la suite rend cette tâche assez longue beaucoup plus facile:
PS51> $AddPetStorePetsParams = @{
Id = 44
Name = "Birdie"
Status = "available"
CategoryId = 50
CategoryName = "Hawks"
PhotoUrls = "https://images.contoso.com/hawk.jpg"
Tags = @(
@{
Id=10
Name="Not eagles"
}
)
}
PS51> Add-PetStorePet @AddPetStorePetsParams
id : 44
category : @{id=50; name=Hawks}
name : Birdie
photoUrls : {https://images.contoso.com/hawk.jpg}
tags : {@{id=0}}
status : availableTrès probablement, de nombreux modules que vous utilisez quotidiennement sont constitués de fonctions qui n'utilisent que des API REST en arrière-plan..
résumé
Apprendre à utiliser les API REST consiste principalement à apprendre à lire la documentation. Nous utilisons la documentation basée sur SWAGGER dans ce post, car il représente à quoi peuvent ressembler les autres styles de documentation.
En même temps, transformer vos appels API en fonction peut vous faire gagner beaucoup de temps, facilitez votre travail et nettoyez vos scripts.
