Búsqueda de sitios web

Cómo utilizar Invocar RestMethod en PowerShell

Cuando necesite interactuar con una API REST en PowerShell, deberá utilizar el cmdlet Invoke RestMethod. Este cmdlet le permite enviar solicitudes HTTP(S) a un servicio web REST desde su línea de comandos o script de PowerShell.

Las API REST se pueden utilizar para gestionar todo tipo de servicios o extraer datos de ellos. Pero tenga en cuenta que a menudo hay módulos PowerShell disponibles para servicios populares, como Azure, Graph, GitHub, etc. ¡Así que asegúrese de verificarlo antes de comenzar!

En este artículo, veremos cómo realizar llamadas a la API REST desde PowerShell con el cmdlet Invoke-RestMethod.

Método PowerShell Invoke-Rest

El cmdlet PowerShell Invoke-RestMethod le permite trabajar con API REST. Admite todos los métodos HTTP necesarios, como Get, Post, Put, etc., y autenticación. Una ventaja del cmdlet es que convertirá automáticamente las respuestas JSON o XML en objetos pscustomobjects en PowerShell.

Para realizar una llamada a la API REST, necesitará el URI al que enviar la solicitud, probablemente el método de autenticación y, por supuesto, saber qué método utilizar. De forma predeterminada, el cmdlet utilizará el método GET, pero otros métodos utilizados habitualmente son:

  • OBTENER : recupera datos de un punto final específico.
  • POST: envía datos al servidor para crear un nuevo recurso
  • PUT: actualiza un recurso existente en el servidor.
  • PATCH: similar a PUT, pero envía solo los datos que se modifican al servidor
  • DELETE: elimina recursos del servidor.

Recuperar datos

Comenzaremos con lo básico, recuperando datos de una API. Para recuperar datos, necesitaremos saber qué URI (punto final) usar. Prácticamente todas las API tienen documentación, donde puedes consultar los diferentes URI que puedes usar.

Nota

Para los ejemplos siguientes, utilizaremos esta API REST gratuita https://restful-api.dev/. Esta API no requiere ninguna autenticación y también le permite realizar solicitudes de transferencia, lo cual es excelente para aprender.

Para obtener todos los objetos de la API, solo necesitamos usar el cmdlet Invoke-RestMethod con un URI del cual queremos recibir los datos. Esta es una API abierta, por lo que no se requiere autenticación.

Invoke-RestMethod -Uri 'https://api.restful-api.dev/objects'

La API devuelve JSON, que el cmdlet Invoke-RestMethod convierte automáticamente en un objeto de PowerShell. Pero cuando la API devuelve varios objetos, los objetos se reciben como una matriz.

La selección de objetos específicos de una API REST a menudo se realiza mediante una consulta o especificando el ID del objeto. Por ejemplo, para seleccionar el Google Pixel 6 entre los objetos, podemos especificar el ID 1:

https://api.restful-api.dev/objects/1

Y como ahora solo se devuelve un objeto, también podemos usar directamente el cmdlet select-object para devolver solo el nombre del objeto:

https://api.restful-api.dev/objects/1 | Select name

# Result
name
----
Google Pixel 6 Pro

Usando parámetros de consulta

Para seleccionar objetos específicos de una API, deberá utilizar parámetros de consulta. Estos parámetros pueden ser parte del URI en el cmdlet Invoke-RestMethod o podemos usar un cuerpo JSON. Los parámetros que puede utilizar realmente dependen de la API.

Deberá consultar la documentación de la API para ver qué parámetros de consulta utiliza. Por ejemplo, el punto final que usamos en este ejemplo solo acepta ID como parámetro de consulta:

Invoke-RestMethod -uri 'https://api.restful-api.dev/objects?id=3&id=5'

# result
id name                    data
-- ----                    ----
3  Apple iPhone 12 Pro Max @{color=Cloudy White; capacity GB=512}
5  Samsung Galaxy Z Fold2  @{price=689,99; color=Brown}

Para darle otro ejemplo, podemos usar la API randomuser.me, que genera datos de usuario aleatorios. Esta API acepta múltiples parámetros que le permiten especificar qué tipo de datos de usuario desea generar.

Entonces, por ejemplo, podemos generar 5 usuarios, que todos tienen el género masculino y la nacionalidad holandesa:

Invoke-RestMethod -Uri 'https://randomuser.me/api/?gender=male&results=5&nat=nl' | select -ExpandProperty results | ft

Usando un cuerpo JSON

Especificar todos los parámetros en el URI puede hacer que su código sea más difícil de leer. Entonces, cuando necesita especificar varios parámetros, suele ser mejor utilizar un cuerpo JSON.

La ventaja del cuerpo JSON es que son más fáciles de leer y le permiten agregar o cambiar rápidamente parámetros en la solicitud.

Para realizar la misma solicitud que en el ejemplo anterior, podemos crear un cuerpo para Invoke-RestMethod con una tabla hash simple. También almacené el URI en una variable para que el ejemplo sea un poco más legible:

$uri = 'https://randomuser.me/api/'
$body = @{
    gender = 'male'
    nat = 'nl'
    results = '5'
}

Invoke-RestMethod -Uri $uri -Body $body | select -ExpandProperty results | ft

Incluso podemos almacenar todos los parámetros dentro de una tabla hash usando la técnica de splatting. En este caso, siempre es una buena idea especificar también el método de solicitud. He incluido el cuerpo dentro de la tabla hash, pero también puedes crear el cuerpo por separado si lo prefieres.

$parameters = @{
    Method = 'GET'
    Uri = 'https://randomuser.me/api/'
    Body =  @{
            gender = 'male'
            nat = 'nl'
            results = '5'
        }
    }

Invoke-RestMethod @parameters | select -ExpandProperty results | ft

Seguir enlaces de relación

Algunas API REST admiten el uso de enlaces de relación. Los enlaces de relación se usan comúnmente para la paginación, por lo que solicita miles de objetos en una sola llamada. Los enlaces de relación se indican en el encabezado del resultado.

Al utilizar el cmdlet Invoke RestMethod, puede acceder a estos vínculos de relación mediante el parámetro FollowRelLink. El parámetro MaximumFollowRelLink también le permite determinar cuántas páginas desea solicitar.

$url = 'https://api.github.com/repos/ruudmens/lazyadmin/issues'
Invoke-RestMethod $url -FollowRelLink -MaximumFollowRelLink 2

Envío de datos

También podemos usar PowerShell Invoke-RestMethod para enviar datos a una API REST. Para ello necesitaremos crear un cuerpo JSON con los datos que queremos enviar. Además, necesitará conocer el URI del punto final y utilizaremos el método correcto.

Si desea crear un nuevo objeto/recurso, deberá utilizar el método POST. Para actualizar un recurso existente, deberá utilizar el método PUT o PATH.

El primer paso es crear el cuerpo con el elemento que desea PUBLICAR en la API. La API REST de ejemplo que estamos usando requiere que el atributo de datos también sea un objeto JSON, pero a menudo puedes especificar los atributos directamente sin la tabla hash anidada:

$body = @{
    name = 'LazyPhone'
    data = @{
       year = 2024
       price = 399.99
       'Screen size' = 6.2
    }
}

Antes de que podamos PUBLICAR el nuevo objeto, necesitaremos asegurarnos de que el cuerpo se convierta en un objeto JSON. Podemos hacer esto con el cmdlet ConvertTo-JSON. También necesitamos especificar el ContentType que estamos enviando y por supuesto el método POST:

$parameters = @{
    Method = 'POST'
    Uri = 'https://api.restful-api.dev/objects'
    Body =  ConvertTo-JSON($body)
    ContentType = 'application/json'
}

Invoke-RestMethod @parameters

La mayoría de las API devolverán el objeto después de que lo haya PUBLICADO correctamente. Puede almacenar los resultados en una variable o redirigirlos a nulo si no desea que se envíen a la consola.

Invoke-RestMethod @parameters | Out-Null

Carga de archivos y contenido mixto

Cuando necesites cargar un archivo o una imagen a una API con PowerShell, a menudo necesitarás usarlo multipart/formdata para enviar tu objeto. Para esto, necesitará usar PowerShell 6 al menos, porque esto le permite usar el parámetro -Form.

Al igual que cuando usamos el parámetro del cuerpo, necesitamos crear una tabla hash para el parámetro del formulario:

$form = @{
    brand = 'LazyPhone'
    model = 'Snap 2'
    released = '2024-01-22'
    image = Get-Item -Path "c:\marketing\LazyPhone\"
}

$parameters = @{
    Method = 'POST'
    Uri = 'https://api.example.dev/phones'
    Form = ConvertTo-JSON($form)
    ContentType = 'application/json'
}

Invoke-RestMethod @parameters

Actualizar un objeto

La actualización de un objeto se realiza prácticamente de la misma manera que la creación de uno. La única diferencia aquí es que deberá especificar el objeto que desea actualizar.

Hay dos métodos que puede utilizar para actualizar un objeto, PUT y PATCH. El primero reemplazará todos los atributos del objeto, mientras que el segundo solo reemplazará los atributos que envíes.

$body = @{
    name = 'LazyPhone'
    data = @{
        color = 'Cloudy White'
        'capacity GB' = 512
    }
}

$parameters = @{
    Method = 'POST'
    Uri = 'https://api.restful-api.dev/objects/3'
    Body =  ConvertTo-JSON($body)
    ContentType = 'application/json'
}

Autenticación

Hasta ahora hemos utilizado API REST en nuestro ejemplo que no requieren ninguna autenticación. Pero la mayoría de las API REST requieren que usted se autentique antes de poder interactuar con ellas. Normalmente se utilizan tres métodos de autenticación:

  • Básico: autenticación simple basada en nombre de usuario/contraseña
  • Portador: requiere un parámetro de token
  • Clave API : combinación de clave de acceso y clave secreta

Los detalles de autenticación se proporcionan en el encabezado de la llamada. Esto se hace con el cmdlet Invoke-RestMethod mediante el parámetro -header.

Autenticación básica

La autenticación básica consta de un nombre de usuario y una contraseña codificados con base64. No son la opción más segura de usar hoy en día, por lo que no los encontrarás mucho. Para utilizar la autenticación básica, primero deberá crear un objeto de credencial en PowerShell.

$cred = Get-Credential

Luego podemos agregar el objeto de credencial al encabezado de la solicitud de API REST. Si está utilizando PowerShell 6 o superior, puede utilizar el parámetro -authentication y -credential:

Invoke-RestMethod -uri 'https://api.restful-api.dev/objects/' -Credential $cred -Authentication Basic

Cuando usa PowerShell 5, puede usar solo el objeto de credencial y deberá crear el encabezado con un objeto JSON:

$headers = @{
    Authorization = "Basic"
}

Invoke-RestMethod -uri 'https://api.restful-api.dev/objects/' -Headers $header -Credential $cred

Portador

El token de portador es un método de autenticación más utilizado. Utiliza un token que a menudo es necesario solicitar primero a la API REST. Depende de la API cómo se solicita el token y cuánto tiempo es válido.

Para usar el token, podemos usar el parámetro -Token (en PowerShell 6 o superior) o agregar el token en el encabezado.

$token = 'token-from-api'

Invoke-RestMethod -Uri $uri -Authentication Bearer -Token $token

O cuando use PowerShell 5.x:

$headers = @{
    'Authorization' = "Bearer $Token"
}

Invoke-RestMethod -Uri $uri -Headers $header

Clave API: secreta

La última opción de autenticación que quiero mostrarles es el método API Key/Secret. Muchas API hoy en día le permiten crear una combinación única de clave/secreto que puede usar para su aplicación.

Para usar la clave y el secreto para la autenticación, necesitaremos usar el encabezado X-ApiKeys. Al igual que con el otro encabezado, necesitarás crear un objeto de encabezado con la regla de encabezado X-ApiKeys:

$parameters = @{
    Method = 'PUT'
    Uri = 'https://api.restful-api.dev/objects/'
    Headers = @{
        "X-ApiKeys" = "accessKey=$($accessKey); secretKey=$($secretKey)"
    }
    ContentType = 'application/json'
}

Invoke-RestMethod @parameters

Concluyendo

Las API REST son una excelente manera de intercambiar información con otros sistemas. Tenga en cuenta que hay módulos PowerShell disponibles para muchos servicios populares. Así que asegúrese de comprobarlo antes de comenzar.

El cmdlet PowerShell Invoke RestMethod es más fácil de usar en PowerShell 7.x, por lo que realmente recomiendo que use la última versión cuando trabaje con una API REST.

Espero que este artículo te haya resultado útil. Si tiene alguna pregunta, simplemente deje un comentario a continuación.

Artículos relacionados