Lookups hinzufügen
Lookups sind ein schreibgeschützter Mechanismus, der den Dienst abfragt, um eine Liste von Werten abzurufen, die als Dropdown-Liste angezeigt werden. Lookups können auf anderen Elementen oder Informationen basieren, die im Formular bereits bereitgestellt sind. Durch Verwendung von Lookups entfällt die Notwendigkeit, die Ihren Drittanbieter-Kontoressourcen zugeordneten Werte beim Konfigurieren einer Aktion oder eines Triggers manuell einzugeben oder sich diese Werte zu merken.
Verwenden Sie Lookups in Aktionen und Triggern. Um viele Elemente anzuzeigen, verwenden Lookups einen Paging-Mechanismus.
Lookups unterstützt die anfängliche Datenfilterung. Wenn Sie beispielsweise Text in ein Lookup-Feld eingeben und auf den Pfeil klicken, wird eine Liste von Werten angezeigt, die den Text enthalten.
Im Gegensatz zu anderen Artefakten werden Lookups nicht extern versioniert. Jeder Lookup-Aufruf ist eine Funktion im Lookup-Artefakt. Daher gibt es ein Lookup-Artefakt pro Konnektor.
Die folgende Abbildung enthält beispielsweise eine Lookup-Aktion. Das Lookup ruft die E-Mails des Benutzers aus Gmail ab, und diese Werte werden als Eingabe im Feld Nachrichten-ID angezeigt. Das ist möglich, weil das Schema angibt, dass ein Lookup für dieses Feld verwendet werden kann.
Um die Aktion "get-mail-details" zu implementieren, benötigen Sie die ID des E-Mail-Kontos. Das Lookup-Skript verwendet die Authentifizierung Ihres Gmail-Kontos, um nach allen E-Mails in Ihrem Konto zu suchen. Die Liste wird dann im Aktionsformular angezeigt, und Sie können die entsprechende ID als Lookup auswählen.
Gehen Sie wie folgt vor, um ein neues Lookup zu erstellen:
1. Führen Sie in der Eingabeaufforderung die folgenden Befehle aus:
a. cd <user project root directory>
b. flow add lookup
Der Name des Lookups ist der Name des Konnektors und wird im Ordner "Lookups" im Projektverzeichnis erstellt.
Die folgenden Optionen sind für den Befehl verfügbar.
Optionen | Beschreibung | Datentyp |
|---|---|---|
--version | Zeigt die Versionsnummer an. | [Boolean] |
--help | Zeigt die Hilfe an. | [Boolean] |
--parentDir, -d | Das Elternverzeichnis für das Projekt. | [Standardwert: "."] |
--logLevel, -1 | Legt die Protokollebene fest. | [Standardwert: "info"] |
2. Aktualisieren Sie die Eigenschaften in der Datei index.js.
Ein Lookup-JavaScript sollte ein einzelnes JavaScript-Objekt exportieren. Das Objekt kann eine beliebige Anzahl Methoden enthalten. Die Datei Index.js hat die folgende Struktur.
function(input, options, output){
return}
return}
 | Der Code kann anders aussehen, wenn der externe Dienst eine Verbindung anstelle einer OAuth verwendet. |
Das Optionsobjekt bietet eine Reihe von Dienstprogramm-Methoden, die für die Verwendung in Lookups benötigt werden.
validateDependencies(input.<property name>) – Prüfen Sie, dass die Eingabe die angegebene Eigenschaft enthält.
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.
Informationen zu einem SDK für APIs, die in Lookups verwendet werden können, finden Sie im Abschnitt SDK der ThingWorx Flow Konnektoren.
In der folgenden Tabelle wird die Verwendung der Argumente beschrieben.
Argument | Verwendung |
|---|---|
input | Enthält die im Lookup konfigurierten Abhängigkeiten. |
options | Stellt Dienstprogrammmethoden zum Abrufen von Authentifizierungsmethode, Verbindung oder Zugriffstoken und zum Aktivieren der Paging-Unterstützung bereit. |
output | Callback, der aufgerufen werden muss, um Ergebnisse an ThingWorx Flow zurückzugeben. Er befolgt die "Error-first"-Konvention des Knotens. Das Ergebnis muss ein Array von JSON-Objekten sein. In der Regel sind das ID- und Wert-Paare. Zusätzliche Felder können hinzugefügt werden, wenn das dynamische Schema hinzugefügt wird. Weitere Informationen finden Sie im Abschnitt "Injektion eines dynamischen Schemas". Das Ergebnis muss an den Callback (Ausgabefunktion) übergeben werden, und es muss ein Array von JSON-Objekten sein, die die ID und den Wert enthalten. Die Ergebnisse sollten im folgenden Format sein: { [ {"id":"id1","value":"value1"}, {"id":"id2","value":"value2"}, ], “next_page”: true } |
Ein Beispiel zum Hinzufügen von Lookups finden Sie im Tutorial B.
Injektion eines dynamischen Schemas
Wenn ein festes Eingabe- und Ausgabeschema für eine Aktion vorhanden ist, führt dies zu einer Beschränkung beim Erstellen von Aktionen mit vielen Funktionen. Das Eingabe- und Ausgabeschema für eine Aktion kann basierend auf Benutzerauswahlmöglichkeiten beim Laden eines Lookups oder beim Auswählen eines Werts aus dem Lookup aktualisiert werden. In der Folge wird das Formular so aktualisiert, dass es dem aktualisierten Eingabeschema entspricht, wobei die aktuellen Werte beibehalten werden. Darüber hinaus werden die für das Zuordnen in der nächsten Aktion verfügbaren Ausgabefelder so aktualisiert, dass sie dem aktualisierten Ausgabeschema entsprechen.
Aktualisierungen des Eingabe- und Ausgabeschemas für eine Aktion können über die Lookup-Ergebnisverarbeitungsschnittstelle vorgenommen werden.
Sie können das dynamische Schema injizieren, während die Ergebnisse der Lookups zurückgegeben werden, oder Sie können dem Lookup über das Attribut onSelect (für die ausgewählte Option) eine andere Funktion hinzufügen. Wenn das dynamische Schema zum Zeitpunkt des Ladens des Lookups eingefügt wird, ist für das Einfügen des dynamischen Schemas das Schema für alle Lookup-Werte erforderlich.
| | Das Einfügen auf mehreren Ebenen unter Verwendung von zwei aufeinander folgenden Lookups ist für einige Dinge möglich. Beim Einfügen auf mehreren Ebenen kann mit Einschränkungen angehängt, aber nicht entfernt werden. |
Das im Formular angezeigte Eingabeschema wird hinzugefügt, indem die Attribute schema, parent und append im Ergebnis-JSON für das Lookup zusätzlich zu ID und value verwendet werden. Verwenden Sie entsprechend outSchema, outAppend und outParent, um das Ausgabeschema hinzuzufügen, das als Ausgabeschema der Aktion angezeigt wird, wenn die verbundene Aktion geöffnet wird. In der Regel werden append oder outAppend und parent oder outParent zusammen verwendet, wenn das angegebene Schema an das angegebene Elternobjekt angefügt wird, um die Eigenschaften zu erweitern. Wenn append nicht verwendet wird, wird das Schema durch das neu hinzugefügte Schema ersetzt.
Das Attribut parent oder outParent ist die ID des Schemaelements (muss Typ object aufweisen) für das jeweilige Schema. Bei Fehlen des Attributs parent oder outParent ist der Standardkontext für die Aktualisierung der Stamm des jeweiligen Schemas. Die Aktualisierung des Schemas erfolgt innerhalb des Umfangs des parent- oder outParent-Objekts, indem die im Einfügeschema angegebenen Eigenschaften mit den vorhandenen Eigenschaften zusammengeführt oder – bei Fehlen von append/outAppend – ersetzt werden.
Sie können auch das Attribut userSelected für das Ausgabeschema, welches eingefügt wird, verwenden. Es wird verwendet, um ein Standardschema (Wert "false") einzufügen und dieses durch eine Untermenge zu ersetzen (Wert "true"), wenn Sie Optionen im Formular auswählen. Wenn die userSelected = true-Attribute entfernt werden, wenn ein Array-Element des Formulars gelöscht wird, wird das Schema auf den Standardwert zurückgesetzt.
Für den OData-Konnektor müssen Sie beispielsweise das Eingabe- und Ausgabe-Einfügeschema wie in der folgenden Abbildung dargestellt einrichten:
Das Eingabe-Injektionsschema für OData lautet wie folgt:
"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
}
}
}
}
Das Ausgabe-Injektionsschema für OData lautet wie folgt:
"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
}
}
}
}
}
}
Wie im vorstehenden Beispiel vorgeschlagen, können einige Parameter in der Zuordnungs-Benutzeroberfläche im dynamisch injizierten Ausgabeschema durch Festlegen der folgenden Eigenschaft fixiert werden: visible = true.
Hinweise zur Internationalisierung des dynamischen Eingabe- und Ausgabeschemas finden Sie im Abschnitt Internationalisierungsunterstützung für Konnektoren.
Paging
Lookups unterstützen Paging, d.h. die Möglichkeit, mehrere Seiten mit Ergebnissen zu produzieren. Jeder Aufruf produziert eine einzige Seite mit Ergebnissen. In der Benutzeroberfläche kann diese Seite durch Klicken auf "Mehr Ergebnisse" in der Liste aufgerufen werden. Die Eingabe und die Optionsobjekte enthalten Methoden und Eigenschaften, die sich mit Paging befassen.
• options.getNextPage(boolean) – Wird bei der Verwendung von Paging für die Rückgabe der URL verwendet, um die nächste Seite abzurufen. Diese URL muss auf der Eigenschaft "next_page" des Ergebnisobjekts festgelegt werden, damit Paging richtig funktioniert. Legen Sie diese Eigenschaft auf "falsch" fest, wenn keine weiteren Seiten zurückgegeben werden sollen.
• options.maxResults – Wird verwendet, um die maximale Anzahl der zurückgegebenen Ergebnissen bei der Verwendung von Paging anzugeben.
• input.page – Die aktuelle Seitenanzahl
• input.searchById – Suchen nach ID
• input.searchByValue – Suchen nach Wert
Suchen nach ID und Suchen nach Wert sind verfügbar, wenn das Flag für durchsuchbar im Lookup auf "wahr" festgelegt ist. Ein Beispiel für ein Lookup finden Sie in den Abschnitten oben. Diese Eigenschaften helfen dabei, die Suche einzuschränken, indem im Zielsystem nach Elementen gesucht wird, die mit der ID oder dem Wert übereinstimmen.
| | ID und Wert beziehen sich u.U. auf unterschiedliche Felder im Zielsystem. |