L'utilizzo dell'API REST per estendere i tuoi script è una funzionalità utile da implementare. È possibile accedere a nuove funzionalità e le possibilità di creare nuovi script più avanzati sono ampliate.
Ma l'esperienza per molti quando si inizia a utilizzare l'API REST negli script è che sembra piuttosto goffo e innaturale. In questo post discutiamo:
- Che cos'è un'API REST
- Come leggere la forma più comune di documentazione
- Come utilizzare un'API REST con PowerShell
- Alcuni suggerimenti e trucchi su come renderlo un'esperienza migliore e più semplice
Cos'è REST?
RIPOSO, o API RESTful, è un'API che utilizza le richieste HTTP per la ricerca, Inserisci, eliminare o manipolare i dati in diversi servizi.
Quello che vogliamo fare con i dati è generalmente deciso da cosa Metodo HTTP cosa usi. Ecco un elenco riassuntivo dei metodi HTTP e di cosa sono usati per fare in un'API REST:
- Essere letto
- PER POST: creare
- TOPPA: aggiornamento / modifica parziale
- METTERE: aggiornare o sostituire
- ELIMINA: Rimuovere
I dati restituiti da un'API REST vengono generalmente restituiti in formato JSON.
Ora, iniziamo con la nostra prima chiamata API!
Leggi i documenti
Imparare a leggere e interpretare la documentazione di diverse API REST è essenziale per usarle. fortunatamente, se sai leggere uno stile doc, può imparare rapidamente a leggere gli altri.
stiamo usando animali.swagger.io in questo post, poiché utilizza il popolare Pavoneggiarsi quadro che è abbastanza comune da trovare nel mondo reale.
L'immagine sopra mostra le informazioni più essenziali sugli endpoint dell'API REST:
- Metodo HTTP: OTTENERE / INVIARE / ELIMINA, eccetera.
- URL relativo all'endpoint dell'API REST (l'URL di base è solitamente presentato nella parte superiore della pagina della documentazione)
- Una breve descrizione
Entra nei dettagli
La prima pagina della documentazione è eccellente e, generalmente, è possibile effettuare la maggior parte delle chiamate che richiedono il metodo HTTP GET con tali informazioni. Ma metodi come POST e SET generalmente richiedono di fare clic ed espandere la riga per ottenere maggiori informazioni..
Se fai clic su una delle righe, Ti vengono presentate informazioni simili a questa:
Qui, introduciamo l'endpoint REST che può creare un nuovo oggetto animale domestico. Specifica come dovrebbe apparire il JSON fornito nel corpo del POST e che tipo di contenuto accetta. Altri endpoint REST specificano quali sono i loro diversi parametri, che tipo di dati dovrebbe essere, eccetera.
Queste sono le basi per leggere la documentazione. Ora che è chiaro, è ora di iniziare a utilizzare le API REST con PowerShell.
OTTENERE (cosa) i tuoi primi dati
L'uso delle API REST con PowerShell è in genere piuttosto semplice e si utilizzano i cmdlet integrati, quindi non sono necessari moduli aggiuntivi. Otterrai i dati tramite il metodo GET in / animale domestico / {petId} punto finale.
Se espandi il / animale domestico / {petId} endpoint nella documentazione, puoi vederlo {petId} è in realtà un parametro che accetta un numero intero.
Ciò rende l'URL per cercare l'oggetto animale domestico con id 1: https://petstore.swagger.io/v2/pet/1
La documentazione dell'API REST SWAGGER generalmente presenta l'URL di base nella parte superiore della pagina.
Ora, iniziamo con PowerShell. Apri una finestra di Terminale e inserisci:
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 converte il JSON restituito automaticamente in un oggetto, dal tipo di contenuto “applicazione / json” viene restituito nella soluzione server.
Error 404 - Not foundgeneralmente significa che l'oggetto non può essere trovato, non che l'url sia scritto male.
Ora hai effettuato con successo la tua prima chiamata API REST. Ma solo essere in grado di OTTENERE dati è piuttosto limitante, quindi creiamo qualcosa con il metodo POST.
Crea un oggetto con il metodo POST
Il metodo POST è più comunemente usato per creare, come creare utenti o voci, eccetera. Una richiesta POST invia un BODY contenente informazioni all'endpoint REST, generalmente in formato JSON, ma può anche essere un modulo con codifica URL.
Imparerai come creare un oggetto JSON che puoi POST sul /mascotte punto finale.
Puoi vedere come dovrebbe apparire il JSON se espandi il INVIARE / mascotte riga nella documentazione.
Iniziamo creando una tabella hash che possiamo poi convertire in un oggetto JSON. JSON non elaborato dovrebbe essere evitato negli script di PowerShell in quanto limita le sue capacità.
$Body = @{
id = 19
category = @{
id = 45
name = "Whatever"
}
name = "Dawg"
photoUrls = @(
"string"
)
tags = @(
@{
id = 0
name = "string"
}
)
status = "available"
}Se hai difficoltà a creare una tabella hash che converta nel JSON che desideri, installare il PsdKit modulo e utilizzare il comando:
$JsonString | ConvertTo-Psd
Ora hai una tabella hash che puoi convertire in una stringa JSON e POST in /mascotte punto finale:
$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 : availableQuando l'oggetto è stato creato, ricevere regolarmente l'oggetto che è stato creato per il commit.
Usando DELETE
Il metodo DELETE rimuove i dati, e il modo per farlo è abbastanza simile al metodo GET come mostrato qui:
PS51 > Invoke-RestMethod -Method DELETE -ContentType "application/json" -Uri "https://petstore.swagger.io/v2/pet/1"Ricorda solo di non eliminare nulla di cui potresti aver bisogno.
Usando PUT
Il metodo PUT aggiorna i dati già esistenti. Questo viene fatto in modo simile al metodo POST, invio di un oggetto JSON completo o parziale:
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 {} {}Generalmente, l'API REST restituisce un oggetto JSON con i dati utilizzati e / o aggiornato. Puoi vedere che l'oggetto è stato aggiornato usando il metodo GET verso di esso:
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 : availableCreazione di funzioni
Scrivere questi comandi così com'è può diventare piuttosto noioso e non è veramente scalabile. Se chiamiamo un punto finale più di una volta, creare una funzione per lui. È abbastanza semplice e sono necessarie solo poche righe:
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{}
}Dopo aver creato il tuo ruolo, puoi chiamarlo nel tuo script:
PS51> Get-PetstorePet -Id 1
id name photoUrls tags
-- ---- --------- ----
1 Doggie {http://picture.dirección url} {} Puoi farlo per il metodo POST e per creare un nuovo animale domestico nel negozio di animali:
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{}
}E chiamare in seguito questa funzione PowerShell rende questo compito piuttosto lungo molto più semplice:
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 : availableMolto probabilmente, molti dei moduli che usi quotidianamente sono costituiti da funzioni che utilizzano solo API REST in background.
Riepilogo
Imparare a usare le API REST significa principalmente imparare a leggere la documentazione. Usiamo la documentazione basata su SWAGGER in questo post, poiché rappresenta l'aspetto che possono avere altri stili di documentazione.
Allo stesso tempo, trasformare le tue chiamate API in una funzione può farti risparmiare un sacco di tempo, semplifica il tuo lavoro e pulisci i tuoi script.
