Met een REST Api ‘ s voor het uitbreiden van uw scripts is een handige functie te implementeren. U kunt toegang krijgen tot nieuwe functionaliteiten en de mogelijkheden om nieuwe, meer geavanceerde scripts uit te breiden.
Maar de ervaring voor velen bij het beginnen met het gebruik van REST-Api ‘ s in scripts is dat het voelt heel onhandig en onnatuurlijk. In deze post bespreken we:
- Wat een REST API is
- Hoe lees je de meest voorkomende vorm van documentatie
- Het gebruik van een REST API met PowerShell
- Enkele tips en trucs over hoe om het te maken, gemakkelijker en betere ervaring
Wat Is RUST?
REST, of RESTful Api ‘ s, is een API die gebruikt HTTP-verzoeken ophalen, toevoegen, verwijderen of bewerken van gegevens in de verschillende diensten.
Wat willen we doen met de gegevens wordt in de regel bepaald door wat de HTTP-methode die u gebruikt. Hier is een overzicht van de HTTP-methoden en wat ze gewend zijn te doen in een REST API:
- KRIJGEN—Lezen
- POST—Maken
- PATCH—Gedeeltelijke update/wijzigen
- ZET—Update/vervangen
- Verwijderen
De gegevens die worden geretourneerd door een REST API is meestal terug in JSON formaat.
Nu, laten we beginnen met onze eerste API-aanroep!
Het lezen van de documentatie
Leren lezen en interpreteren van de documentatie voor de verschillende REST-Api ‘ s is van essentieel belang voor het gebruik ervan. Gelukkig, als je weet hoe om te lezen van een stijl van documentatie kunt u snel leren hoe om te lezen van anderen.
Wij zijn met behulp van petstore.bluf.io in dit artikel, omdat het gebruik maakt van de populaire Branie kader dat is vrij gebruikelijk om in de echte wereld tegenkomen.
De vorige afbeelding toont de meest essentiële informatie over de REST API eindpunten:
- HTTP-methode GET/POST/VERWIJDEREN, enz.
- Relatieve URL voor de REST API-eindpunt (Basis-URL wordt meestal gepresenteerd op de top van de pagina documentation)
- Een korte beschrijving
Krijgen in de Details
De eerste pagina van de documentatie is geweldig, en je kunt meestal het uitvoeren van het meeste oproepen waarvoor de HTTP-methode GET met die informatie. Maar de methoden zoals het PLAATSEN en STELLEN meestal vereisen dat je klikt en vouw de rij om meer informatie te krijgen.
Als u klikt op één van de rijen, u bent gepresenteerd met informatie die er als volgt uitziet:
Hier hebben we gepresenteerd in de REST eindpunt dat kan het maken van een nieuwe pet-object. Het geeft aan hoe de JSON moeten kijken die werd geleverd in het lichaam van de POST en wat voor soort inhoud het accepteert. Overige overige eindpunten geeft aan wat de verschillende parameters zijn, wat gegevenstype moet worden, etc.
Dat is de basis voor het lezen van de documentatie. Nu dat duidelijk is, is het tijd om te beginnen met een REST Api ‘ s met PowerShell.
KRIJGEN(ting) Uw Eerste Gegevens
Met een REST Api ‘ s met PowerShell is meestal vrij eenvoudig en je bent met de ingebouwde cmdlets dus geen extra modules nodig zijn. Je gaat om het ophalen van gegevens via de GET-methode op /pet/{petId} eindpunt.
Als u uitbreiden het /pet/{petId} eindpunt in de documentatie, dan kunt u zien dat {petId} is eigenlijk een parameter die neemt een geheel getal.
Dat maakt de URL voor het ophalen van de pet-object met id 1: https://petstore.swagger.io/v2/pet/1
BRANIE REST API-documentatie meestal presenteert de basis-URL bovenaan de pagina.
Nu, laten we beginnen met PowerShell. Open een Terminal venster en typ:
PS51 > Beroepen-RestMethod -Methode GET-ContentType “application/json” -Uri “https://petstore.swagger.io/v2/pet/1”
id : 1
categorie : @{id=0; naam=string}
naam : doggie
photoUrls : {string}
tags : {@{id=0; naam=string}}
status : beschikbaar
Beroepen-RestMethod zet de geretourneerde JSON automatisch naar een object, als de content-type “application/json” is terug in het antwoord van de server.
Fout 404 – Niet gevonden, betekent dat meestal dat het object kan niet worden gevonden, niet dat de URL foutief heeft ingevoerd.
U heeft nu succesvol uw eerste REST API-aanroep. Maar alleen zijn is de toegang tot data is vrij beperkt, dus laten we iets maken met de methode POST.
Het maken van een Object met de POST-Methode
De POST-methode wordt het meest gebruikt voor het maken, zoals het aanmaken van gebruikers of items, enz. Een POST-aanvraag stuurt een LICHAAM met informatie naar de REST eindpunt, meestal in JSON formaat, maar het kan ook als een URL-gecodeerde vorm.
Je gaat leren hoe te maken van een JSON-object dat je kan POSTEN op de /pet eindpunt.
U kunt zien hoe de JSON is verondersteld om te kijken of je het uitbreiden van de POST /huisdier rij in de documentatie.
Laten we beginnen met het maken van een hash die we later kunnen omzetten naar een JSON-object. Raw JSON moet worden vermeden in PowerShell scripts becaise het beperken van de mogelijkheden.
$Body = @{
id = 19
categorie = @{
id = 45
name = “Wat”
}
name = “Dawg”
photoUrls = @(
“string”
)
tags = @(
@{
id = 0
name = “string”
}
)
status = “beschikbaar”
}
Als u een harde tijd aan het creëren van een hash die wordt omgezet in de JSON die u wilt installeren, installeert u de PsdKit module en gebruik het commando: $JsonString | ConvertTo-Psd
Je hebt nu een hash-tabel die je kan converteren naar een JSON string en POST naar de /pet-eindpunt:
$JsonBody = $Body | ConvertTo-Json
$Uri = “https://petstore.swagger.io/v2/pet”
Beroepen-RestMethod -ContentType “application/json” -Uri $Uri -Methode Post -Body $JsonBody
id : 19
categorie : @{id=45; naam=Wat}
naam : Dawg
photoUrls : {string}
tags : {@{id=0; naam=string}}
status : beschikbaar
Wanneer het object is gemaakt, meestal wordt het object dat is gemaakt voor bevestiging.
Met DELETE
De methode DELETE verwijdert de gegevens en de manier om dat te doen is vrij gelijkaardig aan de methode zoals hier wordt getoond:
PS51 > Beroepen-RestMethod -Methode VERWIJDEREN-ContentType “application/json” -Uri “https://petstore.swagger.io/v2/pet/1”
Net op de hoogte zodat u niet verwijderen van alles wat die u nodig zou kunnen hebben.
Met behulp van ZETTEN
De methode PUT updates van reeds bestaande gegevens. Dit is gedaan op dezelfde manier als de POST-methode, door het indienen van een volledige of gedeeltelijke JSON object:
PS51> $Body = [PSCustomObject]@{
id = 19
name = “Dawg met een nieuwe naam”
}
PS51> $JsonBody = $Body | ConvertTo-Json
PS51> $Uri = “https://petstore.swagger.io/v2/pet”
PS51> Beroepen-RestMethod -ContentType “application/json” -Uri $Uri -Methode ZET -Body $JsonBody
id naam photoUrls tags
— —- ——— —-
19 Dawg met een nieuwe naam {} {}
Meestal, de REST API geeft een JSON object met de gebruikte en/of bijgewerkte gegevens. U kunt zien dat het object is bijgewerkt met de GET-methode naar het:
PS 51> Beroepen-RestMethod -ContentType “application/json” -Uri “https://petstore.swagger.io/v2/pet/19”
id : 19
categorie : @{id=45; naam=Wat}
naam : Dawg met een nieuwe naam
photoUrls : {string}
tags : {@{id=0; naam=string}}
status : beschikbaar
Het Creëren Van Functies
Het schrijven van deze commando ‘ s als ze kan heel vervelend en niet echt schaalbaar. Als we noemen een eindpunt meer dan eens, maak dan een functie voor. Het is vrij eenvoudig en slechts een paar regels nodig zijn:
Functie-PetstorePet {
[cmdletbinding()]
param(
# Id van het huisdier
[Parameter(Verplicht,ValueFromPipeline)]
[int]$Id
)
Begin{}
Proces{
$RestMethodParams = @{
Uri = “https://petstore.swagger.io/v2/pet/$Id’”
ContentType = “application/json”
Method = “GET”
}
Beroepen-RestMethod @RestMethodParams
}
End{}
}
Na het maken van uw functie, kunt u bellen in je script:
PS51> Get-PetstorePet -Id 1
id naam photoUrls tags
— —- ——— —-
1 Hondje {http://picture.url} {}
U kunt dit doen voor de POST-methode en voor het maken van een nieuw huisdier in de dierenwinkel:
Functie Add-PetstorePet {
[cmdletbinding()]
param(
# Id van het huisdier
[Parameter(Verplicht,ValueFromPipelineByPropertyName)]
[int]$Id,
# Naam van het huisdier
[Parameter(Verplicht,ValueFromPipelineByPropertyName)]
[string]$Naam
# De Status van de huisdier (beschikbaar, verkocht, etc)
[Parameter(Verplicht,ValueFromPipelineByPropertyName)]
[string]$Status,
# Id van de pet-categorie
[Parameter(Verplicht,ValueFromPipelineByPropertyName)]
[int]$Categorienummer,
# Naam van het huisdier categorie
[Parameter(Verplicht,ValueFromPipelineByPropertyName)]
[string]$Categorienaam
# Url ‘s om foto’ s van het huisdier
[Parameter(Verplicht,ValueFromPipelineByPropertyName)]
[string[]]$PhotoUrls,
# Tags van de huisdieren als hash-array: @{Id=1;Naam=”Hond”}
[Parameter(Verplicht,ValueFromPipelineByPropertyName)]
[Hash[]]$Labels
)
Begin{}
Proces{
$Body = @{
id = $Id
categorie = @{
id = $CategoryId
naam = $Categorienaam
}
naam = $Naam
photoUrls = $PhotoUrls
tags = $Labels
status = $Status
}
$BodyJson = $Body | ConvertTo-Json
$RestMethodParams = @{
Uri = “https://petstore.swagger.io/v2/pet/”
ContentType = “application/json”
Method = “Post”
Body = $BodyJson
}
Beroepen-RestMethod @RestMethodParams
}
End{}
}
En het aanroepen van deze PowerShell functie daarna maakt dit heel lang taak een stuk eenvoudiger:
PS51> $AddPetStorePetsParams = @{
Id = 44
Name = “Birdie”
Status = “beschikbaar”
CategoryId = 50
Categorie Naam = “Haviken”
PhotoUrls = “https://images.contoso.com/hawk.jpg”
Tags = @(
@{
Id=10
Name=”Niet eagles”
}
)
}
PS51> Add-PetStorePet @AddPetStorePetsParams
id : 44
categorie : @{id=50; naam=Hawks}
naam : Birdie
photoUrls : {https://images.contoso.com/hawk.jpg}
tags : {@{id=0}}
status : beschikbaar
Kans is groot dat veel van de modules die u dagelijks gebruikt worden gemaakt van functies die alleen gebruikt REST Api ‘ s in de achtergrond.
Samenvatting
Leren hoe te gebruiken REST Api ‘ s is het met name over het leren lezen van de documentatie. We gebruikten ORNAAT op basis van de documentatie in dit bericht, omdat het aangeeft hoe de andere vormen van documentatie kan meekijken.
Ook het omzetten van uw API-aanroepen van een functie kan bespaart u een hoop tijd, maak uw werk gemakkelijker, en je scripts cleaner.