Script REST

NOTA BENE

L'argomento seguente potrebbe contenere riferimenti agli aspetti relativi agli script personalizzati della linea di prodotti IndySoft. Alcuni aspetti delle funzionalità descritte potrebbero non essere accessibili ai clienti finali. A titolo informativo, le funzionalità interessate riporteranno la dicitura «script» o «script personalizzato».Per ulteriori informazioni sugli script personalizzati e su come vengono implementati e supportati all'interno del prodotto, consultare l'argomento "Panoramica sugli script personalizzati".

Inoltre, si noti che l'utilizzo degli script REST per l'accesso web al database IndySoft richiede la registrazione del prodotto «IndySoft REST Scripting» nel modulo di registrazione IndySoft. Per ulteriori dettagli, contattare il reparto vendite di IndySoft. Se «IndySoft REST Scripting» è stato registrato come prodotto (tramite l'utilità di registrazione IndySoft), è possibile utilizzare la scheda «REST Scripts» per modificare gli script e configurare il relativo servizio REST di IndySoft. Gli script REST consentono l'accesso web tramite script al database IndySoft. La funzionalità è interamente gestita dagli script creati e aggiornati in questa scheda. REST è semplicemente uno stile architettonico per le richieste e le risposte HTTP. Se il server REST di IndySoft è in esecuzione e sono stati creati uno o più script REST, IndySoft può intercettare specifiche richieste HTTP e rispondere di conseguenza tramite questo servizio.

Ecco un esempio molto semplice. Supponiamo che tu sia il proprietario del dominio myurl.com e che voglia consentire a una specifica richiesta web di restituire la data di scadenza della calibrazione per un determinato bene. (Questo è un esempio molto semplice!). Per prima cosa, dovresti configurare uno script REST che si attivi in base a specifiche richieste HTTP. Questo script leggerebbe i parametri richiesti in ogni richiesta e poi genererebbe una risposta HTTP. Il nome dello script corrisponderebbe alla parte finale dell'URL nella richiesta. A questo punto dovresti installare/eseguire il servizio REST di IndySoft (indicando il tuo dominio myurl.com in esecuzione su una porta specifica, ecc. Lo scripting REST in IndySoft consente di accedere a tutte le proprietà delle richieste HTTP (URL, porta, IP, ecc.), al tipo di richiesta («GET», «POST», «PUT», «DELETE»), a tutte le intestazioni, a tutti i parametri di query e al corpo del messaggio (sia in formato testo che binario). Sono disponibili funzioni di script specifiche per restituire ciascun elemento. Nel nostro esempio, supponiamo che la richiesta web dal lato client sia interamente contenuta nell'URL (in questo esempio non è necessario alcun corpo del messaggio):

http://myurl.com:9001/IndyScripts/ReturnDueDate?Company=ABC+COMPANY&Id=ABC123

Quindi, dall'URL dell'esempio sopra riportato, si evince che il nostro server REST IndySoft funziona su HTTP (non HTTPS), che il dominio su cui è configurato è myurl.com e che l'URI relativo (come configurato durante l'installazione) è «IndyScripts». Il nome dello script che viene richiamato è «ReturnDueDate». Infine, vengono passati due parametri di query: «Company» e «Id». Solo le richieste HTTP inviate a 'http://myurl.com:9001/IndyScripts' raggiungeranno il server REST di IndySoft. Inoltre, solo le richieste seguite (nell'URL) dal nome di uno script daranno mai esecuzione a uno script, come nel caso di 'http://myurl.com:9001/IndyScripts/ReturnDueDate', che esegue lo script 'ReturnDueDate'. Infine, lo script leggerà i parametri della query (insieme ad altri dettagli, se necessario) e fornirà una risposta adeguata. Di seguito è riportato un esempio di script per un server REST:

sCompany = RequestQueryParameter("Company")

sID = RequestQueryParameter("Id")

if tdDoSQLRecords(1, "SELECT SCHED_DUE_DATE FROM SCHEDGI WHERE COMPANY = '" & sCompany & "' AND GAGE_SN = '" & sID & "' AND SCHED_TYPE = 'CALIBRATION'") then

sDueDate = tdFieldbyNameAsString(1, "SCHED_DUE_DATE")

ResponseStatusCode(700)

ResponseBodyAsText(sDueDate)

Else

sDueDate = ""

ResponseStatusCode(800)

ResponseBodyAsText(sDueDate)

End If

Ecco, questo è un esempio molto semplice. Lo script legge i parametri di query dell'URL relativi a «Azienda» e «ID». Si noti che i simboli codificati in percentuale vengono sostituiti automaticamente dalla funzione RequestQueryParameter (ad esempio, «ABC+COMPANY» viene restituito come «ABC COMPANY»). Se viene individuata una data di scadenza della CALIBRAZIONE per questa risorsa, viene restituita la data di scadenza sotto forma di testo, insieme a un codice di risposta HTTP 700. Se non viene trovata alcuna data di scadenza, vengono restituiti un testo vuoto e un codice di risposta HTTP 800. In script più comuni, la risposta testuale sarebbe una pagina HTML completa. In alternativa, la risposta potrebbe includere un file XML nel corpo del messaggio di risposta che fornisce ulteriori dettagli sulla transazione completata. Ma questi sono i fondamenti: inviare una richiesta HTTP a un URL + URI relativo + script + parametri opzionali. Includi in questa richiesta eventuali intestazioni e/o il corpo del messaggio. Lo script del server risponde alle richieste valide, legge i dettagli del messaggio e invia una risposta adeguata. Le risposte HTTP includono un codice di risposta e un corpo del messaggio in formato testuale o binario. Il client HTTP dovrebbe essere in grado di reagire di conseguenza (se la risposta è un file HTML, verrà visualizzata; se nel corpo del messaggio è presente un PDF, verrà visualizzato, ecc.)

Configurazione di IndySoftRESTServer
Il primo passo (dopo aver registrato «IndySoft REST Scripting» nell'utilità di registrazione IndySoft) consiste nel configurare il servizio IndySoft REST sul proprio server web. Questo servizio risponderà a tutte le richieste web relative a questo dominio. Per aprire la schermata di configurazione, premere il pulsante «IndySoftRESTServer Setup» situato sopra la griglia degli script REST:

Configurazione di IndySoftRESTServer

Impostazioni del server REST IndySoft

Questa finestra di dialogo serve per installare o disinstallare il servizio REST di IndySoft, avviare o arrestare il servizio e inserire o salvare tutte le impostazioni correlate. IMPORTANTE: Se questa finestra di dialogo viene utilizzata per installare/disinstallare il servizio o per riservare automaticamente uno spazio dei nomi per l'host/URI, saranno necessari i diritti di amministratore di Windows. Prima di continuare, assicurati di chiudere e riavviare IndySoftSyncOptions.exe selezionando "Esegui come amministratore" in Windows.

·Installa servizio / Disinstalla servizio: il pulsante nella parte superiore della finestra di dialogo può essere utilizzato per installare o disinstallare il servizio, a seconda dei casi. Si noti che per eseguire questa operazione sono necessari i diritti di accesso appropriati in Windows. Una volta installato, vedrai il servizio elencato tra i servizi di Windows con il nome «IndySoft REST Server». Dopo l'installazione o la disinstallazione, la finestra di dialogo si chiuderà. Nota: ti consigliamo di controllare attentamente il pulsante "Impostazioni avanzate" prima di installare il servizio. Una volta installato, il servizio può essere avviato o arrestato tramite i pulsanti situati nella parte inferiore della finestra di dialogo. Ovviamente è possibile avviare o arrestare il servizio direttamente da "Servizi di Windows".

·Porta utilizzata: inserire la porta desiderata per il servizio REST IndySoft. Questa porta può essere specificata nella richiesta HTTP dopo il dominio dell'host, seguita da due punti (vedi esempio nella finestra di dialogo).

·Utilizza HTTPS: seleziona questa casella se preferisci le richieste HTTPS anziché HTTP. Se si utilizza HTTPS, è necessario specificare un certificato. Una volta salvate le impostazioni (premendo OK), IndySoft ti chiederà automaticamente di selezionare un certificato tramite Windows. Questo processo avrà luogo quando IndySoft tenterà di registrare l'host specificato.

·Host: inserisci il nome del dominio host per questo server.Nota: una volta salvate le impostazioni (premendo il pulsante OK), IndySoft tenterà di registrare automaticamente questo spazio dei nomi URL. Il server REST di IndySoft si basa su hHTTPsys in modalità kernel, il che significa che il sistema operativo elabora tutte le richieste HTTP. In questa architettura, il kernel inoltra le richieste HTTP in base all'URL richiesto. Affinché funzioni, dobbiamo prima riservare uno spazio dei nomi URL. La prenotazione dello spazio dei nomi assegna i diritti su una porzione dello spazio dei nomi degli URL HTTP a un determinato gruppo di utenti Windows. Una prenotazione conferisce a tali utenti il diritto di creare servizi che ascoltano su quella porzione dello spazio dei nomi. Supponiamo quindi che, in base alle impostazioni specificate in questa finestra di dialogo, il tuo server sia raggiungibile all'indirizzo 'http://myurl.com:9001/IndyScripts/'. In tal caso, IndySoft tenterà di riservare tale spazio dei nomi per garantire che Windows accetti le richieste HTTP a tali indirizzi anziché rifiutarle. Se è necessario configurare queste regole manualmente, richiedere lo strumento IndyHTTPConfig.exe al supporto tecnico di IndySoft. Si noti che lo stesso strumento IndyHTTPConfig.exe è già incluso nel 3-Tier Application Server (nel caso in cui tale servizio sia installato sullo stesso server).

·URI relativo: inserire il nome dell'URI relativo. Si tratta della parte dello spazio dei nomi che segue l'host; ad esempio, la parte "IndyScripts" dell'URL completo "http://myurl.com:9001/IndyScripts/ScriptNameHere"

·Esempio: questo testo di sola lettura aggiunge le quattro impostazioni sopra indicate nel formato richiesto al momento dell'invio della richiesta client. Si noti che la parte finale dell'URL includerà un riferimento allo script specifico (seguito da eventuali parametri di query opzionali). Il piccolo pulsante a destra di questa casella di modifica aprirà l'URL specificato. Il tuo browser predefinito gestirà la richiesta. Nota: questo link web non è necessariamente completo: poiché in genere sono richiesti parametri di query aggiuntivi o un corpo del messaggio, si tratta solo di un punto di partenza.

·Accesso al server: il server REST di IndySoft esegue gli script utilizzando la connessione client al database. Ciò significa che alcune impostazioni, come quelle relative alla posta elettronica, seguiranno le impostazioni dell'utente o della posizione. Per questo motivo, è importante specificare un nome utente da utilizzare per caricare queste impostazioni all'avvio di IndySoft REST Server. Verrà utilizzata la posizione PREDEFINITA per questo utente.

·Precaricamento degli script: se questa casella è selezionata, all'avvio di IndySoft REST Server tutti gli script verranno precaricati in memoria. Ciò consente un'esecuzione leggermente più rapida di ogni richiesta web. Lo svantaggio è che, se lo script viene modificato (da IndySoft DataSync Utility...REST Scripts), sarà necessario arrestare e riavviare il servizio affinché le modifiche apportate alle funzionalità diventino effettive. Se questa casella non è selezionata, lo script viene caricato dal database ad ogni richiesta.

·Registra tutte le richieste: questa opzione viene solitamente attivata solo durante il debug di un nuovo script. Quando questa opzione è attiva, tutte le richieste vengono registrate nella scheda Cronologia / Stato. Il registro delle richieste conterrà un elenco completo di tutte le proprietà, le intestazioni, i parametri di query e i corpi dei messaggi disponibili come riferimento per gli script. I valori saranno annotati nel log nello stesso formato in cui possono essere richiamati (se lo si desidera) all'interno dello script.

·Impostazioni avanzate: se lo si desidera, è possibile utilizzare questa finestra di dialogo per specificare le dipendenze del servizio e le credenziali. Nota: queste impostazioni saranno applicate al servizio solo al momento dell'installazione

·Avvia/Interrompi servizio: utilizzare i due pulsanti in basso a sinistra nella finestra di dialogo per avviare o interrompere il server REST IndySoft.

Griglia degli script REST
Aggiungi/Modifica/Elimina script REST: utilizza queste opzioni per aggiungere, modificare o eliminare uno script REST. Queste opzioni sono disponibili solo se "IndySoft REST Scripting" è un prodotto registrato. In caso contrario, ti verrà richiesto un codice di risposta che può essere ottenuto esclusivamente tramite l'assistenza IndySoft.

Stampa tabella degli script REST - Utilizza questa opzione per stampare rapidamente l'elenco corrente degli script REST.

Visualizza solo lo script REST - Utilizza questo pulsante per esaminare lo script REST attualmente selezionato senza diritti di modifica. Questa opzione è utile se non disponi dei diritti di modifica ma devi verificare il corretto funzionamento dello script selezionato.

Importa/Esporta script REST - Utilizza queste opzioni per importare uno script REST da un file zip (precedentemente esportato tramite l'opzione di esportazione) o per esportare lo script attualmente selezionato in un file zip.

Configurazione del server REST IndySoft - Utilizza questa opzione per aprire la finestra di dialogo delle impostazioni del server REST.

Script REST: Aggiungi/Modifica
· Nome dello script - Il nome univoco dello script REST. Questo nome apparirà nella cronologia dei log e in tutte le e-mail inviate dallo script o in risposta a errori dello script.

·Attivo - Indica se lo script è stato caricato/eseguito dal servizio REST di IndySoft. Lo script può essere testato dalla schermata IndySoftSyncOptions solo se questa opzione non è selezionata.

·VBScript/Pascal - Ogni script può essere scritto utilizzando la sintassi VBScript o Pascal

·Nome codificato (per URL) - Per richiamare questo script tramite una richiesta HTTP web è necessario utilizzare il nome dello script (indicato a sinistra come «Script Name»). Se il nome dello script contiene caratteri che non possono essere inseriti in un URL, è necessario utilizzare la versione codificata del nome dello script (come mostrato automaticamente qui). Ad esempio, il nome dello script «WEB SCRIPT» verrebbe codificato come «WEB%20SCRIPT» in un URL.

·Descrizione - Una descrizione più dettagliata dello script

·Errori dello script a - Può contenere uno o più indirizzi e-mail. Queste persone riceveranno automaticamente un'e-mail se lo script genera un errore durante l'esecuzione. Si noti che questi errori riguardano la compilazione dello script e non sono necessariamente errori interni allo script che potrebbero essere intercettati in quella fase. Ad esempio, se lo script contiene errori di sintassi, questi indirizzi e-mail riceveranno una notifica (poiché lo script non può essere compilato). Ma se, ad esempio, il tuo script carica un file XML e questo file presenta un formato errato che genera un codice di errore, la logica dello script potrebbe reagire o meno a tale codice di errore: dipende dall'autore dello script. Quindi, se lo script rileva il codice di errore, è possibile richiamare la funzione SendEMail dall'interno dello script per rispondere a tale errore. Se desideri restituire questi indirizzi "Invia errori a" dall'interno dello script, utilizza la funzione SendScriptErrorsTo.

A destra dello script è presente una scheda "Procedure/Funzioni" che ricorda agli utenti le procedure e le funzioni disponibili. Gli utenti possono trascinare queste funzioni/procedure nell'area dello script. La scheda "Registro di debug" registra eventuali errori di sintassi rilevati durante l'esecuzione dello script. Inoltre, il testo del "Registro di debug" può essere popolato con note di debug dall'interno dello script richiamando la funzione DebugLog.

Per assistenza o informazioni sulle procedure e le funzioni di scripting relative a REST disponibili, consultare le sezioni dedicate alle funzioni di scripting REST nella documentazione di aiuto di IndySoft Custom Scripting. |