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.
| Concepto | Qué es | Cómo se expresa en Invoke-RestMethod |
|---|---|---|
| Endpoint | La dirección del recurso, por ejemplo https://api.example.com/v1/tickets | El parámetro -Uri (o el primer argumento) |
| Método | La acción: leer (GET), crear (POST), reemplazar (PUT), cambiar en parte (PATCH), borrar (DELETE) | -Method Get, -Method Post… |
| Encabezados | Datos de la petición: autenticación, formato, versión | -Headers @{ Authorization = 'Bearer …' } |
| Cuerpo | Los datos que se envían al crear o cambiar algo, casi siempre JSON | -Body y -ContentType |
| Código de estado | El resultado: 200 correcto, 201 creado, 204 sin contenido, 401 sin autorización, 404 no existe, 429 demasiadas peticiones, 500 fallo del servidor | Un error que se captura con try y catch |
| Respuesta | Los datos devueltos | Objetos 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-RestMethod | Invoke-WebRequest | |
|---|---|---|
| Qué devuelve | El contenido ya convertido: objetos desde JSON, elementos desde XML o RSS, texto si es texto | Un objeto de respuesta con StatusCode, Headers, Content y RawContentStream |
| Uso típico | Consumir APIs | Comprobar si un servicio responde, leer encabezados, descargar páginas |
| Código de estado | Solo con -StatusCodeVariable (PowerShell 7) | Siempre en .StatusCode |
| Encabezados de la respuesta | Solo con -ResponseHeadersVariable (PowerShell 7) | Siempre en .Headers |
| Alias | irm | iwr; 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ámetro | Para qué sirve | En 5.1 |
|---|---|---|
-Uri | Dirección del endpoint | Sí |
-Method | Get, Post, Put, Patch, Delete, Head, Options, Trace, Merge | Sí |
-Headers | Tabla hash con los encabezados (autenticación, versión, formato) | Sí |
-Body | Cuerpo de la petición: texto, bytes o tabla hash | Sí |
-ContentType | Tipo del cuerpo, por ejemplo application/json; charset=utf-8 | Sí |
-Credential | Usuario y contraseña (autenticación básica o de Windows) | Sí |
-UseDefaultCredentials | La cuenta de Windows de quien ejecuta, para servicios internos | Sí |
-TimeoutSec | Tiempo máximo de espera; 0 es indefinido | Sí (en 7 es alias de -ConnectionTimeoutSeconds) |
-OutFile / -InFile | Guardar la respuesta en un archivo / enviar un archivo como cuerpo | Sí |
-Proxy / -ProxyCredential | Salir por un proxy | Sí |
-Authentication y -Token | Bearer, Basic u OAuth con el token como SecureString | Solo 7 |
-StatusCodeVariable | Guarda el código de estado en una variable | Solo 7 |
-ResponseHeadersVariable | Guarda los encabezados de la respuesta | Solo 7 |
-SkipHttpErrorCheck | No lanza error con un 4xx o 5xx: devuelve el cuerpo del error | Solo 7 |
-FollowRelLink y -MaximumFollowRelLink | Sigue la paginación del encabezado Link | Solo 7 |
-MaximumRetryCount y -RetryIntervalSec | Reintentos automáticos | Solo 7 |
-Form | Formulario multipart/form-data, con archivos | Solo 7 |
-SkipCertificateCheck | Ignora errores de certificado (solo laboratorio) | Solo 7 |
-OperationTimeoutSeconds | Tiempo máximo entre lecturas de datos de una descarga | Solo 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 declaraapplication/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/jsonsincharset=utf-8estropea 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. Conapplication/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
-Bodysin 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:
| Orden | Resultado | Aviso |
|---|---|---|
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étodo | Cómo se envía | Ejemplo de servicios |
|---|---|---|
| Clave de API | Un encabezado propio, como X-Api-Key | Herramientas de monitoreo, mesas de servicio, servicios de terceros |
| Autenticación básica | Authorization: Basic con usuario y contraseña en Base64 | Equipos de red y consolas antiguas |
| Token Bearer | Authorization: Bearer <token> | GitHub, Microsoft Graph, Azure y la mayoría de API modernas |
| OAuth 2.0 | Primero se pide un token a un servidor de autorización y luego se usa como Bearer | Microsoft 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 responde | Invoke-RestMethod devuelve |
|---|---|
| Un objeto JSON | Un PSCustomObject con una propiedad por campo |
| Un arreglo JSON | Un arreglo de objetos (Object[]); uno de un solo elemento sigue siendo arreglo |
| Un arreglo JSON vacío | Un arreglo vacío, no $null |
| XML o RSS | En RSS, los elementos item ya separados (dos noticias, dos objetos con title y link) |
| Texto | Una cadena |
| 204 sin contenido | Una cadena vacía |
| Una redirección 302 | Sigue 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:
| Respuesta | Windows PowerShell 5.1 | PowerShell 7.7 |
|---|---|---|
application/json; charset=utf-8 | Bogotá | Bogotá |
application/json sin charset | Bogotá · Señal débil | Bogotá · Señal débil |
text/plain sin charset | Bogotá | 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ón | Windows PowerShell 5.1 | PowerShell 7.7 |
|---|---|---|
| 404 de la API | System.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:
| Respuesta | Peticiones que recibió la API | Tiempo |
|---|---|---|
| 401 sin autorización | 4 | 3,0 s |
| 404 no existe | 4 | 3,1 s |
| 500 fallo del servidor | 4 | 3,1 s |
| 404 en un POST | 4 POST | 3,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 local | Windows PowerShell 5.1 | PowerShell 7.7 |
|---|---|---|
| Con la barra de progreso (por defecto) | 41,6 s | 0,1 s |
Con $ProgressPreference = 'SilentlyContinue' | 0,2 s | 0,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
- Olvidar
-ContentTypeen un POST. PowerShell declara formulario y la API rechaza el JSON. application/jsonsincharset=utf-8en Windows PowerShell 5.1. Las tildes salen en Latin-1 y el JSON llega inválido.ConvertTo-Jsonsin-Depth. A partir del tercer nivel, la API recibe el nombre de un tipo en lugar del dato, sin aviso en 5.1.- Respuestas sin
charseten 5.1. «Bogotá» se guarda como «Bogotá» sin ningún error. - Usar
curlen 5.1 creyendo que es curl. Es Invoke-WebRequest con otro nombre. - Invoke-WebRequest sin
-UseBasicParsingen 5.1. Puede quedarse bloqueado esperando una interacción que nadie ve. - No poner tiempo de espera. El valor por defecto es infinito.
-MaximumRetryCounten operaciones que crean algo. Repite el POST con cualquier error 4xx o 5xx.- Capturar
[System.Net.WebException]. En PowerShell 7 el error es otro tipo y elcatchno lo atrapa. - Dejar la barra de progreso en descargas de 5.1. Una descarga de 50 MB pasó de 0,2 a 41,6 segundos.
- Escribir la dirección de Graph entre comillas dobles.
$selecty$topse pierden como variables vacías. - Tokens y claves dentro del script. Léalos de un almacén de secretos o de una variable de entorno protegida.
-SkipCertificateChecken producción. Anula la protección de HTTPS.- Tratar un arreglo de un elemento como objeto al enviarlo. Por la canalización,
ConvertTo-Jsonlo convierte en objeto; use-InputObject. - Canalizar la respuesta directamente. Un arreglo JSON entra como un solo objeto; ponga la llamada entre paréntesis.
- Variables que solo cambian en mayúsculas. Para PowerShell,
$by$Bson la misma variable. Al preparar este artículo, un$bcon el cuerpo de la petición pisó la variable$Bcon 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,-TimeoutSecy 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-Aftery 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.




