Veeam Backup: Swagger REST API

En este artículo hablaremos de: “Backup Enterprise Manager REST API” que es una API cliente servidor que permite consultar y administrar Veeam Backup.

La comunicación con la API es vía el protocolo https y la API retorna una respuesta en formato JSON. 

Parece que el futuro de la automatización y de la administración de aplicaciones pasa por usar API’s https. 

Cada vez más fabricantes están desarrollando API’s para la administración y así múltiples sistemas y aplicaciones pueden conectar y ejecutar acciones o consultas sobre las aplicaciones.

HTTPS + JSON son dos elementos muy bien integrados con PowerShell es por este motivo que en este post vamos a explicar cómo monitorizar Veeam Backup mediante PowerShell.

Para utilizar la API, debemos autenticarnos y obtener un token de seguridad. Una vez autenticados, podemos realizar consultas y ejecutar acciones utilizando los endpoints correspondientes.

Podéis descargar Veeam Backup & Replication de forma gratuita en la siguiente ubicación: https://vee.am/9aKtYw

Swagger Veeam Backup & Replication REST API

El primer paso para conocer las capacidades de la REST Api de Veam Backup es abrir la consola de referencia Swagger:

Desde Veeam abrimos el menú de opciones -> Console -> Swagger que nos abrirá una ventana de navegador. Puede ser que nos avise de que el certificado no es válido, aceptamos y continuamos hasta llegar a esta página:

Mediante esta consola podremos explorar (y ejecutar) los comandos disponibles para la API.

Conceptos básicos de la API:

Cuando trabajamos con APIs, es importante comprender los diferentes tipos de comandos que podemos utilizar. A continuación, presentamos los cuatro tipos de comandos más comunes en una API:

GET: Obtienen información, son inofensivos ya que sólo lanzan consultas. Son los comandos recomendados para empezar a testear. Con comandos GET no podemos “romper” nada.

POST: Comandos de creación o ejecución de acciones. Son peligrosos y es mejor revisar dos veces antes de lanzarlos. Crean cosas y lanza cosas.

PUT: Comandos de edición, normalmente modifican cosas que ya existen.

DELETE: Comando de eliminación, los más peligrosos de todos los comandos.

Aquí vemos algunos ejemplos reales de cada tipo de comando.

Explorando y jugando con la API

Ahora que ya sabemos que tipos de comandos se pueden lanzar a través de la API podemos dedicarnos a navegar por el explorador Swagger de la API.

Por ejemplo, buscaremos en el listado “Jobs” el comando “GET” “/api/v1/Jobs/states”

En la propia descripción del comando nos informa que sirve para obtener un array con todos los Jobs:

“The HTTP GET request to the /api/v1/jobs/states path allows you to get an array of all job states. The states include brief job information that you can also find under the Jobs node in the Veeam Backup & Replication console.”

Al abrir el desplegable podemos visualizar toda la información del comando:

Lo abriremos y probaremos un poco como funciona con el botón “Try it out” que nos rellenará automáticamente los parámetros para lanzarla. En este momento no nos funcionará porque todavía no nos hemos autenticado contra la API pero nos ha servido para navegar y ver los comandos y opciones disponibles.

Autenticar el API de Veeam

El primer paso para crear una sesión contra Veeam API es crear un token de autenticación. Entraremos en el Veeam Swagger y buscaremos:

POST: /api/oauth2/token y lo desplegaremos:

Una vez desplegado pulsaremos sobre el botón: “Try it out”.

Marcamos en el “grant_type” como “password”.

Rellenaremos los campos “username” y “password” con los mismos usuarios que utilizamos para validarnos con Veeam. (Si usamos la autenticación de Windows sería el mismo login y pasword de Windows).

Después pulsamos el botón “Execute”:

Y si todo está correcto se nos generará un token de acceso:

También aparecerá un ejemplo con el comando de Curl que deberíamos ejectuar (que nos será muy muy útil cuando escriptemos en powershell) así como la URL llamada (también muy útil para el futuro script).

Seleccionaremos todo el contenido de la clave que aparece en “Access_token” (la parte superior ofuscada de la captura) y la copiaremos reservaremos (por ejemplo en un notepad).

Nos vamos a “Authorize” o a cualquiera de los candados que haya:

En el formulario que se abre añadimos el texto de la clave que hemos reservado en el notepad con el siguiente formato: 

Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Ahora ya tendremos autorizada nuestra sesión para lanzar comandos que necesiten autorización.

Testear los Jobs mediante Swagger

Ahora que ya estamos autorizados volveremos a buscar el comando: /api/v1/jobs/states

Y pulsaremos “Try it out” y después “Execute”:

Y obtendremos el siguiente resultado:

1.    El comando de curl que se ha ejecutado con todos sus parámetros (¡Muy útil!)

2.    El resultado de la consulta HTTPS (200 es OK).

3.    El contenido del resultado, con todos los datos de cada job.

Mediante este pequeño ejercicio habremos podido empezar a jugar con el API de Veeam, hemos aprendido como validarnos, cómo ejecutar comandos, ver qué comandos se ejecutan, qué código retorna y que objeto json nos retorna.

El autor de este post es: Pol Padrisa