Aggiunta di ricerche
Le ricerche sono meccanismi di sola lettura che interrogano il servizio per ottenere un elenco di valori che vengono visualizzati sotto forma di un elenco a discesa. Le ricerche possono essere basate su altre informazioni già fornite nel modulo. Tramite le ricerche si elimina la necessità di immettere manualmente o di ricordare i valori associati alle risorse di un account di terze parti quando si configura un'azione o un trigger.
Utilizzare le ricerche in azioni e trigger. Per visualizzare molti elementi, le ricerche utilizzano un meccanismo di paging.
Le ricerche supportano il filtraggio dei dati iniziale. Ad esempio, quando si digita un testo nel campo di ricerca e si fa clic sulla freccia, viene visualizzato un elenco di valori contenenti il testo.
A differenza di altri elementi, le ricerche sono senza versione esternamente. Ogni chiamata di ricerca è una funzione nell'elemento ricerca. Di conseguenza, esiste un elemento ricerca per ogni connettore.
Ad esempio, è presente un'azione di ricerca nella figura che segue. La ricerca recupera l'e-mail dell'utente da Gmail e questi valori vengono visualizzati nell'area ID messaggio come input. Ciò avviene perché lo schema specifica che è possibile utilizzare una ricerca per questo campo.
Per implementare l'azione get-mail-details è necessario l'ID dell'account e-mail. Lo script della ricerca utilizza l'autenticazione dell'account Gmail per cercare tutte le e-mail nell'account in uso. L'elenco viene quindi visualizzato nel modulo dell'azione ed è possibile selezionare l'ID appropriato come ricerca.
Per creare una nuova ricerca, attenersi alla procedura descritta di seguito.
1. Dal prompt dei comandi, eseguire i comandi seguenti:
a. cd <user project root directory>
b. flow add lookup
Il nome della ricerca è il nome del connettore e viene creato nella cartella delle ricerche nella directory del progetto.
Il comando dispone delle opzioni seguenti:
Opzioni | Descrizione | Tipo di dati |
|---|---|---|
--version | Visualizza il numero di versione. | [booleano] |
--help | Visualizza la guida. | [booleano] |
--parentDir, -d | Directory padre del progetto. | [default: "."] |
--logLevel, -1 | Imposta il livello di registrazione. | [default: "info"] |
2. Aggiornare le proprietà nel file index.js.
Un JavaScript di ricerca dovrebbe esportare un singolo oggetto JavaScript. L'oggetto può contenere un numero qualsiasi di metodi. Il file index.js presenta le struttura seguente:
function(input, options, output){
return}
return}
 | Il codice può differire se il servizio esterno utilizza una connessione anziché un elemento OAuth. |
L'oggetto options fornisce una serie di metodi di utilità necessari per l'utilizzo nelle ricerche.
validateDependencies(input.<property name>) - Verifica che l'input contenga la proprietà specificata.
options.getAccessToken(input.auth, function(err, data) { }): Fetch the access token from the server. input.auth contains a UID that is used to fetch the access token. options.getConnection(input.connection, function(err, data){ }) : Fetch the connection corresponding to the UID contained in the connection property.
Per informazioni sull'SDK per le API che è possibile utilizzare nelle ricerche, fare riferimento alla sezione SDK per i connettori di ThingWorx Flow.
Nella tabella seguente viene descritto come sono utilizzati gli argomenti.
Argomento | Utilizzo |
|---|---|
input | Contiene le dipendenze configurate nella ricerca. |
options | Fornisce metodi dell'utilità per recuperare il meccanismo di autenticazione (token di accesso o connessione) e per attivare il supporto per il paging. |
output | Callback che deve essere chiamato per restituire i risultati a ThingWorx Flow. Segue la convenzione di utilizzare un oggetto errore come primo argomento della funzione del nodo. Il risultato deve essere una matrice di oggetti JSON. In genere, sono coppie id-valore. È possibile che vengano aggiunti altri campi se viene aggiunto lo schema dinamico. Per ulteriori informazioni, fare riferimento alla sezione Inserimento dello schema dinamico. Il risultato deve essere passato al callback (funzione output) e deve essere una matrice di oggetti JSON contenente l'ID e il valore. I risultati dovrebbero presentarsi nel formato seguente: { [ {"id":"id1","value":"value1"}, {"id":"id2","value":"value2"}, ], “next_page”: true } |
Per un esempio sull'aggiunta di elementi ricerca, fare riferimento all'Esercitazione B.
Inserimento dello schema dinamico
La presenza di uno schema di input e output fisso per un'azione crea una limitazione durante la creazione di azioni caratterizzate da numerose funzionalità. Lo schema di input e di output per un'azione può essere aggiornato in base alle scelte dell'utente quando si carica una ricerca o quando si seleziona un valore dalla ricerca. Di conseguenza il modulo viene aggiornato in modo da corrispondere allo schema di input aggiornato che mantiene i valori correnti. Inoltre, i campi di output disponibili per la mappatura sull'azione successiva vengono aggiornati in modo da corrispondere allo schema di output aggiornato.
Gli aggiornamenti allo schema di input e di output per un'azione possono essere eseguiti nell'interfaccia di elaborazione dei risultati della ricerca.
È possibile inserire lo schema dinamico durante la restituzione dei risultati della ricerca oppure è possibile aggiungere un'altra funzione alla ricerca tramite l'attributo onSelect (per l'opzione selezionata). Quando lo schema viene inserito in fase di caricamento della ricerca, l'inserimento dello schema dinamico necessita dello schema per tutti i valori della ricerca.
| | L'inserimento multilivello, utilizzando due ricerche consecutive, è possibile per alcuni oggetti. Tramite l'inserimento multilivello è possibile effettuare aggiunte con restrizioni, ma non è possibile rimuovere nulla. |
Lo schema di input visualizzato del modulo viene aggiunto utilizzando gli attributi schema, parent e append nel JSON risultante per la ricerca accanto a id e value. Analogamente, si utilizzano outSchema, outAppend e outParent per aggiungere lo schema di output, che appare come lo schema di output dell'azione quando viene aperta l'azione connessa. In genere, gli attributi append o outAppend e parent o outParent vengono utilizzati insieme, quando lo schema fornito viene aggiunto all'elemento padre indicato per estendere le proprietà. Se l'attributo append non viene utilizzato, lo schema viene sostituito con lo schema appena aggiunto.
L'attributo parent o outParent è l'id dell'elemento schema (deve essere di tipo oggetto) del rispettivo schema. In assenza dell'attributo parent o outParent, il contesto di default per l'aggiornamento è la radice del rispettivo schema. L'aggiornamento dello schema avviene nell'ambito dell'oggetto parent o outParent tramite l'unione o la sostituzione in assenza di append/outAppend delle proprietà specificate nello schema di inserimento con le proprietà esistenti.
È inoltre possibile utilizzare l'attributo userSelected nello schema di output da inserire. Questo attributo viene utilizzato per inserire uno schema di default con valore false e sostituirlo con un sottoinsieme (valore true) quando si selezionano opzioni nel modulo. Se gli attributi userSelected = true vengono rimossi quando un elemento di matrice del modulo viene eliminato, lo schema torna al valore di default.
Ad esempio, per il connettore OData impostare lo schema di inserimento di input e di output come mostrato nella figura seguente:
Lo schema di inserimento di input per OData si presenta nel modo seguente:
"schema": {
"Properties": {
"type": "object",
"title": "Properties",
"properties": {
"AirlineCode": {
"type": "string",
"title": "AirlineCode",
"minLength": 1
},
"Name": {
"type": "string",
"title": "Name",
"minLength": 1
}
}
}
}
"Properties": {
"type": "object",
"title": "Properties",
"properties": {
"AirlineCode": {
"type": "string",
"title": "AirlineCode",
"minLength": 1
},
"Name": {
"type": "string",
"title": "Name",
"minLength": 1
}
}
}
}
Lo schema di inserimento di output per OData si presenta nel modo seguente:
"outSchema": {
"properties": {
"Airlines": {
"type": "array",
"title": "Airlines",
"displayTitle": "Airlines",
"items": {
"type": "object",
"properties": {
"AirlineCode": {
"title": "AirlineCode",
"type": "string",
"userSelected": false
},
"Name": {
"title": "Name",
"type": "string",
"userSelected": false,
"visible": true
}
}
}
}
}
}
"properties": {
"Airlines": {
"type": "array",
"title": "Airlines",
"displayTitle": "Airlines",
"items": {
"type": "object",
"properties": {
"AirlineCode": {
"title": "AirlineCode",
"type": "string",
"userSelected": false
},
"Name": {
"title": "Name",
"type": "string",
"userSelected": false,
"visible": true
}
}
}
}
}
}
Come suggerito nell'esempio precedente, alcuni parametri possono essere fissi nell'interfaccia utente di mappatura nello schema di output ad inserimento dinamico impostando la proprietà seguente: visible = true.
Per internazionalizzare lo schema dinamico di input e di output, fare riferimento alla sezione Supporto di internazionalizzazione per i connettori.
Paging
Le ricerche supportano il paging, ovvero la possibilità di produrre molte pagine di risultati. Ogni chiamata produce una singola pagina di risultati. Nell'interfaccia utente è possibile recuperare la pagina facendo clic su "More results" nell'elenco. Gli oggetti input e options contengono metodi e proprietà per gestire il paging.
• options.getNextPage(boolean) - Utilizzato nel paging per restituire l'URL per il recupero della pagina successiva. Questo URL deve essere impostato sulla proprietà "next_page" dell'oggetto result affinché il paging funzioni correttamente. Se non è necessario che vengano restituite altre pagine, impostare questa proprietà su false.
• options.maxResults - Utilizzato con il paging per ottenere il numero massimo di risultati da restituire in una volta.
• input.page - Numero di pagina corrente.
• input.searchById - Esegue la ricerca in base all'ID.
• input.searchByValue - Esegue la ricerca in base al valore.
La ricerca in base all'ID e al valore è disponibile se il flag ricercabile della ricerca è impostato su true. Per un esempio di ricerca, fare riferimento alle sezioni precedenti. Queste proprietà consentono di restringere la ricerca cercando nel sistema di destinazione gli elementi che corrispondono all'ID o al valore.
| | L'ID e il valore possono fare riferimento a campi diversi nel sistema di destinazione. |