Atacar vCloud Director REST API con Powershell

Hola, en este post vamos a ver cómo atacar la REST API de vCloud Director con Powershell. En ocasiones, cuando utilizamos herramientas como en este caso vCloud, nos podemos encontrar con funcionalidades o configuraciones que únicamente se pueden realizar mediante REST API o incluso automatizar despliegues, configuración de Edges, catálogos, etc.

Es cierto que hay módulos de PowerCLI para vCloud y NSX que ayudan a realizar varias acciones, pero aún así, me he encontrado situaciones en las que por la versión de vCloud o NSX, he tenido que realizar operaciones utilizando la API.

Bien, para atacar a una API, podemos utilizar el programa que os comenté en mi anterior post, Postman. A continuación, veremos que pasos seguir para poder atacar a la API de vCloud Director mediante la herramienta y llamadas web request.

Para ello lo principal es realizar la conexión contra la API y que nos devolverá el token necesario para poder realizar operaciones contra ella (GET,PUT,POST,DELETE). Pero antes de empezar, debemos conocer que respuestas obtendremos con cada uno de los métodos, para saber interpretar los response codes como resultado de los web request.

Bien, ahora que hemos conocido los response code, vamos a ver como realizar la conexión contra nuestra vCloud REST API. Para ello, echemos un ojo al interfaz de Postman.

En ella, podemos identificar, los siguientes puntos:

Método para Web Request: Aquí configuraremos el tipo de método que queremos realizar. vCloud Director, acepta los siguientes métodos:
- GET
- PUT
- POST
- DELETE
Espacio para Request URL: Aquí introduciremos la url de nuestro vCloud Director y sobre la que lanzaremos el web request.
Espacio para configurar nuestro Web Request:
- Parámetros: Parámetros necesarios que se pasen a nuestro web request.
- Authorization: Configuraremos los métodos de autenticación para lanzar los web request. (En nuestro caso utilizaremos Basic Authentication)
- Headers: Configuraciones para configurar el código aceptado para el web request, para la aceptación del código de respuesta, etc.
- Body: Aquí, incluiremos el código, ya sea en XML o JSON para realizar métodos como POST, PUT o DELETE.

Bien, ahora que conocemos un poco más la herramienta, vamos a ello. Para conectar a nuestra REST API de vCloud, atacaremos a la siguiente URL <https://<fqdn_vcloud/api/sessions>> y el método a realizar será POST. Bien, continuamos, ahora vamos con la autenticación, para ello, como he dicho anteriormente utilizaremos Basic Authentication. Es importante, identificarse con tu usuario de vcloud, que lógicamente deberá tener permisos. El formato de usuario será «usuario@system».

Cuando hagamos Preview Request, se añadirá en la pestaña Headers una entrada temporal como «Authorization», como podemos ver en la imagen. En la pestaña Headers, configuraremos el header «Accept» con el siguiente valor «application/*+xml;version=32.0».

Vale, ahora estaríamos preparados para realizar nuestro web request y conectar contra la REST API.

Una vez realizada, lo importante es lo siguiente, que haya salido bien, para ello lo sabremos con el código de respuesta. Y si ha salido bien, habremos obtenido nuestro token o x-vcloud-authorization.

Ahora ya podemos realizar operaciones contra nuestra REST API, simplemente poniendo la URL correcta, el método y por supuesto debemos aplicar una entrada en la pestaña Headers e incluiremos el token obtenido como nuevo header.

Bien, ahora que ya sabemos atacar a la REST API, mediante la herramienta, os vot a dejar la función para poder conectar a la REST API y así automatizar tareas que queráis realizar contra la REST API.

Function Get-xvCloudAuthorization
{
           param(
           [Parameter(
           Position=0,
           Mandatory=$true,
           ValueFromPipeline=$true,
           ValueFromPipelineByPropertyName=$true)
           ]
           [String]$BaseUrl,
           [String]$Username,
           [SecureString]$Password
           )
           #Convertimos la Password en UnsecureString
           $UnsecurePassword = (New-Object PSCredential                                  
           $Username,$Password).GetNetworkCredential().Password
           # Codificamos la conexión con $user@system:$password para Basic Authentication
           $base64auth = [convert]::ToBase64String([text.encoding]::ASCII.GetBytes("$($Username):$($UnsecurePassword)"))

           # Fijamos la URL para conectar a REST API
           $url = $BaseUrl + "/sessions"

           Write-Host "Lanzando conexión a REST API a la url [** $url **] : " -ForegroundColor Yellow -NoNewline

           #Parametros de conexión <Accept> y <Authorization>
           $params = @{
           Accept = "application/*+xml;version=32.0";
           Authorization = "Basic $($base64auth)";
           }

           $response = Invoke-WebRequest -Uri $url -Method Post -Headers $params
           $authtoken = [regex]::Match($response.RawContent, "x-vcloud-authorization:\s(?<authtoken>.*)\s").groups["authtoken"].value
           Write-Host "[OK] Conexión establecida a la url [** $url **]" -ForegroundColor Green
           return $authtoken
}

Para llamar a la función podemos realizarlo de la siguiente manera:

$credentials = Get-Credential -Message "Introduce credenciales con permisos para vCloud Director"

$username = $credentials.Username

$securepass = $credentials.Password

$base_url = "https://vcloudVM.cloudvm.es/api"

# Llamada a la función

$token = Get-xvCloudAuthorization -BaseUrl $base_url -Username $username -Password $securepass

Bien, ahora que tenemos el token, ya podemos realizar métodos como GET, POST, PUT o DELETE.

Os dejo alguna función para realizar GET REQUEST, pasando la URL y el token obtenido de la sesión.

Function GetRequest-RESTAPI
{
            param(
            [Parameter(
            Position=0,
            Mandatory=$true,
            ValueFromPipeline=$true,
            ValueFromPipelineByPropertyName=$true)
            ]
            [String]$UrlRequest,
            [String]$Auth_XCloud
            )
             # Fijamos los Headers
            $param_headers = @{"Accept" = "application/*+json;version=32.0";"x-vcloud-authorization" = $Auth_XCloud;"Content-Type" = "application/json"}
            # Realizamos el Get Request a la REST API y devolvemos la respuesta en formato convertido desde JSON
            $response_request = Invoke-WebRequest -Uri $UrlRequest -Headers $param_headers -Method Get | ConvertFrom-Json

            # Devolvemos la respuesta
            return $response_request
}

Para realizar métodos como PUT o POST, debemos tener en cuenta que debemos incluir el body, para realizar estos métodos, por lo que debemos tener muy claro que es lo que queremos realizar.

Bien, pues por último os dejo algunos links que os serán de ayuda:

https;//fqdn_vcloud_director/api-explorer/provider –> Aquí, podemos ver que acciones podemos realizar como Provider contra la REST API, e incluso podremos ejecutarlas. Es muy útil si queréis comenzar a familiarizaros con la REST API. Utiliza JSON para tanto el cuerpo de la respuesta a las consultas (GET), como para el body para reailzar UPDATE (PUT) o crear (POST).

https://docs.vmware.com/es/vCloud-Director/index.html –> Página con documentación sobre la REST API de vCloud y todo la jerarquía de páginas.

Pues hasta aquí el post, espero que os haya sido útil. Si te ha gustado, podéis compartirlo 😉

Si te ha gustado, comparte el post:

Leave a Reply Cancelar la respuesta