¿Necesita integrar datos externos de servicios web en sus scripts de PowerShell? En este tutorial práctico, aprenderá cómo consultar las API REST usando PowerShell y analizar los resultados sin ningún problema. Construiremos una herramienta reutilizable que maneje los errores con elegancia y devuelva datos limpios y estructurados.

Exploremos esto trabajando con una API gratuita de códigos postales.io que proporciona datos del código postal del Reino Unido.

Conceptos básicos: realizar su primera llamada API

La forma más sencilla de consultar una API REST con PowerShell es utilizar el Invoke-WebRequest cmdlet. Piense en ello como un navegador web de línea de comandos: llega a cualquier URL y descarga cualquier contenido que esté disponible.

$result = Invoke-WebRequest -Uri 'http://api.postcodes.io/random/postcodes'

Cuando ejecuta este comando, obtendrá varias propiedades, pero las más importantes son:

• Código de estado: debe ser 200 para una solicitud exitosa
• Contenido: los datos reales devueltos por la API.

Veamos qué hay en esa propiedad de Contenido:

Lo que verá son datos JSON que contienen información del código postal. Pero hay un problema: este contenido es sólo una cadena:

$result.Content.GetType().FullName
# Returns: System.String

Para trabajar realmente con estos datos en PowerShell, debe convertirlos de JSON a objetos. He aquí cómo:

$objResult = $result.Content | ConvertFrom-Json
$objResult.result

La mejor manera: usar Invoke-RestMethod

Mientras Invoke-WebRequest funciona, PowerShell tiene un cmdlet mejor diseñado específicamente para trabajar con API REST: Invoke-RestMethod. Aquí está la magia: convierte automáticamente las respuestas JSON en objetos PowerShell:

$response = Invoke-RestMethod -Uri 'http://api.postcodes.io/random/postcodes'
$response.result

Mucho más sencillo, ¿verdad? ¡No se necesita conversión JSON manual!

Construyendo una herramienta reutilizable

Llevemos esto al siguiente nivel y creemos un script reutilizable. Crearemos una herramienta que pueda:

• Aceptar diferentes puntos finales de API
• Maneje los errores con gracia
• Devolver resultados bien formateados

Aquí está nuestro script (guárdelo como Get-RandomPostCode.ps1):

[CmdletBinding()]
param(
    [Parameter()]
    [string]$Uri = 'http://api.postcodes.io/random/postcodes'
)

$response = Invoke-RestMethod -Uri $Uri -SkipHttpErrorCheck -StatusCodeVariable respStatus
if ($respStatus -ne 200) {
    throw "API query failed: $_"
} else {
    [PSCustomObject]@{
        Postcode = $response.result.postcode
        Country  = $response.result.country
        Region   = $response.result.region
        Latitude = $response.result.latitude
        Longitude = $response.result.longitude
        JSONFullResponse = $response
    }
}

Analicemos lo que hace este script:

1. Acepta un parámetro URI personalizado con un valor predeterminado
2. Utiliza -SkipHttpErrorCheck y -StatusCodeVariable para un mejor manejo de errores
3. Devuelve un objeto personalizado limpio con solo las propiedades que nos interesan
4. Incluye la respuesta JSON completa si es necesario para solucionar problemas

Para utilizar el guión:

# Get a random postcode using the default API endpoint
.\Get-RandomPostCode.ps1

# Try a custom endpoint (this will demonstrate error handling)
.\Get-RandomPostCode.ps1 -Uri 'https://oops.postcodes.io'

Una nota sobre el manejo de errores

En PowerShell 7+, tenemos algunas características interesantes para manejar errores de API. El -SkipHttpErrorCheck El parámetro le dice a PowerShell que no arroje errores en el flujo de errores (evitando ese aterrador texto rojo), mientras que -StatusCodeVariable Comprobemos el código de estado HTTP nosotros mismos.

Si está utilizando una versión anterior de PowerShell, puede utilizar este método alternativo de manejo de errores:

$ErrorActionPreference="Stop"
try {
    $response = Invoke-RestMethod -Uri $Uri
    $response.result
} catch {
    throw "API query failed: $_"
}

Consejos profesionales

1. Verifique siempre el código de estado: el hecho de que una API haya respondido no significa que haya funcionado
2. Considere devolver objetos personalizados en lugar de respuestas API sin procesar: hace que sus scripts sean más profesionales y más fáciles de usar.
3. Incluya la respuesta API completa en sus objetos de salida para solucionar problemas

Próximos pasos

Ahora que sabe cómo trabajar con las API REST en PowerShell, puede:

• Integre datos de cualquier servicio web en sus scripts
• Cree funciones contenedoras para sus API favoritas
• Cree herramientas que combinen datos de múltiples fuentes

¡Las posibilidades son infinitas! Sólo recuerde: consulte siempre la documentación de la API para conocer los requisitos de autenticación y los límites de velocidad antes de crear herramientas de producción.

¿Qué API planea integrar con PowerShell? ¡Déjamelo saber en los comentarios!