Peticiones HTTP y APIs con PowerShell

Consultar el tipo de cambio, mandar un aviso a Teams, crear un ticket o leer pedidos de una tienda en línea: todo eso es hablar con una API por HTTP. En PowerShell se hace con Invoke-RestMethod, que además convierte el JSON de la respuesta en objetos.

Para que los ejemplos se puedan comprobar sin internet, se ejecutaron contra una pequeña API de prueba en la propia computadora, en http://localhost:8080, que devuelve productos en JSON. Con una API real solo cambia la dirección.

GET: pedir datos con Invoke-RestMethod

$productos = Invoke-RestMethod -Uri "http://localhost:8080/api/productos"
$productos.Count
$productos | Where-Object existencias -gt 0 | Select-Object id, nombre, existencias
$productos[0].nombre
salida3

id nombre              existencias
-- ------              -----------
 1 Teclado mecánico             14
 3 Monitor 27 pulgadas           6
Teclado mecánico

Invoke-RestMethod hace la petición, ve que la respuesta es JSON y la convierte en objetos: no hay que llamar a ConvertFrom-Json. A partir de ahí se filtra y se ordena como cualquier otra cosa en PowerShell.

Errores: 404 y tiempo de espera

try {
    Invoke-RestMethod -Uri "http://localhost:8080/api/productos/99"
} catch {
    "Código: $($_.Exception.Response.StatusCode.value__)"
    "Respuesta: $($_.ErrorDetails.Message)"
}

try {
    Invoke-RestMethod -Uri "http://localhost:8080/lento" -TimeoutSec 1
} catch {
    "Falló: $($_.Exception.GetType().Name)"
}

$r = Invoke-RestMethod -Uri "http://localhost:8080/api/productos/99" -SkipHttpErrorCheck -StatusCodeVariable codigo
"Sin excepción: código $codigo, error '$($r.error)'"
salidaCódigo: 404
Respuesta:
{
  "error": "no existe"
}
Falló: TaskCanceledException
Sin excepción: código 404, error 'no existe'

Una respuesta 404 o 500 lanza un error que detiene, así que se atrapa con try. El código está en $_.Exception.Response.StatusCode y el cuerpo de la respuesta, en $_.ErrorDetails.Message. -TimeoutSec evita que el script se quede esperando para siempre. Y en PowerShell 7, -SkipHttpErrorCheck con -StatusCodeVariable deja revisar el código sin excepciones, que a veces es más claro.

POST con JSON y un token

$pedido = @{ producto = 3; piezas = 2 } | ConvertTo-Json
$cabeceras = @{ Authorization = "Bearer token-de-prueba" }
$r = Invoke-RestMethod -Uri "http://localhost:8080/api/pedidos" -Method Post `
    -Body $pedido -ContentType "application/json" -Headers $cabeceras
"Pedido creado: $($r.pedido) ($($r.piezas) piezas del producto $($r.producto))"

$r = Invoke-RestMethod -Uri "http://localhost:8080/api/pedidos" -Method Post `
    -Body $pedido -ContentType "application/json" -SkipHttpErrorCheck -StatusCodeVariable codigo
"Sin token: $codigo, $($r.error)"
salidaPedido creado: 5001 (2 piezas del producto 3)
Sin token: 401, sin permiso

El cuerpo se arma como hashtable y se convierte a JSON; las cabeceras van en otra hashtable. Muchas APIs piden el token en Authorization: Bearer …. Ese token, como cualquier contraseña, no debe ir escrito en el script: léelo de una variable de entorno, como en el ejemplo de variables de entorno, o de una bóveda con SecretManagement.

Descargar un archivo

Invoke-WebRequest -Uri "https://example.com/reporte.pdf" -OutFile reporte.pdf

Para archivos se usa Invoke-WebRequest con -OutFile. Este no se pudo ejecutar en el contenedor sin red. Un detalle de Windows: en Windows PowerShell 5.1, curl y wget eran alias de Invoke-WebRequest; en PowerShell 7 ya no existen esos alias, y curl ejecuta el curl.exe de verdad, que viene con Windows 10 y 11.

Todos los scripts de esta página se ejecutaron con PowerShell 7.6.10 (LTS) en un contenedor Linux limpio sin acceso a la red, con la configuración regional de México, y pasaron PSScriptAnalyzer 1.25 sin avisos antes de publicarla; las salidas están copiadas de esa ejecución. Por eso las rutas salen como /home/ana/proyecto; en Windows verás algo como C:\Users\ana.