Introducció a l’ús de l’API de Cyberwatch

Els usuaris de Cyberwatch tenen accés a una API que permet interactuar amb la major part dels recursos visibles a l’aplicació. Aquest accés pot permetre, per exemple, automatitzar determinades tasques o obtenir resultats personalitzats…

Aquesta pàgina és una introducció al funcionament i a l’ús d’aquesta API.

Interactuar amb l’API de Cyberwatch

Com que l’API de Cyberwatch retorna respostes en format JSON, es pot utilitzar de manera nativa un client curl, la cmdlet de PowerShell Invoke-WebRequest o el nostre client Python per consultar-la.

Autenticar-se a l’API i provar la connexió

L’ús de l’API, sigui quina sigui la ruta consultada, requereix l’autenticació amb les claus d’API d’un usuari de Cyberwatch que tingui el rol Administrador.

Aquestes claus d’API es poden generar des de la interfície gràfica (GUI) de Cyberwatch, a la pestanya El meu perfil > Claus d’API de cada administrador de Cyberwatch.

Aquestes credencials es poden utilitzar amb els dos modes d’autenticació disponibles: el basic-auth i l’apiAuth. Documentem l’ús de curl, de la cmdlet de PowerShell Invoke-WebRequest i del nostre client d’API Python. El mode d’autenticació preferent als exemples de la nostra documentació és el basic-auth. Hi ha més informació sobre l’apiAuth aquí.

Provar la connexió

Les ordres que s’indiquen a continuació permeten comprovar la validesa de la credencial utilitzada i fan una prova de comunicació amb la vostra API de Cyberwatch. Si la prova té èxit, l’API retorna un identificador d’usuari.

Aquesta consulta només requereix una credencial d’API amb drets de només lectura. Per tant, després pot caldre verificar el nivell d’accés de què disposa la credencial utilitzada en funció de les sol·licituds que es facin.

A continuació trobareu exemples detallats de l’execució d’aquesta prova de connexió amb curl, la cmdlet de PowerShell Invoke-WebRequest o el nostre client d’API Python.

Diagnosticar els problemes de connexió

Obteniu un error 401 Un error 401 significa que l'autenticació ha fallat. Per solucionar-ho, primer cal verificar que les claus indicades són correctes. Després, també hauríeu de verificar que l'URL correspon a la de la instància de Cyberwatch desitjada.
Obteniu un error 403 Quan es produeix aquest error, la causa és un problema de privilegis. És possible que les claus d'API s'hagin generat amb un compte que no té drets d'administrador. Un altre cas possible és l'ús de claus que no tenen accés a l'API, per exemple les que serveixen per instal·lar agents. Per verificar aquests elements, cal anar a la interfície web de l'aplicació Cyberwatch. Un cop hàgiu iniciat la sessió, aneu a la pàgina «El meu perfil». El camp «Rol» correspon al nivell de privilegi del vostre compte. Per utilitzar l'API, ha de ser «Administrador». Aneu després a la part inferior de la pàgina i feu clic a «Visualitza les meves claus d'API». Veureu el detall de les claus d'API associades al vostre compte, així com el seu nivell de drets. Si només voleu obtenir dades de l'API, n'hi ha prou amb el mode «Només lectura». Altrament, cal que la clau tingui el nivell d'accés «Complet».

Estructura de les rutes i de les respostes de l’API

Els diferents punts d’accés de l’API es poden consultar en una documentació Swagger accessible des de la vostra aplicació amb el botó </> situat a la part superior dreta de la pàgina.

A Swagger, cada secció descriu la ruta utilitzada, la llista dels paràmetres disponibles i un exemple de l’estructura de les dades que retorna la sol·licitud. A més, es pot generar aquesta llista en format OpenAPI des d’aquí, per importar-la a altres eines com Postman. Swagger també permet generar directament sol·licituds curl autenticades i executar-les sobre la marxa, per provar les respostes de l’API de la vostra instància.

Com qualsevol sol·licitud feta a l’API, Swagger requereix l’autenticació amb una credencial d’API, tal com s’ha indicat anteriorment.

Us recomanem que les configureu directament amb el formulari Authentication de Swagger. Quan les credencials es proporcionen d’aquesta manera, Swagger genera directament la capçalera d’autenticació de curl, cosa que fa que l’ordre sigui fàcil de reutilitzar.

Clients d’API obsolets

Des de la versió 13.0 de Cyberwatch, els nostres antics clients d’API PowerShell i Python són obsolets.

Per a qualsevol pregunta sobre aquest tema, o si necessiteu ajuda per migrar un script d’API d’una versió antiga a la nova, podeu contactar amb nosaltres per correu electrònic a support@cyberwatch.com o per telèfon al +33 1 84 80 88 84.