Utilizzando Api REST per estendere il vostro script è una funzionalità utile per implementare. È possibile ottenere l’accesso a nuove funzionalità e la possibilità di creare nuovi e più avanzati script espandere.
Ma l’esperienza per molti quando si inizia a utilizzare Api REST in script è che si sente abbastanza goffo e innaturale. In questo post vogliamo discutere di:
- Quello che una API REST è
- Come leggere la forma più comune della documentazione
- Come utilizzare una API REST con PowerShell
- Alcuni trucchi e suggerimenti su come rendere più facile e migliore esperienza
Che cosa È il RESTO?
RESTO, o RESTful Api, è un’API che utilizza le richieste HTTP per recuperare, aggiungere, eliminare o modificare i dati nei diversi servizi.
Quello che vogliamo fare con i dati è di solito deciso da che cosa HTTP metodo che si utilizza. Qui è riportato un elenco sintetico dei metodi HTTP, e ciò che essi sono utilizzati per fare un REST API:
- GET—a Leggere
- POST—Creare
- PATCH di aggiornamento Parziale/modificare
- METTERE—Aggiornare/sostituire
- Elimina—per ELIMINARE
I dati restituiti da una API REST è di solito restituiti in formato JSON.
Ora, cominciamo con la nostra prima chiamata di API!
La lettura di Documenti
Imparare a leggere e interpretare la documentazione per le diverse Api REST è essenziale per il loro utilizzo. Fortunatamente, se si sa leggere, uno stile di documentazione, si può imparare rapidamente come leggere gli altri.
Stiamo usando petstore.spavalderia.io in questo articolo, come si utilizza il popolare Spavalderia quadro che è abbastanza comune incontrare nel mondo reale.
L’immagine precedente mostra le informazioni essenziali sull’endpoint REST API:
- Metodo HTTP—GET/POST/CANCELLARE, etc.
- URL relativo al RESTO endpoint API (URL di Base è di solito in cima alla pagina di documentazione)
- Una breve descrizione
Entrare nei Dettagli
La prima pagina della documentazione è grande, e di solito si può eseguire la maggior parte delle chiamate che richiedono il metodo HTTP GET con l’informazione. Ma i metodi come POST e di solito richiedono che si fa clic e di espandere la fila per ottenere ulteriori informazioni.
Se si fa clic su una delle righe, si è presentato con le informazioni che assomiglia a questo:
Qui, abbiamo presentato l’endpoint REST in grado di creare un nuovo animale domestico oggetto. Si specifica come il JSON dovrebbe guardare che è stata fornita nel corpo del POST, e che tipo di contenuto si accetta. Altri RESTO endpoint specifica che è di diversi parametri, quali il tipo di dati dovrebbe essere, etc.
Che le nozioni di base per la lettura della documentazione. Ora che è chiaro, è il momento di iniziare a utilizzare Api REST con PowerShell.
GET(ting) Dati
Utilizzando Api REST con PowerShell è di solito abbastanza semplice, e si sta utilizzando built-in cmdlet in modo che nessun extra moduli sono necessari. Si sta andando a recuperare i dati utilizzando il metodo GET /pet/{petId} endpoint.
Se si espande il /pet/{petId} endpoint nella documentazione, si può vedere che {petId} in realtà è un parametro che assume un valore integer.
Che rende la URL per il recupero dell’animale oggetto con id 1: https://petstore.swagger.io/v2/pet/1
SWAGGER RESTO documentazione delle API di solito si presenta l’URL di base in cima alla pagina.
Ora, cominciamo con PowerShell. Aprire una finestra di Terminale e digitare:
PS51 > Invoke-RestMethod -Metodo GET-content-type “application/json” -Uri “https://petstore.swagger.io/v2/pet/1”
id : 1
categoria : @{id=0; nome=string}
nome : pecorina
photoUrls : {string}
tags : {@{id=0; nome=string}}
stato : disponibile
Invoke-RestMethod converte JSON restituito automaticamente a un oggetto, come il tipo di contenuto “application/json” è restituito nella risposta dal server.
Errore 404 – Non trovato, di solito significa che l’oggetto non può essere trovato, non che l’URL digitato in modo errato.
Ora avete completato con successo il primo RESTO chiamata API. Ma solo essere in grado di OTTENERE i dati è piuttosto limitante, quindi cerchiamo di creare qualcosa con il metodo POST.
La creazione di un Oggetto con il Metodo POST
Il metodo POST è più comunemente utilizzato per creare, ad esempio la creazione di utenti o voci, etc. Una richiesta POST invia un CORPO contenente le informazioni per il RESTO endpoint, di solito in formato JSON, ma può anche essere come un modulo con codifica URL.
Si sta andando a imparare come creare un oggetto JSON che si può POSTARE al /pet endpoint.
Si può vedere come il JSON si suppone a guardare se si espande il POST /pet riga nella documentazione.
Iniziamo con la creazione di una tabella hash che poi possiamo convertire un oggetto JSON. Raw JSON deve essere evitato in script di PowerShell becaise è limitando la sua capacità.
$Body = @{
id = 19
categoria = @{
id = 45
name = “Qualunque”
}
name = “Bischero”
photoUrls = @(
“stringa”
)
tags = @(
@{
id = 0
name = “string”
}
)
status = “disponibile”
}
Se si stanno avendo un momento difficile la creazione di una tabella hash che converte in JSON si desidera installare il PsdKit modulo e utilizzare il comando: $JsonString | ConvertTo-Psd
Si dispone ora di una hashtable che si può convertire in una stringa JSON e POST al /pet endpoint:
$JsonBody = $Corpo | ConvertTo-Json
$Uri = “https://petstore.swagger.io/v2/pet”
Invoke-RestMethod -ContentType “application/json” -Uri $Uri -Metodo di Post -Corpo $JsonBody
id : 19
categoria : @{id=45; nome=Qualunque cosa}
nome : Dawg
photoUrls : {string}
tags : {@{id=0; nome=string}}
stato : disponibile
Quando viene creato l’oggetto, in genere si riceve l’oggetto è stato creato per la conferma.
Utilizzando ELIMINARE
Il metodo DELETE cancella i dati, e il modo di fare che è molto simile al metodo GET, come mostrato qui:
PS51 > Invoke-RestMethod -Metodo di ELIMINAZIONE di ContentType “application/json” -Uri “https://petstore.swagger.io/v2/pet/1”
Basta essere consapevoli, così non eliminare tutto ciò che potrebbe essere necessario.
Utilizzo di METTERE
Il metodo PUT rielabora i dati già disponibili. Questo viene fatto allo stesso modo il metodo POST, inviando una completa o parziale di oggetto JSON:
PS51> $Body = [PSCustomObject]@{
id = 19
name = “Dawg con un nuovo nome”
}
PS51> $JsonBody = $Corpo | ConvertTo-Json
PS51> $Uri = “https://petstore.swagger.io/v2/pet”
PS51> Invoke-RestMethod -ContentType “application/json” -Uri $Uri -Metodo di METTERE il Corpo $JsonBody
id nome photoUrls tag
— —- ——— —-
19 Dawg con un nuovo nome {} {}
Di solito, il RESTO API restituisce un oggetto JSON con usato e/o aggiornamento dei dati. Si può vedere che l’oggetto è stato aggiornato utilizzando il metodo GET verso di essa:
PS 51> Invoke-RestMethod -ContentType “application/json” -Uri “https://petstore.swagger.io/v2/pet/19”
id : 19
categoria : @{id=45; nome=Qualunque cosa}
nome : Dawg con un nuovo nome
photoUrls : {string}
tags : {@{id=0; nome=string}}
stato : disponibile
Creazione Di Funzioni
La scrittura di questi comandi come sono può diventare molto noioso e non è realmente scalabile. Se si sta chiamando un endpoint più di una volta, quindi creare una funzione per farlo. E ‘ abbastanza semplice e solo poche righe sono necessari:
La Funzione Get-PetstorePet {
[attributo()]
param(
# Id dell’animale domestico
[Parametro(Obbligatorio,ValueFromPipeline)]
[int]$Id
)
Begin{}
Processo{
$RestMethodParams = @{
Uri = “https://petstore.swagger.io/v2/pet/$Id”
ContentType = “application/json”
Method = “GET”,
}
Invoke-RestMethod @RestMethodParams
}
End{}
}
Dopo la creazione di una funzione, si può chiamare lo script:
PS51> Get-PetstorePet -Id 1
id nome photoUrls tag
— —- ——— —-
1 Pecorina {http://picture.url} {}
Si può fare questo per il metodo POST e per la creazione di un nuovo animale domestico in un negozio di animali:
Funzione Add-PetstorePet {
[attributo()]
param(
# Id dell’animale domestico
[Parametro(Obbligatorio,ValueFromPipelineByPropertyName)]
[int]$Id,
# Nome della pet
[Parametro(Obbligatorio,ValueFromPipelineByPropertyName)]
[string]$Nome,
# Status di animale domestico (disponibile, venduto ecc)
[Parametro(Obbligatorio,ValueFromPipelineByPropertyName)]
[string]$Stato,
# Id della categoria pet
[Parametro(Obbligatorio,ValueFromPipelineByPropertyName)]
[int]$Idcategoria
# Nome della pet categoria
[Parametro(Obbligatorio,ValueFromPipelineByPropertyName)]
[string]$Nomecategoria,
# Url per le foto di animali domestici
[Parametro(Obbligatorio,ValueFromPipelineByPropertyName)]
[string[]]$PhotoUrls,
# Tag di animali domestici come hashtable matrice: @{Id=1;Nome=”Cane”}
[Parametro(Obbligatorio,ValueFromPipelineByPropertyName)]
[Hashtable[]]$Tags
)
Begin{}
Processo{
$Body = @{
id = $Id
categoria = @{
id = $Idcategoria
nome = $nome Categoria
}
nome = $Nome
photoUrls = $PhotoUrls
tags = $Tags
stato = $Status
}
$BodyJson = $Corpo | ConvertTo-Json
$RestMethodParams = @{
Uri = “https://petstore.swagger.io/v2/pet/”
ContentType = “application/json”
Method = “Post”
Body = $BodyJson
}
Invoke-RestMethod @RestMethodParams
}
End{}
}
E di chiamare questo PowerShell funzione poi è molto lunga compito molto più facile:
PS51> $AddPetStorePetsParams = @{
Id = 44
Name = “Birdie”
Status = “disponibile”
Idcategoria = 50
Categoria = “Falchi”
PhotoUrls = “https://images.contoso.com/hawk.jpg”
Tags = @(
@{
Id=10
Name=”Non aquile”
}
)
}
PS51> Aggiungi-PetStorePet @AddPetStorePetsParams
id : 44
categoria : @{id=50; nome=Falchi}
nome : Birdie
photoUrls : {https://images.contoso.com/hawk.jpg}
tags : {@{id=0}}
stato : disponibile
Le probabilità sono che molti moduli che si utilizza tutti i giorni sono fatti di funzioni che utilizza solo Api REST in background.
Riepilogo
Imparare l’uso di Api REST è principalmente imparare a leggere la documentazione. Abbiamo usato la SPAVALDERIA a base di documentazione in questo post, in quanto rappresenta come altri stili di documentazione può guardare come bene.
Inoltre, la conversione di chiamate API per una funzione può risparmiare un sacco di tempo, rendere il vostro lavoro più facile, e il tuo script cleaner.