Introduzione all’utilizzo dell’API Cyberwatch

Gli utenti di Cyberwatch hanno accesso a un’API che consente di interagire con la maggior parte delle risorse visibili nell’applicazione. Questo accesso può consentire, ad esempio, l’automazione di alcune attività o l’ottenimento di risultati personalizzati…

Questa pagina costituisce un’introduzione al funzionamento e all’utilizzo di questa API.

Interagire con l’API Cyberwatch

Poiché l’API Cyberwatch restituisce risposte in formato JSON, è possibile utilizzare nativamente un client curl, la cmdlet PowerShell Invoke-WebRequest, oppure il client Python di Cyberwatch per interrogarla.

Autenticarsi presso l’API e testare la connessione

L’utilizzo dell’API, indipendentemente dalla route interrogata, richiede l’autenticazione tramite le chiavi API di un utente Cyberwatch con ruolo Amministratore.

Queste chiavi API possono essere generate dalla GUI Cyberwatch, nella scheda Il mio profilo > Chiavi API, di ciascun Amministratore Cyberwatch.

Queste credenziali possono essere utilizzate tramite le due modalità di autenticazione proposte: basic-auth e apiAuth. La documentazione descrive l’utilizzo di curl, della cmdlet PowerShell Invoke-WebRequest e del client API Python di Cyberwatch. La modalità di autenticazione privilegiata negli esempi della documentazione è basic-auth. Ulteriori informazioni su apiAuth sono disponibili qui.

Testare la connessione

I comandi riportati di seguito consentono di testare la validità della credenziale utilizzata ed eseguono un test di comunicazione con l’API Cyberwatch. In caso di successo, viene restituito un ID utente.

Questa interrogazione richiede soltanto una credenziale API con diritti di sola lettura. Può quindi essere necessario verificare in seguito il livello di accesso di cui dispone la credenziale utilizzata, in funzione delle richieste che verranno eseguite.

Di seguito sono riportati esempi dettagliati dell’esecuzione di questo test di connessione tramite curl, la cmdlet PowerShell Invoke-WebRequest, oppure il client API Python di Cyberwatch.

Diagnosticare i problemi di connessione

Si verifica un errore 401

Un errore 401 indica che l'autenticazione non è riuscita. Per risolvere il problema, è necessario innanzitutto verificare che le chiavi inserite siano corrette. In secondo luogo, è opportuno verificare anche che l'URL corrisponda a quello dell'istanza Cyberwatch desiderata.

Si verifica un errore 403

Quando si verifica questo errore, la causa è un problema di privilegi. È possibile che le chiavi API siano state generate con un account privo dei diritti di amministratore. Un altro caso possibile è l'utilizzo di chiavi che non dispongono dell'accesso all'API, ad esempio quelle per l'installazione degli agent. Per verificare questi elementi, è necessario accedere all'interfaccia web dell'applicazione Cyberwatch. Una volta effettuato l'accesso, aprire la pagina «Il mio profilo». Il campo «Ruolo» corrisponde al livello di privilegio dell'account. Per utilizzare l'API, quest'ultimo deve essere «Amministratore». Scorrere quindi fino in fondo alla pagina e cliccare su «Visualizza le mie chiavi API». Viene visualizzato il dettaglio delle chiavi API associate all'account, con il relativo livello di diritti. Per il solo recupero di dati dall'API, è sufficiente la modalità «Sola lettura». In caso contrario, la chiave deve disporre del livello di accesso «Completo».

Struttura delle route e delle risposte dell’API

I diversi endpoint dell’API sono consultabili da una documentazione Swagger accessibile dall’applicazione tramite il pulsante </> situato in alto a destra della pagina.

In Swagger, ogni sezione descrive la route utilizzata, l’elenco dei parametri disponibili e un esempio della struttura dei dati restituiti dalla richiesta. È inoltre possibile generare tale elenco in formato OpenAPI da qui, per importarlo in altri strumenti come Postman. Swagger consente anche di generare direttamente richieste curl autenticate e di eseguirle al volo, per testare le risposte API dell’istanza.

Come per qualsiasi richiesta effettuata all’API, Swagger richiede l’autenticazione tramite una credenziale API, come indicato in precedenza.

Si consiglia di configurarle direttamente tramite il modulo Authentication di Swagger. Quando le credenziali vengono fornite in questo modo, Swagger genera direttamente l’header di autenticazione curl, il che rende il comando facilmente riutilizzabile.

Client API deprecati

A partire dalla versione 13.0 di Cyberwatch, i precedenti client API PowerShell e Python sono deprecati.

Per qualsiasi domanda sull’argomento, o per un supporto nella migrazione di uno script API da una versione precedente a quella nuova, è possibile contattare Cyberwatch via e-mail all’indirizzo support@cyberwatch.com, o telefonicamente al numero +33 1 84 80 88 84.