Invoke-RestMethod: cómo consumir una API REST con PowerShell

Invoke-RestMethod: centralita telefónica antigua con cientos de conectores numerados y una fila de clavijas rojas listas para enlazar cada llamada con su destino

Invoke-RestMethod es el cmdlet de PowerShell para hablar con una API REST: envía la petición, recibe la respuesta y, si llega en JSON o en XML, la convierte en objetos que se filtran, se ordenan y se exportan sin escribir una línea de análisis. Con él se consulta Microsoft Graph, se crean tickets en una mesa de servicio, se revisa el estado de una consola de copias o se descarga la última versión de un programa desde GitHub, todo desde la misma consola y con el mismo estilo de los demás cmdlets.

Esta guía de consulta explica Invoke-RestMethod desde la primera petición hasta los casos que de verdad fallan en producción: métodos GET, POST, PUT, PATCH y DELETE, encabezados, claves de API, token Bearer en PowerShell, OAuth, envío de JSON, codificación de tildes, errores HTTP, paginación, límites de peticiones, reintentos, tiempos de espera y archivos. Cada comportamiento que se describe se midió el 17 de noviembre de 2026 en un Windows 11 en español con Windows PowerShell 5.1 y con PowerShell 7.7.0, contra una API de laboratorio montada en el propio equipo y contra la API pública de GitHub. Donde las dos versiones se comportan distinto, y son bastantes casos, se dice.

Si es la primera vez que abre la consola, empiece por la guía de PowerShell y vuelva aquí cuando ya ejecute órdenes con soltura.

Qué es Invoke-RestMethod y qué es una API REST

Una API REST es la puerta que un servicio deja abierta para que otros programas trabajen con él por HTTP, sin pasar por la pantalla. Microsoft 365, Azure, Intune, GitHub, las mesas de servicio, los sistemas de monitoreo y casi cualquier consola moderna publican una. En la práctica, cada operación es una petición a una dirección (el *endpoint*) con un método, unos encabezados y, a veces, un cuerpo; el servicio contesta con un código de estado y, normalmente, con datos en JSON.

Invoke-RestMethod, por su parte, hace esa petición y entrega la respuesta ya convertida. Es lo que diferencia trabajar con una API REST con PowerShell de hacerlo con un navegador o con un programa genérico: el resultado no es texto, es un objeto con propiedades.

ConceptoQué esCómo se expresa en Invoke-RestMethod
EndpointLa dirección del recurso, por ejemplo https://api.example.com/v1/ticketsEl parámetro -Uri (o el primer argumento)
MétodoLa acción: leer (GET), crear (POST), reemplazar (PUT), cambiar en parte (PATCH), borrar (DELETE)-Method Get, -Method Post…
EncabezadosDatos de la petición: autenticación, formato, versión-Headers @{ Authorization = 'Bearer …' }
CuerpoLos datos que se envían al crear o cambiar algo, casi siempre JSON-Body y -ContentType
Código de estadoEl resultado: 200 correcto, 201 creado, 204 sin contenido, 401 sin autorización, 404 no existe, 429 demasiadas peticiones, 500 fallo del servidorUn error que se captura con try y catch
RespuestaLos datos devueltosObjetos de PowerShell listos para usar

El cmdlet existe desde Windows PowerShell 3.0 y tiene el alias irm. En PowerShell 7 creció mucho: medido con Get-Command, admite 34 parámetros en Windows PowerShell 5.1 y 58 en PowerShell 7.7, contando los parámetros comunes. Los que solo existen en 7 son justamente los que resuelven los problemas de este artículo: autenticación por token, reintentos, paginación automática, códigos de estado sin excepción y formularios con archivos.

Invoke-RestMethod vs Invoke-WebRequest: cuál usar

PowerShell trae dos cmdlets para HTTP y la comparación entre Invoke-RestMethod vs Invoke-WebRequest es de las búsquedas más repetidas sobre el tema. La regla corta: Invoke-RestMethod cuando interesa el contenido; Invoke-WebRequest cuando interesa la respuesta completa (código, encabezados, cuerpo en bruto).

Invoke-RestMethodInvoke-WebRequest
Qué devuelveEl contenido ya convertido: objetos desde JSON, elementos desde XML o RSS, texto si es textoUn objeto de respuesta con StatusCode, Headers, Content y RawContentStream
Uso típicoConsumir APIsComprobar si un servicio responde, leer encabezados, descargar páginas
Código de estadoSolo con -StatusCodeVariable (PowerShell 7)Siempre en .StatusCode
Encabezados de la respuestaSolo con -ResponseHeadersVariable (PowerShell 7)Siempre en .Headers
Aliasirmiwr; en 5.1 también curl y wget

Sin embargo, hay dos detalles medidos que confunden a mucha gente. En Windows PowerShell 5.1, curl y wget no son los programas de ese nombre: son alias de Invoke-WebRequest, así que una orden copiada de una guía de Linux falla con errores de parámetros. En PowerShell 7 esos alias ya no existen y curl ejecuta el curl.exe real.

El otro: en 5.1, Invoke-WebRequest sin -UseBasicParsing usa el motor de Internet Explorer para analizar el HTML. En este Windows 11 la primera llamada se quedó bloqueada más de quince minutos sin mostrar nada; lanzada en un trabajo en segundo plano, PowerShell respondió que el trabajo estaba «bloqueado a la espera de la interacción del usuario». Por eso, en 5.1, escriba siempre -UseBasicParsing. PowerShell 7, en cambio, ya no usa ese motor: el parámetro no hace nada y la llamada respondió en un segundo.

La primera petición GET con Invoke-RestMethod

La petición más sencilla es un GET a una dirección pública. Este ejemplo consulta la API de GitHub para saber cuál es la última versión publicada de PowerShell:

$version = Invoke-RestMethod -Uri 'https://api.github.com/repos/PowerShell/PowerShell/releases/latest'
$version | Select-Object tag_name, published_at, html_url
$version | Get-Member -MemberType NoteProperty | Select-Object -First 10 Name

Medido en las dos versiones: devolvió v7.7.0, publicada el 10 de noviembre de 2026, con 24 archivos de instalación en assets. Además, el resultado es un PSCustomObject y cada campo del JSON es una propiedad: $version.tag_name da la versión, $version.assets es una colección que se recorre con ForEach-Object y Get-Member muestra todo lo que trae.

Hay una diferencia que conviene conocer desde el principio: en PowerShell 7 las fechas en formato ISO 8601 llegan convertidas a DateTime y en Windows PowerShell 5.1 llegan como texto. Medido con el mismo campo published_at: System.DateTime en 7 y System.String en 5.1. Si un script compara fechas y tiene que funcionar en las dos, conviértalas usted con [datetime] y no dependa de la versión.

La API de GitHub sin autenticar admite 60 peticiones por hora por dirección IP; lo dice su encabezado X-RateLimit-Limit, leído en la prueba. Del mismo modo, casi todas las API públicas tienen un límite parecido, y por eso este artículo dedica una sección a los límites y los reintentos.

Parámetros de consulta: filtrar desde la petición

Muchas API aceptan filtros en la dirección (?page=2&size=5). Con Invoke-RestMethod hay dos formas de enviarlos en un GET: escribirlos en la dirección o pasar una tabla hash en -Body, que en un GET se convierte en la cadena de consulta. Medido en las dos versiones: -Body @{ page = 2; size = 5 } llegó al servidor como ?page=2&size=5.

$Api = 'https://api.example.com/v1'

# Con una tabla hash: PowerShell arma ?page=2&size=5
Invoke-RestMethod -Uri "$Api/tickets" -Method Get -Body @{ page = 2; size = 5 }

# Escrita a mano: los valores con espacios o tildes se codifican
$filtro = [uri]::EscapeDataString("sede eq 'Bogotá'")
Invoke-RestMethod -Uri "$Api/tickets?filter=$filtro"

Cuando el filtro lleva espacios, tildes o comillas, codifíquelo con [uri]::EscapeDataString. Medido: sede eq 'Bogotá' se convierte en sede%20eq%20'Bogot%C3%A1' en 5.1 y en sede%20eq%20%27Bogot%C3%A1%27 en 7, que además codifica el apóstrofo; las dos formas son válidas para un servidor que siga el estándar.

Los parámetros más usados de Invoke-RestMethod

Esta tabla reúne los parámetros que se usan a diario. La última columna indica si existen en Windows PowerShell 5.1; lo que dice «solo 7» se comprobó con Get-Command en las dos versiones.

ParámetroPara qué sirveEn 5.1
-UriDirección del endpointSí
-MethodGet, Post, Put, Patch, Delete, Head, Options, Trace, MergeSí
-HeadersTabla hash con los encabezados (autenticación, versión, formato)Sí
-BodyCuerpo de la petición: texto, bytes o tabla hashSí
-ContentTypeTipo del cuerpo, por ejemplo application/json; charset=utf-8Sí
-CredentialUsuario y contraseña (autenticación básica o de Windows)Sí
-UseDefaultCredentialsLa cuenta de Windows de quien ejecuta, para servicios internosSí
-TimeoutSecTiempo máximo de espera; 0 es indefinidoSí (en 7 es alias de -ConnectionTimeoutSeconds)
-OutFile / -InFileGuardar la respuesta en un archivo / enviar un archivo como cuerpoSí
-Proxy / -ProxyCredentialSalir por un proxySí
-Authentication y -TokenBearer, Basic u OAuth con el token como SecureStringSolo 7
-StatusCodeVariableGuarda el código de estado en una variableSolo 7
-ResponseHeadersVariableGuarda los encabezados de la respuestaSolo 7
-SkipHttpErrorCheckNo lanza error con un 4xx o 5xx: devuelve el cuerpo del errorSolo 7
-FollowRelLink y -MaximumFollowRelLinkSigue la paginación del encabezado LinkSolo 7
-MaximumRetryCount y -RetryIntervalSecReintentos automáticosSolo 7
-FormFormulario multipart/form-data, con archivosSolo 7
-SkipCertificateCheckIgnora errores de certificado (solo laboratorio)Solo 7
-OperationTimeoutSecondsTiempo máximo entre lecturas de datos de una descargaSolo 7

La lista completa, con ejemplos, está en la referencia oficial del cmdlet en Microsoft Learn.

Invoke-RestMethod POST: enviar datos en JSON

Para crear algo en una API se usa POST con un cuerpo en JSON. La forma correcta en las dos versiones tiene tres piezas: construir los datos como tabla hash, convertirlos con ConvertTo-Json y declarar el tipo con -ContentType.

$Api = 'https://api.example.com/v1'
$ticket = @{
    asunto    = 'Monitor sin señal'
    sede      = 'Bogotá'
    prioridad = 'alta'
}
$json = $ticket | ConvertTo-Json -Depth 5

$creado = Invoke-RestMethod -Uri "$Api/tickets" -Method Post -Body $json -ContentType 'application/json; charset=utf-8'
$creado

Las tres piezas importan, y estas son las razones medidas:

  • Sin -ContentType, Invoke-RestMethod POST declara application/x-www-form-urlencoded, aunque el cuerpo sea JSON. Medido en 5.1 y en 7. Muchas API rechazan la petición o la interpretan como formulario.
  • En Windows PowerShell 5.1, application/json sin charset=utf-8 estropea las tildes. El cuerpo salió en la codificación Latin-1 de .NET Framework: «Bogotá» llegó con un byte que no es UTF-8 válido y el servidor de laboratorio no pudo leer el JSON. Con application/json; charset=utf-8, llegó bien. PowerShell 7 envía UTF-8 en los dos casos. Un JSON sin tildes funciona de las dos formas, que es por lo que el fallo pasa desapercibido en las pruebas y aparece con el primer nombre que lleva eñe.
  • Una tabla hash en -Body sin convertir no es JSON: en un POST, PowerShell la envía como formulario (asunto=Monitor+sin+se%C3%B1al&sede=…). Sirve para las API que piden formulario, como la mayoría de las que entregan tokens, pero no para las que esperan JSON.

Si un script tiene que funcionar en 5.1 con cualquier texto, hay una alternativa a declarar el charset: enviar los bytes ya codificados, con -Body ([Text.Encoding]::UTF8.GetBytes($json)). Medido en las dos versiones: llegó correcto.

ConvertTo-Json y la trampa de la profundidad

ConvertTo-Json solo convierte dos niveles de anidamiento si no se le indica otra cosa. Lo que queda más abajo no se convierte: se sustituye por el nombre del tipo. Medido con un ticket que lleva cliente, sede y ciudad anidados:

OrdenResultadoAviso
ConvertTo-Json{"ticket":{"cliente":{"sede":"System.Collections.Hashtable"}}}Ninguno en 5.1; advertencia en 7
ConvertTo-Json -Depth 10{"ticket":{"cliente":{"sede":{"ciudad":"Cali"}}}}Ninguno

Es decir, en Windows PowerShell 5.1 la API recibe un dato equivocado sin ningún aviso. PowerShell 7 al menos advierte («El JSON resultante se trunca porque la serialización ha superado la profundidad establecida de 2»), pero envía igual. Ponga siempre -Depth (el máximo es 100) en todo ConvertTo-Json que vaya a una API. Lo mismo pasa al revés: una respuesta con cinco niveles reconvertida a JSON para guardarla en un archivo quedó cortada como "@{d=}".

La otra trampa es un arreglo de un solo elemento. Por la canalización, @(@{ id = 1 }) | ConvertTo-Json produce {"id":1}, un objeto y no una lista. Si la API espera un arreglo, use ConvertTo-Json -InputObject $lista, que produjo [{"id":1}] en las dos versiones.

Leer, cambiar y borrar: GET, PUT, PATCH y DELETE

En general, el resto de métodos funciona igual que POST: cambia -Method y, cuando hay cuerpo, se envía en JSON. PUT reemplaza el recurso completo y PATCH cambia solo los campos que se envían; cuál acepta cada API lo dice su documentación.

$Api = 'https://api.example.com/v1'
$json = @{ estado = 'cerrado' } | ConvertTo-Json

Invoke-RestMethod -Uri "$Api/tickets/3"                                                                  # leer uno
Invoke-RestMethod -Uri "$Api/tickets/3" -Method Patch -Body $json -ContentType 'application/json; charset=utf-8'   # cambiar un campo
Invoke-RestMethod -Uri "$Api/tickets/3" -Method Delete                                                  # borrar

Un detalle medido para quien comprueba el resultado: un DELETE que responde 204 sin contenido devuelve una cadena vacía, no $null, en las dos versiones. Una condición if ($null -eq $r) dice que «no hubo respuesta» cuando sí la hubo; para saber si funcionó, confíe en que no hubo error o, en PowerShell 7, en -StatusCodeVariable.

Autenticación: claves de API, Basic, token Bearer en PowerShell y OAuth

Casi ninguna API útil responde sin identificarse. Hay cuatro formas habituales, y la elección no la hace quien escribe el script: la impone la API.

MétodoCómo se envíaEjemplo de servicios
Clave de APIUn encabezado propio, como X-Api-KeyHerramientas de monitoreo, mesas de servicio, servicios de terceros
Autenticación básicaAuthorization: Basic con usuario y contraseña en Base64Equipos de red y consolas antiguas
Token BearerAuthorization: Bearer <token>GitHub, Microsoft Graph, Azure y la mayoría de API modernas
OAuth 2.0Primero se pide un token a un servidor de autorización y luego se usa como BearerMicrosoft Entra ID, Google, servicios en la nube

Clave de API y token Bearer con -Headers (5.1 y 7)

La forma que funciona en todas las versiones es escribir el encabezado en -Headers:

$Api = 'https://api.example.com/v1'
$token = $env:API_TOKEN

$encabezados = @{
    Authorization = "Bearer $token"
    Accept        = 'application/json'
}
Invoke-RestMethod -Uri "$Api/protegido" -Headers $encabezados

# Una API que pide su propia clave en un encabezado
Invoke-RestMethod -Uri "$Api/apikey" -Headers @{ 'X-Api-Key' = $env:API_KEY }

Eso sí, el token no se escribe dentro del script. En el ejemplo se lee de una variable de entorno; en un servidor, lo correcto es guardarlo en un almacén de secretos, como el módulo SecretManagement de Microsoft, y leerlo al ejecutar. Un token es una contraseña: quien lo copie entra en la API con sus permisos.

Token Bearer en PowerShell 7 con -Authentication

PowerShell 7 añade -Authentication Bearer -Token, que no deja el token en texto plano dentro de la tabla de encabezados. El token tiene que ser un SecureString: pasarlo como texto falla con «No se puede enlazar el parámetro Token. No se puede convertir el valor de tipo System.String al tipo System.Security.SecureString».

$token = Read-Host -Prompt 'Token' -AsSecureString
Invoke-RestMethod -Uri 'https://api.github.com/user' -Authentication Bearer -Token $token

Y una protección que conviene conocer: PowerShell 7 se niega a enviar credenciales o tokens por HTTP sin cifrar. Medido contra la API de laboratorio por http://: «El cmdlet no puede proteger los secretos de texto sin formato enviados a través de conexiones sin cifrar…». Existe -AllowUnencryptedAuthentication para saltarse el aviso, pero la respuesta correcta casi siempre es usar HTTPS. Contra GitHub por HTTPS, la misma orden con un token falso llegó al servidor y respondió 401, como debía.

Autenticación básica: la petición doble de -Credential

Con -Credential y sin -Authentication, Windows PowerShell 5.1 no envía la contraseña en la primera petición: espera a que el servidor responda 401 y pida credenciales, y entonces repite la petición con ellas. Medido en el registro del servidor de laboratorio: dos peticiones, la primera sin el encabezado Authorization y la segunda con Basic. Funciona, pero cada llamada cuesta el doble, y algunas API no piden credenciales con un 401 sino que devuelven directamente un error. PowerShell 7, por HTTP, rechazó la orden con el aviso de conexión sin cifrar.

Para que vaya a la primera en las dos versiones, envíe el encabezado usted mismo, o en PowerShell 7 use -Authentication Basic -Credential:

$Api = 'https://api.example.com/v1'
$cred = Get-Credential -Message 'Usuario de la API'
$par  = '{0}:{1}' -f $cred.UserName, $cred.GetNetworkCredential().Password
$b64  = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($par))

Invoke-RestMethod -Uri "$Api/basica" -Headers @{ Authorization = "Basic $b64" }

OAuth 2.0: pedir un token y usarlo

Con OAuth el script hace dos pasos: pide un token al servidor de autorización enviando su identidad (la aplicación y su secreto o certificado) y usa ese token como Bearer hasta que caduca. Este ejemplo lo hace contra Microsoft Entra ID para llamar a Microsoft Graph con permisos de aplicación; necesita una aplicación registrada en el inquilino con los permisos concedidos por un administrador.

$tenant   = 'contoso.onmicrosoft.com'
$clientId = '00000000-0000-0000-0000-000000000000'
$secreto  = $env:GRAPH_CLIENT_SECRET

$respuesta = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenant/oauth2/v2.0/token" -Body @{
    grant_type    = 'client_credentials'
    client_id     = $clientId
    client_secret = $secreto
    scope         = 'https://graph.microsoft.com/.default'
}
$graph = @{ Authorization = "$($respuesta.token_type) $($respuesta.access_token)" }

Invoke-RestMethod -Uri 'https://graph.microsoft.com/v1.0/users?$select=displayName,userPrincipalName&$top=5' -Headers $graph

Para terminar, fíjese en dos cosas. El token se pide con una tabla hash en -Body, que se envía como formulario: es justo lo que exige el estándar OAuth, y por eso aquí no se usa JSON. Y la dirección de Graph va entre comillas simples, porque $select y $top llevan el signo de dólar y entre comillas dobles PowerShell los tomaría por variables vacías. El flujo completo se probó contra un servidor de tokens de laboratorio en las dos versiones: token Bearer con 3.599 segundos de vida, aceptado en la llamada siguiente.

Para Microsoft 365, Microsoft ofrece además el módulo Microsoft Graph PowerShell, que gestiona el token por usted y trae Invoke-MgGraphRequest para las llamadas que no tienen cmdlet propio; la guía de Microsoft 365 PowerShell lo explica. Invoke-RestMethod sigue siendo útil cuando se quiere un script sin módulos o se trabaja con una API que no tiene módulo.

Qué devuelve Invoke-RestMethod según la respuesta

El cmdlet mira el tipo de contenido que declara el servidor y decide qué entregar. Medido con la API de laboratorio en las dos versiones:

La API respondeInvoke-RestMethod devuelve
Un objeto JSONUn PSCustomObject con una propiedad por campo
Un arreglo JSONUn arreglo de objetos (Object[]); uno de un solo elemento sigue siendo arreglo
Un arreglo JSON vacíoUn arreglo vacío, no $null
XML o RSSEn RSS, los elementos item ya separados (dos noticias, dos objetos con title y link)
TextoUna cadena
204 sin contenidoUna cadena vacía
Una redirección 302Sigue la redirección y devuelve el destino

La trampa del arreglo en la canalización

Cuando la API responde un arreglo JSON, Invoke-RestMethod lo entrega a la canalización como un solo objeto, no elemento por elemento. Medido con una API que devuelve 12 tickets como arreglo, en 5.1 y en 7.7: Invoke-RestMethod $uri | ForEach-Object { … } dio una vuelta, y con la llamada entre paréntesis, doce. Peor aún, un filtro directo no filtra: pedir los tickets de Cali con Where-Object devolvió los 12, porque la comparación se hizo contra la lista entera; con paréntesis devolvió los 3 correctos.

$Api = 'https://api.example.com/v1'

# Mal: el arreglo entra entero y el filtro devuelve los 12 tickets
Invoke-RestMethod -Uri "$Api/todos" | Where-Object { $_.sede -eq 'Cali' }

# Bien: los paréntesis (o una variable) despliegan el arreglo y salen los 3 de Cali
(Invoke-RestMethod -Uri "$Api/todos") | Where-Object { $_.sede -eq 'Cali' }

La regla práctica: guarde la respuesta en una variable o envuelva la llamada entre paréntesis antes de canalizarla.

Ahora bien, muchas API no devuelven la lista directamente sino envuelta, por ejemplo { "value": [ … ], "nextLink": "…" }. En ese caso los datos están en la propiedad: (Invoke-RestMethod $uri).value. Microsoft Graph usa exactamente ese formato.

Tildes rotas: la respuesta sin charset en Windows PowerShell 5.1

Este es el fallo más frecuente con datos en español. Cuando una API responde Content-Type: application/json sin indicar charset=utf-8, Windows PowerShell 5.1 lee la respuesta como Latin-1 y las tildes salen rotas. Medido con la misma respuesta en UTF-8:

RespuestaWindows PowerShell 5.1PowerShell 7.7
application/json; charset=utf-8BogotáBogotá
application/json sin charsetBogotá · Señal débilBogotá · Señal débil
text/plain sin charsetBogotáBogotá

Lo peor es que el script no falla: guarda «Bogotá» en el informe o en la base de datos, y el error aparece semanas después. Si tiene que trabajar en 5.1 con una API así, pida la respuesta con Invoke-WebRequest y decodifique usted los bytes:

$Api = 'https://api.example.com/v1'
$respuesta = Invoke-WebRequest -Uri "$Api/sin-charset" -UseBasicParsing
$texto = [Text.Encoding]::UTF8.GetString($respuesta.RawContentStream.ToArray())
$datos = $texto | ConvertFrom-Json
$datos.sede

Medido: así «Bogotá» llegó bien en las dos versiones. La solución de fondo es pedir al proveedor que declare el charset, o usar PowerShell 7, que asume UTF-8 para JSON.

Errores HTTP: leer el código y el mensaje de la API

Cuando la API responde con un código 4xx o 5xx, Invoke-RestMethod lanza un error y el script se detiene en ese punto si está dentro de un try. Lo valioso no es el mensaje de PowerShell sino el cuerpo que manda la API, que casi siempre explica qué falló. Este bloque funciona igual en 5.1 y en 7:

$Api = 'https://api.example.com/v1'
try {
    $ticket = Invoke-RestMethod -Uri "$Api/tickets/500" -ErrorAction Stop
}
catch {
    $codigo = [int]$_.Exception.Response.StatusCode
    $detalle = $null
    if ($_.ErrorDetails.Message) { $detalle = $_.ErrorDetails.Message | ConvertFrom-Json }
    Write-Warning ("La API respondió {0}: {1}" -f $codigo, $detalle.error.message)
}

Medido con un ticket inexistente: código 404 y el mensaje propio de la API, «El ticket 500 no existe», en las dos versiones. El cuerpo del error está en $_.ErrorDetails.Message; el código, en $_.Exception.Response.StatusCode. Lo que cambia entre versiones es el tipo de la excepción y su texto, y eso importa si el script captura un tipo concreto:

SituaciónWindows PowerShell 5.1PowerShell 7.7
404 de la APISystem.Net.WebException: «Error en el servidor remoto: (404) No se encontró.»HttpResponseException: «El código de estado de la respuesta no indica un resultado correcto: 404 (Not Found).»
Nombre que no existe«No se puede resolver el nombre remoto»HttpRequestException: «Host desconocido.»
Puerto cerrado«No es posible conectar con el servidor remoto»«No se puede establecer una conexión ya que el equipo de destino denegó expresamente dicha conexión.»
Tiempo de espera agotado«La operación sobrepasó el tiempo de espera.»TaskCanceledException, con el mensaje en inglés

Como consecuencia, un catch [System.Net.WebException] escrito en 5.1 no captura nada en PowerShell 7. Capture sin tipo, o capture los dos. La guía de try catch en PowerShell explica el manejo de errores completo, incluido por qué un script que falla puede terminar con código 0.

PowerShell 7: el código de estado sin excepción

En PowerShell 7, -SkipHttpErrorCheck evita la excepción y -StatusCodeVariable guarda el código, lo que permite decidir con un switch en lugar de un catch:

$Api = 'https://api.example.com/v1'
$r = Invoke-RestMethod -Uri "$Api/tickets/500" -SkipHttpErrorCheck -StatusCodeVariable codigo
switch ($codigo) {
    200     { "Ticket: $($r.asunto)" }
    404     { 'El ticket no existe' }
    default { "Respuesta $codigo de la API" }
}

Medido: $codigo quedó en 404 y $r trajo el cuerpo del error ya convertido. Ojo: los errores de red (nombre que no existe, puerto cerrado, tiempo agotado) siguen lanzando excepción aunque se use -SkipHttpErrorCheck, porque no hay respuesta HTTP.

Paginación: traer todos los resultados

Por supuesto, ninguna API devuelve diez mil registros de una vez. En cambio, los entrega por páginas y dice dónde está la siguiente, de dos maneras: dentro del cuerpo (una propiedad como nextLink o @odata.nextLink) o en el encabezado Link. El bucle que sigue la propiedad funciona en cualquier versión:

$Api = 'https://api.example.com/v1'
$uri = "$Api/tickets?size=5"
$todos = [System.Collections.Generic.List[object]]::new()
do {
    $pagina = Invoke-RestMethod -Uri $uri
    $todos.AddRange(@($pagina.value))
    $uri = $pagina.nextLink
} while ($uri)
$todos.Count

Medido con 12 tickets en páginas de 5: tres peticiones y los 12 registros, en 5.1 y en 7. Se usa una lista y no $todos += …, porque sumar a un arreglo lo copia entero en cada vuelta y con miles de registros se nota.

PowerShell 7 sigue solo la paginación del encabezado Link con -FollowRelLink. Medido: devolvió las tres páginas, cada una como un elemento, y los 12 tickets al desplegarlas; con -MaximumFollowRelLink 2 se detuvo en dos. Solo sirve con API que usen ese encabezado (GitHub lo hace); Microsoft Graph pone @odata.nextLink en el cuerpo y necesita el bucle.

Límites de peticiones y reintentos

Las API protegen sus servidores con límites. Cuando se superan, responden 429 Too Many Requests y, casi siempre, un encabezado Retry-After con los segundos que hay que esperar. Un script que hace cientos de llamadas tiene que contar con ello.

PowerShell 7 trae -MaximumRetryCount y -RetryIntervalSec, y la documentación indica que, ante un 429 con Retry-After, espera lo que dice el servidor. Medido contra una API que respondía 429 dos veces: a la tercera petición funcionó, en 2 segundos. Pero hay un detalle que cambia cómo usarlo: reintenta con cualquier código entre 400 y 599, también los que no se arreglan esperando. Medido con -MaximumRetryCount 3:

RespuestaPeticiones que recibió la APITiempo
401 sin autorización43,0 s
404 no existe43,1 s
500 fallo del servidor43,1 s
404 en un POST4 POST3,0 s

Es decir, un token caducado no se arregla al tercer intento, y un POST reintentado tras un 500 puede crear cuatro tickets si el servidor alcanzó a guardar el primero. Use -MaximumRetryCount en lecturas (GET) y escriba el reintento usted cuando la operación crea o cambia algo. Esta función reintenta solo ante 429 y 503, respeta Retry-After y funciona en las dos versiones, que guardan ese encabezado de forma distinta:

function Invoke-ApiConReintento {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory)] [string] $Uri,
        [string] $Method = 'Get',
        [hashtable] $Headers = @{},
        $Body,
        [string] $ContentType = 'application/json; charset=utf-8',
        [int] $Intentos = 5
    )
    for ($n = 1; $n -le $Intentos; $n++) {
        try {
            $p = @{ Uri = $Uri; Method = $Method; Headers = $Headers; ErrorAction = 'Stop' }
            if ($null -ne $Body) { $p.Body = $Body; $p.ContentType = $ContentType }
            return Invoke-RestMethod @p
        }
        catch {
            $respuesta = $_.Exception.Response
            $codigo = 0
            if ($respuesta) { $codigo = [int]$respuesta.StatusCode }
            if ($codigo -notin 429, 503 -or $n -eq $Intentos) { throw }
            $espera = 0
            if ($respuesta.Headers.RetryAfter) { $espera = [int]$respuesta.Headers.RetryAfter.Delta.TotalSeconds }   # PowerShell 7
            elseif ($respuesta.Headers['Retry-After']) { $espera = [int]$respuesta.Headers['Retry-After'] }           # Windows PowerShell 5.1
            if ($espera -le 0) { $espera = [math]::Pow(2, $n) }
            Write-Verbose "Respuesta $codigo; nuevo intento en $espera s"
            Start-Sleep -Seconds $espera
        }
    }
}

Invoke-ApiConReintento -Uri 'https://api.example.com/v1/limite?id=demo' -Verbose

Medido: tres intentos y 2 segundos en las dos versiones, con la espera tomada del Retry-After del servidor. Si nunca ha escrito una función con [CmdletBinding()] y parámetros validados, la guía de funciones en PowerShell explica cada pieza.

Tiempo de espera: que el script no se quede colgado

De fábrica, Invoke-RestMethod espera indefinidamente: el valor por defecto de -TimeoutSec es 0, según la documentación de las dos versiones. Así, una API que deja la conexión abierta sin responder congela la tarea programada que la llama, y nadie se entera hasta que alguien mira. Ponga siempre un límite:

$Api = 'https://api.example.com/v1'
Invoke-RestMethod -Uri "$Api/lento?s=5" -TimeoutSec 2

Medido con una respuesta que tardaba 5 segundos: el error saltó a los 2,0 s en las dos versiones. En PowerShell 7, -TimeoutSec es un alias del nuevo -ConnectionTimeoutSeconds, y existe además -OperationTimeoutSeconds, que limita la espera entre datos de una descarga larga sin cortarla mientras los datos sigan llegando. La documentación avisa de que la resolución del nombre puede tardar hasta 15 segundos aunque el límite sea menor. Para comprobar antes si un puerto responde, la guía de Test-NetConnection es la herramienta.

Descargar y subir archivos

-OutFile guarda la respuesta en un archivo en lugar de devolverla. Aquí está la diferencia de rendimiento más grande medida en todo el artículo: en Windows PowerShell 5.1, la barra de progreso hace lentísimas las descargas.

Descarga de 50 MB desde la red localWindows PowerShell 5.1PowerShell 7.7
Con la barra de progreso (por defecto)41,6 s0,1 s
Con $ProgressPreference = 'SilentlyContinue'0,2 s0,1 s

En otras palabras, casi doscientas veces más lento, solo por dibujar el progreso. En cualquier script de 5.1 que descargue, apague la barra antes y devuélvala después:

$Api = 'https://api.example.com/v1'
$destino = Join-Path $env:TEMP 'informe.zip'

$antes = $ProgressPreference
$ProgressPreference = 'SilentlyContinue'
try {
    Invoke-RestMethod -Uri "$Api/archivo" -OutFile $destino
}
finally {
    $ProgressPreference = $antes
}
Get-Item $destino | Select-Object Name, Length

Para subir un archivo como formulario multipart/form-data, PowerShell 7 tiene -Form, que acepta campos de texto y objetos de archivo mezclados. Medido: el servidor recibió el campo de texto y el archivo con su nombre y sus 20 bytes. En 5.1 no existe; hay que armar el cuerpo a mano o enviar el archivo entero con -InFile.

$Api = 'https://api.example.com/v1'
$adjunto = Get-Item -Path (Join-Path $env:TEMP 'registro.txt')
Invoke-RestMethod -Uri "$Api/form" -Method Post -Form @{
    asunto  = 'Registro del equipo PC-014'
    archivo = $adjunto
}

Certificados y TLS

En los dos equipos de prueba, [Net.ServicePointManager]::SecurityProtocol valía SystemDefault: Windows decide la versión de TLS y las conexiones con GitHub funcionaron sin tocar nada. La línea que forzaba TLS 1.2 en Windows PowerShell 5.1, que aparece en tantos scripts, solo hace falta en sistemas antiguos que no tienen TLS 1.2 activado por defecto.

PowerShell 7 tiene -SkipCertificateCheck para servidores con certificados autofirmados. Por lo tanto, úselo solo en un laboratorio: en producción desactiva la comprobación que garantiza que se habla con el servidor correcto, y el token viaja a quien esté en medio. La solución es instalar en el equipo la autoridad de certificación interna que firmó el certificado.

Escenarios de ejemplo con Invoke-RestMethod

Estos casos salen del trabajo de una mesa de ayuda y de administración de plataformas. Los dos primeros se pueden ejecutar tal cual.

Saber si hay una versión nueva de PowerShell

$ultima = Invoke-RestMethod -Uri 'https://api.github.com/repos/PowerShell/PowerShell/releases/latest' -TimeoutSec 30
$publicada = [version]($ultima.tag_name.TrimStart('v'))
$instalada = [version](($PSVersionTable.PSVersion.ToString() -split '-')[0])
[pscustomobject]@{
    Instalada  = "$instalada"
    Publicada  = "$publicada"
    Actualizar = ($instalada -lt $publicada)
}

Medido el 17 de noviembre: en Windows PowerShell 5.1 respondió que había que actualizar a la 7.7.0, y en PowerShell 7.7.0, que no. La versión se toma del texto y se corta en el guion porque en 5.1 $PSVersionTable.PSVersion no tiene la propiedad Patch de PowerShell 7 (la primera versión de este ejemplo falló en 5.1 por eso) y las versiones preliminares llevan un sufijo como -preview.5. Con winget se instala la versión nueva, como explica la guía de winget.

Comprobar que una API responde y cuánto tarda

Por ejemplo, para vigilar un servicio que expone una API, interesa el código y el tiempo, no el contenido. Aquí Invoke-WebRequest es mejor que Invoke-RestMethod, porque devuelve StatusCode en cualquier versión:

$servicios = 'https://api.github.com', 'https://api.example.com/v1/tickets/1'
foreach ($url in $servicios) {
    $reloj = [Diagnostics.Stopwatch]::StartNew()
    try {
        $r = Invoke-WebRequest -Uri $url -UseBasicParsing -TimeoutSec 10 -Method Head
        $estado = [int]$r.StatusCode
    }
    catch {
        $estado = 'ERROR: ' + $_.Exception.Message
    }
    [pscustomobject]@{ Url = $url; Estado = $estado; Milisegundos = $reloj.ElapsedMilliseconds }
}

Programado cada cinco minutos, es un monitoreo básico. Para hacerlo en serio, con historial, umbrales y avisos, existen herramientas dedicadas como las que describe la guía de Zabbix.

Listar los usuarios de Microsoft 365 a un CSV con Microsoft Graph

Este caso junta el token de OAuth y la paginación con @odata.nextLink. Usa el $graph del ejemplo de OAuth y una aplicación con el permiso User.Read.All de aplicación:

$uri = 'https://graph.microsoft.com/v1.0/users?$select=displayName,userPrincipalName,accountEnabled&$top=999'
$usuarios = [System.Collections.Generic.List[object]]::new()
do {
    $pagina = Invoke-RestMethod -Uri $uri -Headers $graph -TimeoutSec 60
    $usuarios.AddRange(@($pagina.value))
    $uri = $pagina.'@odata.nextLink'
} while ($uri)

$usuarios | Select-Object displayName, userPrincipalName, accountEnabled |
    Export-Csv -Path (Join-Path $env:TEMP 'usuarios-m365.csv') -NoTypeInformation -Encoding UTF8

La propiedad se escribe entre comillas, $pagina.'@odata.nextLink', porque lleva arroba. La tarea de dejar esto en marcha cada noche está en la guía de tareas programadas con PowerShell, y la administración de Microsoft 365 con los módulos oficiales, en la de Microsoft 365 PowerShell. Para Azure e Intune hay guías propias: Azure PowerShell e Intune PowerShell.

Crear un ticket en una mesa de servicio desde un script

Hoy, muchas mesas de servicio aceptan tickets por API. Este patrón, con la función de reintento de más arriba, es el que usa un script de mantenimiento para dejar constancia de un fallo:

$Api = 'https://api.example.com/v1'
$cuerpo = @{
    asunto    = 'Copia nocturna fallida en SRV-ARCHIVOS'
    sede      = 'Bogotá'
    prioridad = 'alta'
    detalle   = @{ equipo = 'SRV-ARCHIVOS'; hora = (Get-Date).ToString('s') }
} | ConvertTo-Json -Depth 5

$ticket = Invoke-ApiConReintento -Uri "$Api/tickets" -Method Post -Body $cuerpo -Headers @{ Authorization = "Bearer $env:API_TOKEN" }
"Ticket creado: $($ticket.id)"

Por último, el -Depth 5 es lo que evita que detalle llegue como «System.Collections.Hashtable», y el charset=utf-8 de la función, que «Bogotá» llegue roto desde 5.1.

Errores comunes con Invoke-RestMethod

  1. Olvidar -ContentType en un POST. PowerShell declara formulario y la API rechaza el JSON.
  2. application/json sin charset=utf-8 en Windows PowerShell 5.1. Las tildes salen en Latin-1 y el JSON llega inválido.
  3. ConvertTo-Json sin -Depth. A partir del tercer nivel, la API recibe el nombre de un tipo en lugar del dato, sin aviso en 5.1.
  4. Respuestas sin charset en 5.1. «Bogotá» se guarda como «Bogotá» sin ningún error.
  5. Usar curl en 5.1 creyendo que es curl. Es Invoke-WebRequest con otro nombre.
  6. Invoke-WebRequest sin -UseBasicParsing en 5.1. Puede quedarse bloqueado esperando una interacción que nadie ve.
  7. No poner tiempo de espera. El valor por defecto es infinito.
  8. -MaximumRetryCount en operaciones que crean algo. Repite el POST con cualquier error 4xx o 5xx.
  9. Capturar [System.Net.WebException]. En PowerShell 7 el error es otro tipo y el catch no lo atrapa.
  10. Dejar la barra de progreso en descargas de 5.1. Una descarga de 50 MB pasó de 0,2 a 41,6 segundos.
  11. Escribir la dirección de Graph entre comillas dobles. $select y $top se pierden como variables vacías.
  12. Tokens y claves dentro del script. Léalos de un almacén de secretos o de una variable de entorno protegida.
  13. -SkipCertificateCheck en producción. Anula la protección de HTTPS.
  14. Tratar un arreglo de un elemento como objeto al enviarlo. Por la canalización, ConvertTo-Json lo convierte en objeto; use -InputObject.
  15. Canalizar la respuesta directamente. Un arreglo JSON entra como un solo objeto; ponga la llamada entre paréntesis.
  16. Variables que solo cambian en mayúsculas. Para PowerShell, $b y $B son la misma variable. Al preparar este artículo, un $b con el cuerpo de la petición pisó la variable $B con la dirección de la API y la llamada falló con «URI no válido».

Recomendaciones para usar APIs REST con PowerShell en la empresa

  • Prefiera PowerShell 7 para todo lo que hable con APIs. Resuelve la codificación, avisa de la profundidad, trae token seguro, reintentos, paginación y códigos de estado.
  • Si el script tiene que correr en 5.1, ponga siempre charset=utf-8, -Depth, -UseBasicParsing, -TimeoutSec y la barra de progreso apagada en las descargas.
  • Una cuenta o aplicación por script, con los permisos mínimos que pide la API, nunca la cuenta de un administrador.
  • Secretos fuera del código y rotados con fecha; quien deja la empresa no debe llevarse un token válido.
  • Registre cada llamada que cambia algo: qué se envió, qué respondió la API y el código. Sin eso, un fallo nocturno no se puede explicar.
  • Respete los límites: pausas entre lotes, Retry-After y paginación en lugar de pedir todo de golpe.
  • Pruebe primero contra un entorno de pruebas o con métodos de solo lectura (GET) antes de lanzar un POST o un DELETE sobre datos reales.

Invoke-RestMethod en la administración diaria

Invoke-RestMethod convierte cualquier servicio con API en algo que se administra desde la consola: se consulta, se filtra, se exporta y se automatiza con la misma lógica que el resto de PowerShell. Con -ContentType y -Depth bien puestos, el token fuera del código, un tiempo de espera, la paginación y los errores leídos desde el cuerpo de la respuesta, un script que habla con una API deja de ser frágil.

En KHARONTE trabajamos así la gestión de plataformas de nuestros clientes: la administración de usuarios, licencias y accesos en Microsoft 365 y en las consolas que lo permiten se apoya en sus API para revisar, documentar y repetir tareas con el mismo criterio cada vez. Si su empresa necesita una mesa de ayuda TI o quiere conocer nuestros servicios administrados de TI, revise los servicios de TI para empresas o escríbanos.

Hablemos de la TI de su empresa

Cuéntenos qué necesita su operación y le enviamos una propuesta por escrito. Cada línea del portafolio se contrata por separado.

Compartir este artículo

Últimas entradas

Escríbanos ahora