Usar a API REST para estender seus scripts é um recurso útil para implementar. Você pode obter acesso a novas funcionalidades e as possibilidades de criação de novos scripts mais avançados são expandidas.
Mas a experiência de muitos ao começar a usar a API REST em scripts é que ela parece um tanto desajeitada e pouco natural. Nesta postagem, discutimos:
- O que é uma API REST
- Como ler a forma mais comum de documentação
- Como usar uma API REST com PowerShell
- Algumas dicas e truques para tornar a experiência melhor e mais fácil
O que é REST?
DESCANSO, o API RESTful, é uma API que usa solicitações HTTP para pesquisar, adicionar, excluir ou manipular dados em diferentes serviços.
O que queremos fazer com os dados geralmente é decidido pelo que Método HTTP O que você usa. Aqui está uma lista resumida de métodos HTTP e o que eles são usados para fazer em uma API REST:
- GET - Leia
- PARA POSTAR: Criar
- CORREÇÃO: melhoria / modificação parcial
- POR: atualizar ou substituir
- EXCLUIR: Retirar
Os dados retornados por uma API REST geralmente são retornados no formato JSON.
Agora, vamos começar com nossa primeira chamada de API!
Leia a documentação
Aprender a ler e interpretar a documentação de diferentes APIs REST é essencial para usá-las. Por sorte, se você sabe como ler um estilo de documento, pode aprender rapidamente a ler outros.
Estamos usando petstore.swagger.io neste post, uma vez que usa o popular Strut estrutura que é bastante comum encontrar no mundo real.
A imagem acima mostra as informações mais essenciais sobre os endpoints da API REST:
- Método HTTP: PEGUE / PUBLICAR / EXCLUIR, etc.
- URL relativo ao endpoint da API REST (a URL base geralmente é apresentada no topo da página de documentação)
- Uma breve descrição
Entre nos detalhes
A primeira página da documentação é excelente e, em geral, você pode fazer a maioria das chamadas que exigem o método HTTP GET com essas informações. Mas métodos como POST e SET geralmente exigem que você clique e expanda a linha para obter mais informações.
Se você clicar em uma das linhas, são apresentados a você informações semelhantes a esta:
Aqui, introduzimos o endpoint REST, que pode criar um novo objeto de estimação. Especifica como o JSON que foi fornecido no corpo do POST deve ser exibido e que tipo de conteúdo ele aceita. Outros endpoints REST especificam quais são seus diferentes parâmetros, que tipo de dados deve ser, etc.
Esse é o básico para ler a documentação. Agora que está claro, é hora de começar a usar APIs REST com o PowerShell.
PEGUE (ting) seus primeiros dados
O uso de APIs REST com o PowerShell geralmente é bastante simples e você está usando cmdlets internos, então não são necessários módulos adicionais. Você obterá dados através do método GET em / bicho de estimação / {petId} ponto final.
Se você expandir o / bicho de estimação / {petId} endpoint na documentação, pode ver isso {petId} é na verdade um parâmetro que recebe um inteiro.
Isso faz com que o url procure o objeto pet com id 1: https://petstore.swagger.io/v2/pet/1
A documentação da API SWAGGER REST geralmente apresenta o URL base no topo da página.
Agora, vamos começar com PowerShell. Abra uma janela do Terminal e entre:
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 o JSON retornado automaticamente em um objeto, já que o tipo de conteúdo “inscrição / json” é retornado na solução do servidor.
Error 404 - Not foundgeralmente significa que o objeto não pode ser encontrado, não que o url esteja com erros ortográficos.
Agora você fez sua primeira chamada REST API com sucesso. Mas apenas ser capaz de obter dados é bastante limitante, portanto, vamos criar algo com o método POST.
Crie um objeto com o método POST
O método POST é mais comumente usado para criar, como criar usuários ou entradas, etc. Uma solicitação POST envia um BODY contendo informações para o endpoint REST, geralmente em formato JSON, mas também pode ser um formulário codificado por URL.
Você aprenderá como criar um objeto JSON que pode ser POST no /mascote ponto final.
Você pode ver a aparência do JSON se expandir o PUBLICAR / mascote linha na documentação.
Vamos começar criando uma tabela hash que podemos posteriormente converter em um objeto JSON. JSON bruto deve ser evitado em scripts do PowerShell, pois limita seus recursos.
$Body = @{
id = 19
category = @{
id = 45
name = "Whatever"
}
name = "Dawg"
photoUrls = @(
"string"
)
tags = @(
@{
id = 0
name = "string"
}
)
status = "available"
}Se você está tendo dificuldade para criar uma tabela hash que é convertida para o JSON que você deseja, instale o PsdKit módulo e use o comando:
$JsonString | ConvertTo-Psd
Agora você tem uma tabela de hash que pode converter em uma string JSON e POST para o /mascote ponto 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 : availableQuando o objeto é criado, receber regularmente o objeto que foi criado para commit.
Usando DELETE
O método DELETE remove os dados, e a maneira de fazer isso é bastante semelhante ao método GET, conforme demonstrado aqui:
PS51 > Invoke-RestMethod -Method DELETE -ContentType "application/json" -Uri "https://petstore.swagger.io/v2/pet/1"Apenas lembre-se de não excluir nada que você possa precisar.
Usando PUT
O método PUT atualiza dados já existentes. Isso é feito de forma semelhante ao método POST, enviando um objeto JSON completo ou 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 {} {}Em geral, a API REST retorna um objeto JSON com os dados usados e / o actualizados. Você pode ver que o objeto foi atualizado usando o método GET para ele:
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 : availableCriando funções
Escrever esses comandos como estão pode se tornar um tanto entediante e não é verdadeiramente escalonável. Se chamarmos um ponto final mais de uma vez, crie uma função para ele. É bastante simples e apenas algumas linhas são necessárias:
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{}
}Depois de criar sua função, você pode chamá-lo em seu script:
PS51> Get-PetstorePet -Id 1
id name photoUrls tags
-- ---- --------- ----
1 Doggie {http://picture.dirección url} {} Você pode fazer isso para o método POST e para criar um novo animal de estimação na loja de animais:
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 chamar essa função do PowerShell depois torna essa tarefa bastante longa muito mais fácil:
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 : availableProvavelmente, muitos dos módulos que você usa diariamente são feitos de funções que usam APIs REST apenas em segundo plano.
Resumo
Aprender a usar APIs REST é principalmente aprender a ler a documentação. Usamos documentação baseada em SWAGGER nesta postagem, uma vez que representa a aparência de outros estilos de documentação.
Ao mesmo tempo, transformar suas chamadas de API em uma função pode economizar muito tempo, torne seu trabalho mais fácil e limpe seus scripts.
