Introdução às APIs REST no PowerShell

Brien Posey | 04 de agosto de 2023

A API REST, também conhecida como API RESTful, é um protocolo usado para interagir com aplicações web. Embora as chamadas REST normalmente sejam feitas por meio de um navegador ou aplicativo, você também pode usar o PowerShell para interagir com uma API REST.

Ao usar uma API REST, você deve informar à API o método que deseja usar. Por exemplo, o método GET é usado para recuperar dados de um aplicativo, enquanto o método POST é usado para criar novos dados. Outros métodos REST incluem PUT, PATCH e DELETE.

Relacionado: Como construir scripts PowerShell habilitados para ChatGPT

Ao enviar uma solicitação para uma API REST, você precisará fornecer um corpo de solicitação devidamente estruturado. A API retornará então uma resposta a essa solicitação. A estrutura do corpo depende do método específico utilizado.

Como este artigo é destinado a iniciantes, vamos nos concentrar no uso do método GET para recuperar dados de uma API REST.

Estou me concentrando no método GET porque ele não requer a criação de uma tabela hash, ao contrário de alguns outros métodos. Supondo que a API não exija autenticação, você só precisa especificar o URI da API e o método que deseja usar.

De certa forma, porém, isso simplifica um pouco as coisas. Em cenários reais, as solicitações GET quase sempre incluem parâmetros que especificam os dados que você deseja recuperar da API.

Como exemplo, vejamos uma API relacionada a um jogo trivial localizada em https://opentdb.com/api.php. Encontrei a API listada em uma página da Web com vários exemplos de API.

Para obter perguntas triviais da API usando uma solicitação GET, você precisa incluir dois valores: Valor e Categoria. Esses valores normalmente estão na solicitação HTTPS.

Aqui está um exemplo de tal solicitação e os resultados: https://opentdb.com/api.php?amount=1&category=18. Ao fazer essa solicitação, a API retorna dados brutos no formato JSON, conforme mostrado na Figura 1.

Figura 1:Esta chamada de API baseada em navegador retorna dados brutos no formato JSON.

No PowerShell, você pode inserir o URI exatamente como listado acima. No entanto, se você estivesse criando um jogo de perguntas e respostas baseado no PowerShell, provavelmente não desejaria fazer sempre a mesma chamada de URI. Em vez disso, você pode armazenar os valores de Quantidade e Categoria em variáveis ​​para atualizá-los à medida que o jogo avança. Isso exigiria o uso de manipulação de strings para construir o URI dinamicamente.

Aqui está um exemplo de como você poderia fazer isso no PowerShell:

Você pode ver esses comandos e o URI resultante na Figura 2.

Figura 2.É assim que você forma um URI personalizado.

Depois de formar o URI, você pode especificar o método a ser usado. Você pode especificar um método diretamente, mas prefiro armazenar o método em uma variável como esta:

Para consultar a API, você só precisa usar o cmdlet Invoke-RestMethod do PowerShell e especificar o método e o URI:

Você pode ver esse comando em ação na Figura 3. Observe que a API retorna os resultados no formato JSON.

Figura 3.Uma pergunta trivial foi recuperada de um aplicativo da web usando uma API REST.

Normalmente, isso é tudo o que é necessário para enviar uma solicitação GET para uma API REST. Em alguns casos em que a API requer autenticação, pode ser necessário incluir o parâmetro -Credential junto com as credenciais.

Antes de concluir este artigo, vamos ver como converter os dados recuperados em um formato utilizável.

A abordagem mais simples é mapear o cmdlet Invoke-RestMethod para uma variável. Por exemplo, você pode usar o seguinte comando:

Ao usar esta técnica, o PowerShell converte automaticamente os dados JSON recebidos em formato Object, o que oferece diversas vantagens. Para visualizar os dados, basta digitar $APICall.Results. Se precisar acessar campos de dados específicos, você poderá usar o cmdlet Select-Object.

Figura 4.Os dados foram gravados em um objeto do PowerShell e podem ser acessados ​​como qualquer outro dado do PowerShell.

Sobre o autor

Mais informações sobre formatos de texto