Die Verwendung von REST-APIs zu erweitern, Ihre Skripts ist eine nützliche Funktion zu implementieren. Sie können den Zugang zu neuen Funktionalitäten und Möglichkeiten zu erstellen, die neue erweiterte Skripte erweitern.
Aber die Erfahrung für viele, wenn Sie beginnen, zu benutzen, REST-APIs, die in scripts ist, dass es fühlt sich ziemlich ungeschickt und unnatürlich. In diesem post wir diskutieren:
- Was für ein REST-API
- Wie zu Lesen, die häufigste form der Dokumentation
- Wie zu verwenden einer REST-API mit PowerShell
- Einige Tipps und tricks auf, wie man es eine einfachere und bessere Erfahrung
Was Ist REST?
REST oder RESTful APIs ist eine API, die verwendet HTTP-requests abrufen, hinzufügen, löschen oder ändern von Daten in den verschiedenen Diensten.
Was wollen wir mit den Daten machen, ist in der Regel entschieden, welche HTTP-Methode, die Sie verwenden. Hier ist eine zusammenfassende Liste von HTTP-Methoden und was Sie zu tun pflegten, in eine REST-API:
- HOLEN—Lesen
- POST—Erstellen
- PATCH—Partial update/ändern
- PUT—Aktualisieren/ersetzen
- LÖSCHEN—Entfernen
Die Daten zurückgegeben, die durch eine REST-API wird in der Regel wieder im JSON-format.
Nun, lasst uns loslegen mit unserem ersten API-Aufruf!
Das Lesen der Dokumentation
Lern Lesen und interpretieren der Dokumentation für die verschiedenen REST-APIs ist wichtig für Sie zu verwenden. Glücklicherweise, wenn Sie wissen, wie zu Lesen, eine Art Dokumentation, können Sie schnell lernen, wie zu Lesen andere.
Wir sind mit petstore.stolzieren.io in diesem Artikel, wie es verwendet das beliebte Swagger Rahmen, das ist ziemlich üblich in der realen Welt begegnen.
Das Vorherige Bild zeigt die wichtigsten Informationen über die REST API-Endpunkte:
- HTTP—Methode GET/POST/LÖSCHEN, etc.
- Relative URL für die REST-API-Endpunkt (Basis-URL ist in der Regel, die oben auf der Dokumentations-Seite)
- Eine kurze Beschreibung
Immer in die Details
Die erste Seite der Dokumentation ist groß, und Sie können in der Regel führen die meisten Anrufe, in denen der HTTP-Methode GET die Informationen. Aber Methoden wie POST und LEGEN Sie es normalerweise erforderlich, klicken Sie auf und erweitern Sie die Zeile, um weitere Informationen zu erhalten.
Wenn Sie klicken Sie auf eine der Zeilen, die Sie mit dargestellt sind Informationen, die wie folgt aussieht:
Hier haben wir präsentierte die REST-Endpunkt erstellen kann, ein neues Haustier-Objekt. Er gibt an, wie die JSON Aussehen soll, die geliefert wurde, in den Körper der POST, und welche Art von Inhalt es akzeptiert. Andere REST-endpoints gibt an, was es ist, unterschiedliche Parameter, welche Datentypen es werden soll, usw.
Das sind die Grundlagen für die Dokumentation Lesen. Nun, das ist klar, es ist Zeit zu beginnen, die Verwendung von REST-APIs mit PowerShell.
GET(ting) Ihre Ersten Daten
Die Verwendung von REST-APIs mit PowerShell ist in der Regel ziemlich einfach, und Sie sind mit integrierten cmdlets, so dass keine zusätzlichen Module benötigt werden. Du gehst zum abrufen von Daten mithilfe der GET-Methode an – /pet – /{petId} Endpunkt.
Wenn Sie erweitern Sie die /pet/{petId} Endpunkt in der Dokumentation, können Sie sehen, dass {petId} ist eigentlich ein parameter, der nimmt eine ganze Zahl.
Das macht die URL für das abrufen der pet-Objekt mit der id 1: https://petstore.swagger.io/v2/pet/1
SWAGGER REST-API Dokumentation in der Regel stellt die Basis-URL an der Spitze der Seite.
Jetzt wollen wir die ersten Schritte mit PowerShell. Öffnen Sie ein Terminal-Fenster und geben Folgendes ein:
PS51 > Invoke-RestMethod -Methode GET-ContentType “application/json” -Uri “https://petstore.swagger.io/v2/pet/1”
id : 1
Kategorie : @{id=0; name=string}
name : doggie
photoUrls : {string}
tags : {@{id=0; name=string}}
status : verfügbar
Invoke-RestMethod konvertiert den zurückgegebenen JSON automatisch auf ein Objekt, wie der content type “application/json” zurückgegeben in der Antwort vom server.
Fehler 404 – Nicht gefunden in der Regel bedeutet, dass das Objekt nicht gefunden werden kann, nicht, dass die URL ist falsch eingegeben.
Sie haben nun erfolgreich Ihren ersten REST-API-Aufruf. Aber nur in der Lage Daten zu ERHALTEN ist ziemlich begrenzt, also lasst uns etwas schaffen, mit der POST-Methode.
Erstellen Sie ein Objekt mit der Methode POST
Die POST-Methode wird am häufigsten verwendet, zu erstellen, wie das erstellen von Benutzern oder Eintragungen, etc. Eine POST-Anforderung sendet ein KÖRPER mit Informationen zum REST-Endpunkt, in der Regel im JSON-format, aber es kann auch sein, wie ein URL-kodierter form.
Du wirst lernen, wie man ein JSON-Objekt, Sie können POST an die /pet-Endpunkt.
Sie können sehen, wie die JSON Aussehen soll, wenn Sie erweitern Sie die POST – /pet-Zeile in der Dokumentation.
Lassen Sie uns beginnen, indem Sie eine Hashtabelle, die können wir später konvertieren, um ein JSON-Objekt. Rohen JSON sollte vermieden werden PowerShell-Skripts becaise es ist die Begrenzung seiner Fähigkeiten.
$Body = @{
id = 19
Kategorie = @{
id = 45
name = “Whatever”
}
name = “Dawg”
photoUrls = @(
“string”
)
tags = @(
@{
id = 0
name = “string”
}
)
status = “available”
}
Wenn Sie haben eine harte Zeit erstellen einer Hashtabelle konvertiert, um die JSON-Sie wollen, installieren Sie die PsdKit Modul und verwenden Sie den Befehl: $JsonString | ConvertTo-Psd
Sie haben nun eine Hash-Tabelle, die Sie konvertieren können, um einen JSON-string und POST an die /pet-Endpunkt:
$JsonBody = $Body | ConvertTo-Json
$Uri = “https://petstore.swagger.io/v2/pet”
Invoke-RestMethod -ContentType “application/json” -Uri $Uri -Methode-Post -Body $JsonBody
id : 19
Kategorie : @{id=45; name=Was auch immer}
name : Dawg
photoUrls : {string}
tags : {@{id=0; name=string}}
status : verfügbar
Wenn das Objekt erstellt wird, in der Regel erhalten Sie das Objekt, das erstellt wurde, für die Bestätigung.
Mit LÖSCHEN
Die DELETE-Methode löscht die Daten, und die Art und Weise zu tun, dass ist ziemlich ähnlich wie die GET-Methode, wie hier gezeigt:
PS51 > Invoke-RestMethod -Methode LÖSCHEN -ContentType “application/json” -Uri “https://petstore.swagger.io/v2/pet/1”
Just bewusst sein, so dass Sie nicht löschen Sie alles, was Sie brauchen könnten.
Mit PUT
Die PUT-Methode aktualisiert die bereits vorhandenen Daten. Dies geschieht ähnlich wie die POST-Methode, durch die Vorlage eines vollständigen oder teilweisen JSON-Objekt:
PS51> $Body = [PSCustomObject]@{
id = 19
name = “Dawg mit einem neuen Namen”
}
PS51> $JsonBody = $Body | ConvertTo-Json
PS51> $Uri = “https://petstore.swagger.io/v2/pet”
PS51> Invoke-RestMethod -ContentType “application/json” -Uri $Uri -Methode SETZEN -Body $JsonBody
id name photoUrls tags
— —- ——— —-
19 Dawg mit einem neuen Namen {} {}
In der Regel, die REST-API gibt JSON-Objekt mit den verwendeten und/oder Aktualisierung der Daten. Sie können sehen, dass das Objekt wurde aktualisiert, um über die GET-Methode hin:
PS 51> Invoke-RestMethod -ContentType “application/json” -Uri “https://petstore.swagger.io/v2/pet/19”
id : 19
Kategorie : @{id=45; name=Was auch immer}
name : Kumpel mit einem neuen Namen
photoUrls : {string}
tags : {@{id=0; name=string}}
status : verfügbar
Erstellen Von Funktionen
Schreiben Sie sich diese Befehle so, wie Sie sind, kann sehr mühsam und ist nicht wirklich skalierbar. Wenn wir fordern einen Endpunkt mehr als einmal, dann erstellen Sie eine Funktion für Sie. Es ist ziemlich einfach und nur ein paar Zeilen erforderlich:
Function Get-PetstorePet {
[cmdletbinding()]
param(
# Id des Tieres
[Parameter(Mandatory,ValueFromPipeline)]
[int]$Id
)
Begin{}
Prozess{
$RestMethodParams = @{
Uri = “https://petstore.swagger.io/v2/pet/$Id”
ContentType = “application/json”
Method = “GET”
}
Invoke-RestMethod @RestMethodParams
}
End{}
}
Nach der Erstellung Ihrer Funktion, Sie können es nennen, in Ihrem Skript:
PS51> Get-PetstorePet -Id 1
id name photoUrls tags
— —- ——— —-
1 Hund {http://picture.url} {}
Sie können dies tun, für die POST-Methode als auch für die Schaffung einer neuen pet im pet-Shop:
– Funktion Add-PetstorePet {
[cmdletbinding()]
param(
# Id des Tieres
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[int]$Id,
# Name des Haustiers
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[string]$Name,
# Status des Tieres (verfügbar, verkauft, etc)
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[string]$Status,
# Id der Kategorie Haustier
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[int]$CategoryId
# Name der Kategorie Haustier
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[string]$CategoryName,
# URLs auf Fotos von dem Tier
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[string[]]$PhotoUrls,
# Tags die Haustiere als Hash-array: @{Id=1;Name=”Hund”}
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[Hashtable[]]$Tags
)
Begin{}
Prozess{
$Body = @{
id = $Id
Kategorie = @{
id = $CategoryId
name = $Kategoriename
}
name = $Name
photoUrls = $PhotoUrls
tags = $Tags
status = $Status
}
$BodyJson = $Body | ConvertTo-Json
$RestMethodParams = @{
Uri = “https://petstore.swagger.io/v2/pet/”
ContentType = “application/json”
Method = “Post”
Body = $BodyJson
}
Invoke-RestMethod @RestMethodParams
}
End{}
}
Und der Aufruf dieser PowerShell-Funktion danach wird dies sehr lange Aufgabe viel einfacher:
PS51> $AddPetStorePetsParams = @{
Id = 44
Name = “Birdie”
Status = “available”
CategoryId = 50
CategoryName = “Hawks”
PhotoUrls = “https://images.contoso.com/hawk.jpg”
Tags = @(
@{
Id=10
Name=”Kein Adler”
}
)
}
PS51> Add-PetStorePet @AddPetStorePetsParams
id : 44
Kategorie : @{id=50; name=Falken}
name : Birdie
photoUrls : {https://images.contoso.com/hawk.jpg}
tags : {@{id=0}}
status : verfügbar
Die Chancen sind, dass viele der Module, die Sie täglich verwenden, sind aus Funktionen, die nur REST-APIs im hintergrund.
Zusammenfassung
Lernen, wie man REST APIs hauptsächlich darum zu lernen, die Dokumentation zu Lesen. Wir verwendet, FORS-basierte Dokumentation in diesem Beitrag, wie es sich darstellt, wie andere Arten von Dokumentation Aussehen kann als gut.
Auch, konvertieren Sie Ihre API-Aufrufe einer Funktion können Sie sparen eine Menge Zeit, um Ihre Arbeit zu erleichtern, und Ihre Skripte Reiniger.