Die Verwendung der REST-API zum Erweitern Ihrer Skripte ist eine nützliche Funktion, die implementiert werden muss. Sie erhalten Zugriff auf neue Funktionalitäten und die Möglichkeiten, neue, erweiterte Skripte zu erstellen, werden erweitert.
Aber die Erfahrung vieler, wenn sie beginnen, die REST-API in Skripten zu verwenden, ist, dass es sich ziemlich klobig und unnatürlich anfühlt. In diesem Beitrag diskutieren wir:
- Was ist eine REST-API?
- So lesen Sie die gängigste Form der Dokumentation
- So verwenden Sie eine REST-API mit PowerShell
- Einige Tipps und Tricks, wie Sie es zu einem besseren und einfacheren Erlebnis machen können
Was ist REST?
SICH AUSRUHEN, o API RESTful, ist eine API, die HTTP-Anfragen zum Suchen verwendet, hinzufügen, Daten in verschiedenen Diensten löschen oder manipulieren.
Was wir mit den Daten machen wollen, wird in der Regel durch was bestimmt HTTP-Methode was benutzt du. Hier ist eine zusammenfassende Liste von HTTP-Methoden und deren Verwendung in einer REST-API:
- Zu lesen bekommen
- ZUM POSTEN: schaffen
- PATCH: Aktualisierung / Teilmodifikation
- STELLEN: aktualisieren oder ersetzen
- LÖSCHEN: Entfernen
Die von einer REST-API zurückgegebenen Daten werden im Allgemeinen im JSON-Format zurückgegeben.
Jetzt, Beginnen wir mit unserem ersten API-Aufruf!
Lesen Sie die Dokumente
Es ist wichtig, die Dokumentation verschiedener REST-APIs zu lesen und zu interpretieren, um sie verwenden zu können. Glücklicherweise, wenn Sie wissen, wie man einen Dokumentstil liest, kann schnell lernen andere zu lesen.
Wir benutzen petstore.swagger.io in diesem Beitrag, da es das beliebte verwendet Strebe Framework, das in der realen Welt recht häufig zu finden ist.
La imagen anterior muestra la información más esencial sobre los puntos finales de la API REST:
- HTTP-Methode: GET / POST / DELETE, usw.
- URL relativa al punto final de la API REST (la URL base de forma general se presenta en la parte de arriba de la página de documentación)
- Una breve descripción
Entrar en los detalles
La primera página de la documentación es excelente y, im Allgemeinen, puede realizar la mayoría de las llamadas que requieren el método HTTP GET con esa información. Bei Methoden wie POST und SET müssen Sie jedoch im Allgemeinen auf die Zeile klicken und sie erweitern, um weitere Informationen zu erhalten.
Wenn Sie auf eine der Zeilen klicken, Ihnen werden ähnliche Informationen angezeigt:
Hier, Wir führen einen REST-Endpunkt ein, der ein neues Haustierobjekt erstellen kann. Gibt an, wie das im Hauptteil des POST bereitgestellte JSON aussehen soll und welche Art von Inhalt es akzeptiert. Andere REST-Endpunkte geben ihre unterschiedlichen Parameter an, qué tipo de datos debería ser, usw.
Eso es lo básico para leer la documentación. Ahora que es claro, es hora de comenzar a utilizar las API REST con PowerShell.
OBTENGA (ting) sus primeros datos
El uso de API REST con PowerShell suele ser bastante sencillo y está usando cmdlets integrados, por lo que no se necesitan módulos adicionales. Obtendrá datos a través de el método GET en / pet / {petId} punto final.
Si expande el / pet / {petId} endpoint en la documentación, puede ver que {petId} es en realidad un parámetro que toma un número entero.
Das macht die URL, um mit der ID nach dem Haustierobjekt zu suchen 1: https://petstore.swagger.io/v2/pet/1
Die SWAGGER REST API-Dokumentation zeigt im Allgemeinen die Basis-URL oben auf der Seite an.
Jetzt, Beginnen wir mit PowerShell. Öffnen Sie ein Terminalfenster und geben Sie ein:
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 wandelt das automatisch zurückgegebene JSON in ein Objekt um, dado que el tipo de contenido “application / json” se devuelve en la solución del servidor.
Error 404 - Not foundbedeutet im Allgemeinen, dass das Objekt nicht gefunden werden kann, nicht dass die URL falsch geschrieben ist.
Sie haben nun erfolgreich Ihren ersten REST-API-Aufruf durchgeführt. Aber nur in der Lage zu sein, Daten abzurufen, ist ziemlich einschränkend, deshalb erstellen wir etwas mit der POST-Methode.
Erstellen Sie ein Objekt mit der POST-Methode
Die POST-Methode wird am häufigsten verwendet, um, So erstellen Sie Benutzer oder Einträge, usw. Eine POST-Anfrage sendet einen BODY mit Informationen an den REST-Endpunkt, generell im JSON-Format, es kann aber auch ein URL-codiertes Formular sein.
Sie erfahren, wie Sie ein JSON-Objekt erstellen, das Sie per POST an das /Maskottchen punto final.
Sie können sehen, wie der JSON aussehen soll, wenn Sie das erweitern POST / Maskottchen Zeile in der Dokumentation.
Beginnen wir mit der Erstellung einer Hash-Tabelle, die wir später in ein JSON-Objekt konvertieren können. Raw JSON sollte in PowerShell-Skripten vermieden werden, da es seine Fähigkeiten einschränkt.
$Body = @{
id = 19
category = @{
id = 45
name = "Whatever"
}
name = "Dawg"
photoUrls = @(
"string"
)
tags = @(
@{
id = 0
name = "string"
}
)
status = "available"
}Wenn Sie Schwierigkeiten haben, eine Hash-Tabelle zu erstellen, die in das gewünschte JSON konvertiert wird, installiere das PSDKit Modul und verwenden Sie den Befehl:
$JsonString | ConvertTo-Psd
Ahora dispone de una tabla hash que puede convertir en una cadena JSON y POST en el /Maskottchen punto final:
$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 : availableCuando se crea el objeto, regularmente recibe el objeto que se creó para su confirmación.
Usando DELETE
El método DELETE elimina datos, y la forma de hacerlo es bastante semejante al método GET como se demuestra aquí:
PS51 > Invoke-RestMethod -Method DELETE -ContentType "application/json" -Uri "https://petstore.swagger.io/v2/pet/1"Solo tenga en cuenta para no borrar nada que pueda necesitar.
Usando PUT
El método PUT actualiza los datos ya existentes. Esto se hace de manera semejante al método POST, enviando un objeto JSON completo o parcial:
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 {} {}Im Allgemeinen, la API REST devuelve un objeto JSON con los datos usados y / o actualizados. Puede ver que el objeto se actualizó usando el método GET hacia él:
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 : availableCreando funciones
Das Schreiben dieser Befehle kann ziemlich mühsam werden und ist nicht wirklich skalierbar. Wenn wir einen Endpunkt mehr als einmal aufrufen, eine Funktion für ihn erstellen. Es ist ganz einfach und es werden nur wenige Zeilen benötigt:
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{}
}Nachdem Sie Ihre Rolle erstellt haben, Sie können es in Ihrem Skript aufrufen:
PS51> Get-PetstorePet -Id 1
id name photoUrls tags
-- ---- --------- ----
1 Doggie {http://picture.dirección url} {} Sie können dies für die POST-Methode tun und ein neues Haustier in der Zoohandlung erstellen:
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{}
}Und das anschließende Aufrufen dieser PowerShell-Funktion erleichtert diese eher langwierige Aufgabe erheblich:
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 : availableHöchstwahrscheinlich bestehen viele der Module, die Sie täglich verwenden, aus Funktionen, die nur REST-APIs im Hintergrund verwenden.
Zusammenfassung
Beim Erlernen der Verwendung von REST-APIs geht es in erster Linie darum, die Dokumentation lesen zu lernen. Wir verwenden in diesem Beitrag SWAGGER-basierte Dokumentation, da es repräsentiert, wie andere Dokumentationsstile aussehen können.
Zur selben Zeit, Wenn Sie Ihre API-Aufrufe in eine Funktion umwandeln, können Sie viel Zeit sparen, erleichtern Sie Ihre Arbeit und bereinigen Sie Ihre Skripte.
