Connettori: leggere le vostre applicazioni
Collegare un'API REST o un database SQL Server in sola lettura, scrivere una query o farla proporre all'IA, testarla e convalidarla prima di usarla.
Un connettore legge una delle vostre applicazioni, in sola lettura: un'API REST (con la sua descrizione OpenAPI, se ne ha una) oppure un database SQL Server. Ogni query la scrivete voi o la propone l'IA. Solo una query testata e poi convalidata può essere usata dall'Assistente IA, da una sonda o da un riquadro.
Prima di cominciare
Le chiamate partono da un agente della vostra rete, oppure dal server FirstSI quando l'API è pubblica su Internet. Attivate il modulo Directory su un agente che raggiunge l'applicazione (Agenti FSI → Configura).
Dichiarare un'API REST
Connettori → Nuovo connettore, tipo REST API:
| Campo | Esempio |
|---|---|
| Indirizzo di base | https://distribuzione.esempio.local/api |
| Descrizione OpenAPI / Swagger (percorso, facoltativo) | /swagger/v1/swagger.json (l'IA la usa per esplorare gli endpoint) |
| Agente di esecuzione | l'agente che si trova nella rete dell'applicazione |
| Autenticazione | Nessuna, Chiave in un'intestazione, Token Bearer, Basic, Chiave nell'URL, Windows integrata, Utente e password → token (OAuth), Token di sessione (GLPI), Identità dell'applicazione (OAuth client_credentials) |
| Segreto | inserito qui e da nessun'altra parte; viene cifrato e non si rivede più |
| Finalità (registro GDPR), Dati interessati | per il vostro registro dei trattamenti |
Se non sapete da dove partire, Aiuto dell'IA per dichiarare l'applicazione accetta una frase di descrizione. L'IA cerca la descrizione OpenAPI, ne deduce l'autenticazione e propone descrizione, finalità, dati interessati e alcune prime query. Non legge alcun dato, e il segreto resta da inserire a voi.
Dichiarare un database SQL Server
| Campo | Esempio |
|---|---|
| Server SQL | SRV-SQL01, SRV-SQL01\ISTANZA oppure SRV-SQL01,1433 |
| Database | Esercizio |
| Autenticazione | Windows (account computer dell'agente) oppure Login SQL dedicato |
| Perimetro leggibile (obbligatorio) | una sola SELECT che riunisce i dati che si ha il diritto di leggere |
L'account deve avere solo la lettura (db_datareader, oppure SELECT sui soli oggetti del perimetro). L'agente rifiuta di leggere con un account che ha diritti di scrittura.
Il connettore non legge mai l'intero database. Le query, l'Assistente IA e la costruzione assistita vedono solo il perimetro, che si interroga con FROM perimetre. Per scrivere il perimetro, Struttura completa del database mostra nomi e tipi di tabelle e colonne, senza alcun dato.
Scrivere una query
Aprite il connettore, poi Scrivi una query. Potete anche partire da Sfoglia le tabelle o Sfoglia gli endpoint in lettura, poi Usa.
Una query ha un Nome tecnico, un'Etichetta e una descrizione di ciò che restituisce. Curate quella descrizione: è ciò che l'Assistente IA legge per scegliere la query giusta.
In SQL è una sola SELECT su perimetre, con parametri @nome. In REST si indicano il metodo, il percorso, i parametri dell'URL ({param}), il percorso dell'elenco nella risposta e i campi da tenere. Quando servono due chiamate in sequenza (trovare una postazione, poi leggerne le connessioni), scegliete Più passi concatenati: un passo esporta un campo, per esempio un identificativo, che il passo successivo usa.
Ogni parametro ha un tipo (testo, intero, numero, data, sì/no, elenco), un valore predefinito, eventualmente un elenco di valori ammessi, e può essere obbligatorio. Si impostano anche le Colonne mascherate (dati personali), il numero di Righe al massimo e il Timeout (s).
Chiederla all'IA
Fate clic su Chiedi all'IA e descrivete l'esigenza in una frase, per esempio «le attività di distribuzione in corso con la postazione e l'ora di inizio». L'IA esplora la struttura, concatena i passi se serve, prova la query se spuntate Mostrare un esempio all'IA (5 righe, colonne sensibili mascherate), poi propone e spiega il risultato. Apri nell'editor la copia perché possiate verificarla.
Testare, convalidare, usare
- Salva e testa con dei valori di prova. Il risultato riporta il numero di righe, la durata e l'esito dei controlli di sola lettura.
- Convalida. Si può convalidare solo una versione testata, e la versione convalidata resta in servizio finché non ne convalidate un'altra.
- Spuntate gli usi:
| Uso | Effetto |
|---|---|
| Assistente IA | L'assistente può chiamarla per i Ruoli autorizzati; Dati sensibili (solo amministratori) la riserva agli amministratori |
| Sonda | Eseguita a intervalli, nei giorni e negli orari scelti; Normale se nessuna riga, almeno una riga, valore sotto la soglia, valore tra a e b; con una gravità |
| Riquadro | Mostrata sotto forma di riquadro |
Se l'applicazione cambia e la query smette di funzionare, passa allo stato Guasta. Disattiva la mette fuori servizio senza eliminarla, e Versioni conserva lo storico.
Ruoli particolari di un connettore
Il campo Ruolo del connettore assegna al connettore una funzione precisa. Gateway WAN serve per le linee telefoniche e i box delle sedi (vedi Gateway WAN). Lo strumento di ticketing invece si sceglie in Prediagnosi dei ticket. Microsoft 365 e Google Workspace hanno un proprio modello: vedi Microsoft 365 e Google Workspace. Per un centralino telefonico 3CX, vedi Centralino telefonico 3CX.
L'Indirizzo pubblico (facoltativo) è quello che i vostri team aprono nel browser (https://supporto.esempio.it). Serve solo a costruire link cliccabili, per esempio verso gli articoli della knowledge base. FirstSI non lo chiama mai.
Fonte: · Docs FirstSI · aggiornato il 10/10/2026