El uso de API REST para ampliar sus scripts es una característica útil de poner en práctica. Puede obtener acceso a nuevas funcionalidades y se amplían las posibilidades de crear nuevos scripts más avanzados.
Pero la experiencia para muchos al comenzar a utilizar API REST en scripts es que se siente bastante torpe y antinatural. En esta publicación discutimos:
- Que es una API REST
- Cómo leer la forma de documentación más común
- Cómo utilizar una API REST con PowerShell
- Algunos consejos y trucos acerca de cómo hacer que sea una experiencia mejor y más fácil
¿Qué es REST?
REST, o API RESTful, es una API que utiliza solicitudes HTTP para buscar, agregar, borrar o manipular datos en diferentes servicios.
Lo que queremos hacer con los datos de forma general se decide por lo que Método HTTP que usas. Aquí hay una lista resumida de métodos HTTP y lo que se usan para hacer en una API REST:
- OBTENER — Leer
- PUBLICAR: crear
- PARCHE: actualización / modificación parcial
- PUT: actualizar o reemplazar
- BORRAR: Quitar
Los datos devueltos por una API REST de forma general se devuelven en formato JSON.
¡Ahora, comencemos con nuestra primera llamada a la API!
Leer los documentos
Aprender a leer e interpretar la documentación de diferentes API REST es esencial para usarlas. Por suerte, si sabe cómo leer un estilo de documentación, puede aprender rápidamente a leer otros.
Estamos usando petstore.swagger.io en este post, dado que utiliza el popular Pavonearse framework que es bastante común de hallar en el mundo real.
La imagen anterior muestra la información más esencial sobre los puntos finales de la API REST:
- Método HTTP: GET / POST / DELETE, etc.
- URL relativa al punto final de la API REST (la URL base de forma general se presenta en la parte de arriba de la página de documentación)
- Una breve descripción
Entrar en los detalles
La primera página de la documentación es excelente y, por lo general, puede realizar la mayoría de las llamadas que requieren el método HTTP GET con esa información. Pero métodos como POST y SET de forma general requieren que haga clic y expanda la fila para obtener más información.
Si hace clic en una de las filas, se le presenta información semejante a esta:
Aquí, presentamos el punto final REST que puede crear un nuevo objeto mascota. Especifica cómo debe verse el JSON que se proporcionó en el cuerpo del POST y qué tipo de contenido acepta. Otros puntos finales REST especifican cuáles son sus diferentes parámetros, qué tipo de datos debería ser, etc.
Eso es lo básico para leer la documentación. Ahora que es claro, es hora de comenzar a utilizar las API REST con PowerShell.
OBTENGA (ting) sus primeros datos
El uso de API REST con PowerShell suele ser bastante sencillo y está usando cmdlets integrados, por lo que no se necesitan módulos adicionales. Obtendrá datos a través de el método GET en / pet / {petId} punto final.
Si expande el / pet / {petId} endpoint en la documentación, puede ver que {petId} es en realidad un parámetro que toma un número entero.
Eso hace que la URL para buscar el objeto mascota con id 1: https://petstore.swagger.io/v2/pet/1
La documentación de SWAGGER REST API de forma general presenta la URL base en la parte de arriba de la página.
Ahora, comencemos con PowerShell. Abra una ventana de Terminal e ingrese:
PS51 > Invoke-RestMethod -Method GET -ContentType "application/json" -Uri "https://petstore.swagger.io/v2/pet/1"
id : 1
category : @{id=0; name=string}
name : doggie
photoUrls : {string}
tags : {@{id=0; name=string}}
status : availableInvocar-RestMethod convierte el JSON devuelto automáticamente en un objeto, dado que el tipo de contenido «application / json» se devuelve en la solución del servidor.
Error 404 - Not foundde forma general significa que no se puede hallar el objeto, no que la URL esté mal escrita.
Ahora ha realizado con éxito su primera llamada a la API REST. Pero solo poder OBTENER datos es bastante limitante, por lo tanto creemos algo con el método POST.
Crear un objeto con el método POST
El método POST se utiliza más comúnmente para crear, como crear usuarios o entradas, etc. Una solicitud POST envía un BODY que contiene información al punto final REST, de forma general en formato JSON, pero además puede ser un formulario codificado en URL.
Aprenderá a crear un objeto JSON que puede PUBLICAR en el /mascota punto final.
Puede ver cómo se supone que debe verse el JSON si expande el POST / mascota fila en la documentación.
Comencemos creando una tabla hash que posteriormente podamos convertir en un objeto JSON. El JSON sin formato debe evitarse en los scripts de PowerShell debido a que limita sus capacidades.
$Body = @{
id = 19
category = @{
id = 45
name = "Whatever"
}
name = "Dawg"
photoUrls = @(
"string"
)
tags = @(
@{
id = 0
name = "string"
}
)
status = "available"
}Si tiene dificultades para crear una tabla hash que se convierta al JSON que desea, instale el PsdKit módulo y use el comando:
$JsonString | ConvertTo-Psd
Ahora dispone de una tabla hash que puede convertir en una cadena JSON y POST en el /mascota punto final:
$JsonBody = $Body | ConvertTo-Json
$Uri = "https://petstore.swagger.io/v2/pet"
Invoke-RestMethod -ContentType "application/json" -Uri $Uri -Method Artículo -Body $JsonBody
id : 19
category : @{id=45; name=Whatever}
name : Dawg
photoUrls : {string}
tags : {@{id=0; name=string}}
status : availableCuando se crea el objeto, regularmente recibe el objeto que se creó para su confirmación.
Usando DELETE
El método DELETE elimina datos, y la forma de hacerlo es bastante semejante al método GET como se demuestra aquí:
PS51 > Invoke-RestMethod -Method DELETE -ContentType "application/json" -Uri "https://petstore.swagger.io/v2/pet/1"Solo tenga en cuenta para no borrar nada que pueda necesitar.
Usando PUT
El método PUT actualiza los datos ya existentes. Esto se hace de manera semejante al método POST, enviando un objeto JSON completo o parcial:
PS51> $Body = [PSCustomObject]@{
id = 19
name = "Dawg with a new name"
}
PS51> $JsonBody = $Body | ConvertTo-Json
PS51> $Uri = "https://petstore.swagger.io/v2/pet"
PS51> Invoke-RestMethod -ContentType "application/json" -Uri $Uri -Method PUT -Body $JsonBody
id name photoUrls tags
-- ---- --------- ----
19 Dawg with a new name {} {}Por lo general, la API REST devuelve un objeto JSON con los datos usados y / o actualizados. Puede ver que el objeto se actualizó usando el método GET hacia él:
PS 51> Invoke-RestMethod -ContentType "application/json" -Uri "https://petstore.swagger.io/v2/pet/19"
id : 19
category : @{id=45; name=Whatever}
name : Dawg with a new name
photoUrls : {string}
tags : {@{id=0; name=string}}
status : availableCreando funciones
Escribir estos comandos tal como están puede volverse bastante tedioso y no es verdaderamente escalable. Si llamamos a un punto final más de una vez, cree una función para él. Es bastante simple y solo se necesitan unas pocas líneas:
Function Get-PetstorePet {
[cmdletbinding()]
param(
# Id of the pet
[Parameter(Mandatory,ValueFromPipeline)]
[int]$Id
)
Begin{}
Process{
$RestMethodParams = @{
Uri = "https://petstore.swagger.io/v2/pet/$Id"
ContentType = "application/json"
Method = "GET"
}
Invoke-RestMethod @RestMethodParams
}
End{}
}Después de crear su función, puede llamarla en su script:
PS51> Get-PetstorePet -Id 1
id name photoUrls tags
-- ---- --------- ----
1 Doggie {http://picture.dirección url} {} Puede hacer esto para el método POST y para crear una nueva mascota en la tienda de mascotas:
Function Add-PetstorePet {
[cmdletbinding()]
param(
# Id of the pet
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[int]$Id,
# Name of the pet
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[string]$Name,
# Status of the pet (available, sold etc)
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[string]$Status,
# Id of the pet category
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[int]$CategoryId,
# Name of the pet category
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[string]$CategoryName,
# URLs to photos of the pet
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[string[]]$PhotoUrls,
# Tags of the pets as hashtable array: @{Id=1;Name="Dog"}
[Parameter(Mandatory,ValueFromPipelineByPropertyName)]
[Hashtable[]]$Tags
)
Begin{}
Process{
$Body = @{
id = $Id
category = @{
id = $CategoryId
name = $CategoryName
}
name = $Name
photoUrls = $PhotoUrls
tags = $Tags
status = $Status
}
$BodyJson = $Body | ConvertTo-Json
$RestMethodParams = @{
Uri = "https://petstore.swagger.io/v2/pet/"
ContentType = "application/json"
Method = "Artículo"
Body = $BodyJson
}
Invoke-RestMethod @RestMethodParams
}
End{}
}Y llamar a esta función de PowerShell después hace que esta tarea bastante larga sea mucho más fácil:
PS51> $AddPetStorePetsParams = @{
Id = 44
Name = "Birdie"
Status = "available"
CategoryId = 50
CategoryName = "Hawks"
PhotoUrls = "https://images.contoso.com/hawk.jpg"
Tags = @(
@{
Id=10
Name="Not eagles"
}
)
}
PS51> Add-PetStorePet @AddPetStorePetsParams
id : 44
category : @{id=50; name=Hawks}
name : Birdie
photoUrls : {https://images.contoso.com/hawk.jpg}
tags : {@{id=0}}
status : availableLo más probable es que muchos de los módulos que utiliza a diario estén hechos de funciones que solo usan API REST en segundo plano.
Resumen
Aprender a utilizar las API REST se trata principalmente de aprender a leer la documentación. Usamos documentación basada en SWAGGER en esta publicación, dado que representa cómo pueden verse otros estilos de documentación.
Al mismo tiempo, convertir sus llamadas a la API en una función puede ahorrarle mucho tiempo, facilitar su trabajo y limpiar sus scripts.
