Creazione, implementazione e test dei servizi
I servizi di oggetto sono funzioni eseguibili da un oggetto. I servizi vengono utilizzati internamente nella piattaforma ThingWorx e dai mashup e sono raggiungibili da qualsiasi origine esterna con accesso appropriato. È possibile definire servizi solo nelle entità ThingWorx seguenti:
• Oggetti
• Modelli di oggetto
• Thing shape
• Risorse
• Autenticatori
I servizi vengono implementati tramite JavaScript, SQL o Java.
 |
Java è disponibile solo per le estensioni.
|
Un servizio può essere richiamato tramite un URL, un'applicazione client REST o un altro servizio in ThingWorx.
Creare servizi personalizzati per il modello in ThingWorx per soddisfare i requisiti del progetto.
Best practice per la creazione e l'implementazione di servizi
Per creare e implementare servizi, attenersi alle best practice descritte di seguito.
• Definire le convenzioni sull'attribuzione dei nomi per i servizi. Tenere presenti i punti elencati di seguito.
◦ Assegnare un nome logico significativo e una descrizione al servizio.
◦ Utilizzare una nomenclatura standard per tutti i servizi. Ad esempio anteporre al nome un verbo e una descrizione del servizio. Di seguito sono riportati alcuni esempi di verbi.
|
Verbo
|
Descrizione
|
|---|---|
|
Get
|
Recuperare valori dal database.
|
|
Set
|
Impostare il valore delle voci del database.
|
|
Query
|
Restituire un gruppo di record dal database.
|
|
Aggiungi
|
Aggiungere record al database.
|
|
Aggiorna
|
Aggiornare i record nel database.
|
|
Eliminazione
|
Eliminare record nel database.
|
|
Validate
|
Convalidare i record nel database.
|
|
Purge
|
Eliminare i record nel database.
|
|
Creazione
|
Creare un insieme di record nel database.
|
|
Importazione
|
Importare dati nel database.
|
|
Export
|
Esportare dati dal database.
|
|
Parse
|
Analizzare i dati.
|
Per un servizio che recupera dati cronologici, ad esempio, il nome consigliato è getHistory, anziché History.
◦ Evitare nomi ambigui.
◦ Evitare nomi di servizio lunghi, laddove possibile.
Per ulteriori informazioni, vedere la sezione
Denominazione delle entità.
• Raggruppare servizi e proprietà comuni in un'unica entità, preferibilmente una thing shape.
• Se possibile, implementare i servizi in thing shape.
|
|
È consigliabile utilizzare thing shape per definire le proprietà e i servizi. Se le proprietà e i servizi vengono definiti per un modello di oggetto, diventa difficile passare le definizioni a una Thing shape.
|
• Progettare servizi per livelli diversi, ad esempio interfaccia utente, logica aziendale e recupero dati. I servizi di livelli diversi hanno responsabilità diverse. L'immagine seguente offre un esempio delle responsabilità nei diversi livelli:
• Quando si scrive un servizio, provare a riutilizzare gli snippet disponibili della libreria di snippet di codice ThingWorx. Se non si è certi di come debba essere utilizzato uno degli snippet di codice, testarlo prima di utilizzarlo nel servizio.
• Durante la creazione del servizio con output impostato su JSON, tenere presente quanto riportato di seguito.
◦ Se le proprietà hanno valori come null o undefined, non vengono restituite nel risultato.
Ad esempio:
var test = {
test1: "aaa",
test2: 123,
test3: null,
test4: undefined
};
var result = test;
test1: "aaa",
test2: 123,
test3: null,
test4: undefined
};
var result = test;
Output: {"test1": "aaa", "test2": 123}
◦ Se la proprietà è un oggetto JSON e viene impostata su null, viene restituita nel risultato.
Ad esempio:
var test = {
test1: "aaa",
test2: 123,
test3: null,
test4: undefined,
"line_categories": [ null ]
};
var result = test;
test1: "aaa",
test2: 123,
test3: null,
test4: undefined,
"line_categories": [ null ]
};
var result = test;
Output: {"test1": "aaa", "test2": 123, "line_categories": [ null ]}
• Se si prevede che per completare il servizio sia necessario molto tempo, assicurarsi che l'utente non sia in grado di attivare il servizio più volte contemporaneamente.
• Se il servizio è basato su un trigger di evento in un mashup, utilizzare l'evento ServiceInvokeCompleted per consentire il flusso di dati in un'applicazione.
• Per aggiornare i dati nei mashup, è consigliabile utilizzare un widget Aggiornamento automatico o il servizio GetProperties.
Se un mashup utilizza il servizio GetProperties e il browser supporta i WebSocket, il browser riceve automaticamente i valori delle proprietà aggiornate in tempo reale dal server. In questo caso non è necessario utilizzare il widget Aggiornamento automatico. Questa funzionalità è disponibile solo se si seleziona la casella di controllo Aggiorna automaticamente i valori se ne sono disponibili di nuovi nel pannello delle proprietà del servizio.
Se si utilizza il widget Aggiornamento automatico, PTC consiglia di impostarlo su un minimo di 15 secondi per evitare di sovraccaricare il sistema.
| | Non utilizzare un servizio di ritardo lato server, poiché può determinare il blocco di altri servizi, causando così un arresto anomalo dell'applicazione. |
• Per conversioni semplici in fase di esecuzione è consigliabile utilizzare il widget Espressione, anziché servizi.
Se si visualizza la temperatura in °C e si desidera che l'utente possa visualizzarla in °F, ad esempio, utilizzare il widget Espressione.
• Aggiungere controlli al codice per evitare che all'utente finale possa essere restituito un errore.
Se per eseguire il codice sono necessari alcuni parametri di input, ad esempio, creare controlli per verificare che i parametri di input non siano null quando viene eseguito il servizio.
• Se l'applicazione viene localizzata e gli elementi dell'interfaccia utente contengono testo che viene modificato in modo dinamico in base al risultato dei servizi, assicurarsi di non impostare come hardcoded i valori di testo nei servizi visualizzati nel mashup. Il risultato dei servizi che restituiscono il testo deve infatti essere localizzato. Questo consente anche di gestire e modificare più facilmente il testo dell'interfaccia utente in futuro.
• Durante la creazione di servizi personalizzati, decidere quali utenti o gruppi di utenti devono disporre dei permessi necessari per richiamare il servizio. Per ulteriori informazioni, vedere
Protezione delle applicazioni basate sulla piattaforma ThingWorx tramite visibilità e permessi.
• Un possibile risultato dell'esecuzione dei servizi può essere la creazione di entità fantasma. Le entità fantasma vengono create dinamicamente tramite codice/script, anziché in ThingWorx Composer. La creazione di entità fantasma è da evitare. Per ulteriori informazioni, vedere l'articolo
Detection, Removal and Prevention of Ghost Entities in ThingWorx.
Se vengono create entità fantasma, è possibile eliminarle in uno dei modi descritti di seguito.
◦ Riavviare il server ThingWorx. La memoria di JVM viene così ricaricata dai dati persistenti escludendo le entità fantasma.
◦ Utilizzare l'estensione Ghost Entities Cleaner, scaricabile da
PTC Marketplace.
◦ Utilizzare il meccanismo "try-catch" per eliminare le entità fantasma: Per ulteriori informazioni, vedere
Esempio: creazione ed eliminazione di entità fantasma.
• L'impostazione di timeout dello script di default per la piattaforma ThingWorx è di 30 secondi. Se l'esecuzione di uno script richiede più tempo dell'impostazione di default, viene terminata dalla piattaforma. L'amministratore di ThingWorx può configurare il timeout per gli script nella sezione delle impostazioni di base del file platform-settings.json.
Best practice per il test dei servizi
Per testare i servizi, attenersi alle best practice descritte di seguito.
• Testare il servizio in modo incrementale durante la creazione. Utilizzare i messaggi del logger di script, se appropriato.
| | Qualsiasi servizio con loop infinito può arrestare il server ThingWorx. |
• Mentre si testa un servizio, controllare la presenza di messaggi di errore nei log. Ciò è particolarmente opportuno per i servizi in sottoscrizioni. Si rivelano utili i file di log seguenti:
◦ ErrorLog.log - Fornisce una traccia stack dettagliata degli errori
◦ ScriptErrorLog.log - Fornisce informazioni sul contesto del servizio (numero di riga dell'errore nello stack)
Gli errori vengono registrati nel file solo se si seleziona la casella di controllo Attiva traccia stack script nella scheda Configurazione del sottosistema LoggingSubsystem.
| | I file riportati sopra sono disponibili nella cartella ThingworxStorage/logs. Per leggere questi file, è necessario accedere al server ThingWorx. |
• Se il servizio viene chiamato da un mashup, testarlo in Composer e nel mashup.
• Se per l'esecuzione del servizio sono necessari input dell'utente, è possibile utilizzare il widget Convalida.
• Utilizzare gli strumenti di sviluppo disponibili nei browser per controllare il risultato di un servizio. Ciò è utile quando si desidera eseguire il debug di una sequenza di servizi eseguita in un mashup. Lo strumento visualizza i risultati del servizio nel contesto di tale esecuzione specifica.
Suggerimenti
• Se si desidera cercare servizi, non aprire l'entità nella modalità di modifica. Utilizzare il link Anteprima a sinistra del nome dell'entità per aprirla nella modalità di visualizzazione.
Altre considerazioni
• Protezione
◦ Per una maggiore protezione, utilizzare le sostituzioni dei servizi per negare i permessi per i servizi critici disponibili nella piattaforma.
• Aggiornamenti
◦ Utilizzare procedure di codifica efficienti e non creare servizi monolitici di grandi dimensioni.