Introduccion al uso de la API Cyberwatch
Los usuarios de Cyberwatch tienen acceso a una API que permite interactuar con la mayor parte de los recursos visibles en la aplicación. Este acceso puede permitir, por ejemplo, la automatizacion de ciertas tareas, o la obtencion de resultados personalizados…
Esta pagina es una introduccion al funcionamiento y al uso de esta API.
Interactuar con la API Cyberwatch
La API Cyberwatch devuelve respuestas en formato JSON, por lo que es posible usar de forma nativa un cliente curl, el cmdlet PowerShell Invoke-WebRequest, o nuestro cliente Python para consultarla.
Autenticarse ante la API y probar su conexión
El uso de la API, sea cual sea la ruta consultada, requiere autenticarse con las claves de API de un usuario Cyberwatch con rol Administrador.
Estas claves de API se pueden generar desde la GUI de Cyberwatch, en la pestaña Mi perfil > Claves de API, de cada Administrador Cyberwatch.
Estas credenciales se pueden usar mediante los dos modos de autenticación propuestos: el basic-auth y el apiAuth. Documentamos el uso de curl, el cmdlet PowerShell Invoke-WebRequest, o nuestro cliente de API Python. El modo de autenticación privilegiado en los ejemplos de nuestra documentación es el basic-auth. Mas información sobre el apiAuth esta disponible aquí.
Probar su conexión
Los comandos referenciados a continuación permiten comprobar la validez del identificador usado y efectuan una prueba de comunicación con su API Cyberwatch. En caso de exito, se devuelve un id de usuario.
Esta consulta solo requiere un identificador de API con derechos de solo lectura. Por lo tanto, mas adelante puede ser necesario verificar el nivel de acceso del identificador usado en función de las solicitudes que se realicen.
Encontrara adjuntos ejemplos detallados de la ejecución de esta prueba de conexión vía curl, el cmdlet PowerShell Invoke-WebRequest, o nuestro cliente de API Python.
Diagnosticar problemas de conexión
Se encuentra con un error 401
Un error 401 significa que la autenticación ha fallado. Para resolverlo, primero hay que comprobar que las claves introducidas son correctas. En segundo lugar, también debe verificar que la URL corresponde a la instancia Cyberwatch deseada.Se encuentra con un error 403
Cuando aparece este error, hay un problema de privilegios. Es posible que las claves de API se hayan generado con una cuenta que no tiene derechos de administrador. Otro caso posible es el uso de claves que no tienen acceso a la API, por ejemplo las de instalación de agentes. Para verificar estos elementos, debe ir a la interfaz web de la aplicación Cyberwatch. Una vez conectado, vaya a la pagina "Mi perfil". El campo "Rol" corresponde al nivel de privilegio de su cuenta. Para usar la API, este debe ser "Administrador". Luego vaya al final de la pagina y haga clic en "Ver mis claves de API". Entonces tendrá el detalle de las claves de API vinculadas a su cuenta, así como su nivel de derecho. Con el único objetivo de recuperar datos desde la API, el modo "Solo lectura" sera suficiente. De lo contrario, la clave debe tener el nivel de acceso "Completo".Estructura de las rutas y de las respuestas de la API
Los diferentes puntos de acceso de la API se pueden consultar desde una documentación Swagger accesible desde su aplicación mediante el botón </> situado en la esquina superior derecha de la pagina.
Desde Swagger, cada sección describe la ruta utilizada así como la lista de parámetros disponibles y un ejemplo de la estructura de datos devuelta por la solicitud. Ademas, es posible generar la lista en formato OpenAPI desde aquí, para importarla en otras herramientas como Postman. Swagger también permite generar directamente solicitudes curl autenticadas y ejecutarlas al vuelo, para probar las respuestas de la API de su instancia.
Como para cualquier solicitud a la API, Swagger requiere autenticarse mediante un identificador de API como se indico anteriormente.
Recomendamos configurarlos directamente mediante el formulario Authentication de Swagger. Cuando las credenciales se proporcionan de esta forma, Swagger genera directamente el encabezado de autenticación curl, lo que hace que el comando sea facilmente reutilizable.
Clientes de API obsoletos
Desde la version 13.0 de Cyberwatch, nuestros antiguos clientes de API PowerShell y Python están obsoletos.
Para cualquier pregunta sobre el tema, o necesidad de acompañamiento en la migración de un script de API de una version anterior a la nueva, puede contactarnos por correo electronico en support@cyberwatch.com, o por telefono al +33 1 84 80 88 84.