Nesta aula, vamos mergulhar no consumo de APIs REST utilizando o PowerShell. Você aprenderá a usar o cmdlet Invoke-RestMethod para fazer requisições HTTP, lidar com autenticação, processar respostas em JSON e apresentar os dados de forma clara. Este é um conhecimento essencial para automatizar tarefas, integrar sistemas e extrair informações de serviços web modernos.

O PowerShell oferece uma maneira elegante e poderosa de interagir com APIs, graças à sua integração nativa com JSON e HTTP. Vamos construir um projeto prático passo a passo, consumindo uma API pública, para que você veja todos os conceitos em ação.

Invoke-RestMethod

O cmdlet Invoke-RestMethod é a ferramenta principal para enviar requisições HTTP e receber respostas formatadas. Ele automaticamente converte a resposta JSON em objetos do PowerShell, facilitando o acesso aos dados. Diferente de Invoke-WebRequest, que retorna o conteúdo bruto, o Invoke-RestMethod já interpreta o JSON, XML ou outros formatos.

Sua sintaxe básica é simples: Invoke-RestMethod -Uri 'https://api.exemplo.com/dados'. Você pode especificar o método HTTP (GET, POST, PUT, DELETE) usando o parâmetro -Method, e enviar dados no corpo da requisição com -Body. O cmdlet também aceita cabeçalhos personalizados, credenciais e até mesmo um tempo limite.

Exemplo prático: vamos buscar dados de uma API pública de piadas (https://v2.jokeapi.dev/joke/Any).

$resposta = Invoke-RestMethod -Uri 'https://v2.jokeapi.dev/joke/Any'
$resposta | Format-List

O resultado será um objeto com propriedades como category, type, setup e delivery (para piadas de duas partes). Isso mostra como o JSON é convertido automaticamente.

Autenticação

Muitas APIs exigem autenticação para garantir que apenas usuários autorizados acessem os dados. O PowerShell oferece várias formas de autenticar em APIs REST. As mais comuns são: cabeçalho de autorização com token (Bearer), chave de API (API Key) e autenticação básica (usuário/senha).

Para adicionar um cabeçalho de autorização, usamos o parâmetro -Headers com um dicionário. Por exemplo, para um token Bearer:

$headers = @{
    'Authorization' = 'Bearer SEU_TOKEN_AQUI'
}
$resposta = Invoke-RestMethod -Uri 'https://api.exemplo.com/privado' -Headers $headers

Para uma chave de API simples, muitas vezes ela é enviada no cabeçalho X-API-Key ou como parâmetro de consulta. Já a autenticação básica pode ser feita com o parâmetro -Credential ou construindo o cabeçalho manualmente.

Exemplo com chave de API no cabeçalho:

$headers = @{
    'X-API-Key' = 'SUA_CHAVE'
}
$resposta = Invoke-RestMethod -Uri 'https://api.exemplo.com/dados' -Headers $headers

Se a API usar autenticação básica, você pode criar uma credencial com Get-Credential e passá-la ao parâmetro -Credential. Para maior segurança, nunca coloque tokens diretamente no código; use variáveis de ambiente ou cofres de segredos.

Processando JSON

O JSON (JavaScript Object Notation) é o formato mais comum em APIs REST. O PowerShell converte automaticamente o JSON em objetos, mas às vezes você precisa processar a estrutura para extrair informações específicas. Com objetos, você pode acessar propriedades diretamente, filtrar listas, e até mesmo converter de volta para JSON quando necessário.

Quando a resposta é um array, você pode iterar com ForEach-Object ou usar cmdlets como Where-Object para filtrar. Por exemplo, se a API retorna uma lista de usuários, podemos selecionar apenas os ativos.

Vamos usar a API pública 'https://jsonplaceholder.typicode.com/users' para listar nomes e e-mails:

$usuarios = Invoke-RestMethod -Uri 'https://jsonplaceholder.typicode.com/users'
$usuarios | ForEach-Object {
    [PSCustomObject]@{
        Nome = $_.name
        Email = $_.email
    }
} | Format-Table -AutoSize

Para converter um objeto de volta para JSON (útil para enviar dados), use ConvertTo-Json:

$dados = [PSCustomObject]@{
    nome = 'João'
    idade = 30
}
$json = $dados | ConvertTo-Json
$json

Lidar com JSON aninhado também é simples: basta acessar as propriedades como se fossem objetos. Por exemplo, se a resposta tem endereco.cidade, você pode acessar com $_.endereco.cidade.

Saída

Após obter e processar os dados, você precisa apresentá-los de forma legível. O PowerShell oferece vários cmdlets de formatação, como Format-Table, Format-List e Format-Wide. Você também pode exportar para CSV, HTML ou até mesmo gerar relatórios.

Para uma saída tabular, use Format-Table com as propriedades desejadas. Para listas detalhadas, Format-List é útil. Exemplo:

$usuarios = Invoke-RestMethod -Uri 'https://jsonplaceholder.typicode.com/users'
$usuarios | Format-Table -Property name, email -AutoSize

Se quiser exportar para CSV, use Export-Csv:

$usuarios | Export-Csv -Path 'usuarios.csv' -NoTypeInformation

Para saída em HTML, use ConvertTo-Html e depois salve em arquivo. Isso é ótimo para relatórios:

$usuarios | ConvertTo-Html -Property name, email | Out-File 'usuarios.html'

Lembre-se de que a saída padrão do PowerShell é a tela, mas você pode redirecionar para arquivos ou usar cmdlets de exportação. Sempre considere o público da saída: se for para humanos, use tabelas; se for para máquinas, use JSON ou CSV.

Boas Práticas e Observações Finais

Ao consumir APIs, é importante tratar erros e lidar com respostas inesperadas. Use try/catch para capturar exceções e verificar o status HTTP. O PowerShell 7+ tem o parâmetro -StatusCodeVariable para capturar o código de status.

Exemplo de tratamento de erro:

try {
    $resposta = Invoke-RestMethod -Uri 'https://api.exemplo.com/dados' -ErrorAction Stop
} catch {
    Write-Error "Falha na requisição: $_"
}

Além disso, respeite os limites de rate limit das APIs e use cache quando possível. Documente seus scripts e mantenha segredos fora do código. Com essas práticas, você estará pronto para construir integrações robustas.

Exercícios

  1. Use o Invoke-RestMethod para buscar uma piada da API JokeAPI (https://v2.jokeapi.dev/joke/Any) e exiba a piada completa no console.

    2. ✓ Resposta: 
    $piada = Invoke-RestMethod -Uri 'https://v2.jokeapi.dev/joke/Any'
if ($piada.type -eq 'single') {
    Write-Host $piada.joke
} else {
    Write-Host $piada.setup
    Write-Host $piada.delivery
}
  2. Faça uma requisição autenticada a uma API que exija um token Bearer (simule com um token fictício) e mostre como você adicionaria o cabeçalho de autorização.

    3. ✓ Resposta: 
    $headers = @{
    'Authorization' = 'Bearer SEU_TOKEN_AQUI'
}
$resposta = Invoke-RestMethod -Uri 'https://api.exemplo.com/privado' -Headers $headers
  3. Consumindo a API pública JSONPlaceholder (https://jsonplaceholder.typicode.com/users), filtre os usuários que trabalham na empresa "Romaguera-Crona" e exiba nome e email.

    4. ✓ Resposta: 
    $usuarios = Invoke-RestMethod -Uri 'https://jsonplaceholder.typicode.com/users'
$usuarios | Where-Object { $_.company.name -eq 'Romaguera-Crona' } | Select-Object name, email | Format-Table -AutoSize
  4. Converta o seguinte objeto em JSON e exiba a string resultante: [PSCustomObject]@{nome='Maria'; idade=25; cidade='São Paulo'}.

    5. ✓ Resposta: 
    $obj = [PSCustomObject]@{nome='Maria'; idade=25; cidade='São Paulo'}
$json = $obj | ConvertTo-Json
Write-Host $json
  5. Utilizando a API JSONPlaceholder (https://jsonplaceholder.typicode.com/posts), obtenha os 10 primeiros posts e exporte-os para um arquivo CSV com as colunas id, title e body.

    6. ✓ Resposta: 
    $posts = Invoke-RestMethod -Uri 'https://jsonplaceholder.typicode.com/posts'
$posts | Select-Object -First 10 | Select-Object id, title, body | Export-Csv -Path 'posts.csv' -NoTypeInformation

Referências