Wie man Abfrageparameter festlegt

Lernen Sie die Grundlagen der Arbeit mit Abfrageparametern in Ihren HTTP-Connector-Funktionen in Übereinstimmung mit der API-Dokumentation.

Abfrageparameter ermöglichen es Ihnen, die Ergebnisse einer Connector-Funktion zu verfeinern und anzupassen. Verwenden Sie Parameter, um zu sortieren, zu filtern, Grenzen zu setzen, einen Index zu verschieben und vieles mehr. In diesem Artikel werden die Parameter der Tulip Table API verwendet, aber andere APIs können andere Parameteranforderungen haben. Überprüfen Sie die Dokumentation, um sicherzustellen, dass Sie die korrekte Syntax und Spezifikationen verwenden.

Abfragen mit Filtern

Filter können sehr nützlich sein, um nur die Daten zu extrahieren, an denen Sie interessiert sind. Die Syntax dieser Filter kann manchmal ein wenig kompliziert sein. Im Folgenden wird erläutert, wie jeder Filter im Beispiel einer GET-Abfrage für Datensätze gebildet wird, gefolgt von einem vollständigen Beispiel.

DenFeldnamen für benutzerdefinierte Felder wird immer eine fünfstellige Kennung vorangestellt. Diese können am einfachsten nach einer GET-All-Anfrage gefunden werden, um den wahren Namen des Feldes zu überprüfen.

• Beispiel. "Feld"="maytq_scrap_count"

Argumentwerte sind oft einfach zu verstehen. Wenn es sich um einen Textwert handelt, müssen Sie ihn in Anführungszeichen setzen.

• Beispiel. "arg":15

Passen Sie den Funktionstyp an, den Sie verwenden möchten.

• Bsp. "functionType": "greaterThan"

Eine vollständige Anfrage hierfür könnte etwa so aussehen:

https://brian.tulip.co/api/v3/tables/W2HPvyCZrjMMHTiip/records?limit=100&sortBy=\_sequenceNumber&sortDir=asc&filters=[{"field": "maytq\_scrap\_count", "arg":15, "functionType": "greaterThan"}]&filterAggregator=any

So finden Sie Abfrageparameter in der Dokumentation

Um die verfügbaren Abfrageparameter für Ihre Anfrage zu finden, navigieren Sie zur API-Dokumentation. Wenn Sie die Tulip Table API verwenden, finden Sie die Dokumentation unter: your-instance.tulip.co/apiDocs. Wählen Sie die Abfrage, die Sie verwenden möchten und scrollen Sie dann nach unten zur Registerkarte Parameter.

Jede einzelne Methode hat ihren eigenen Parametersatz, aber nicht jede Anfrage hat zugehörige Parameter. Informieren Sie sich daher vorher in der Dokumentation über die verfügbaren Parameter.

Syntax der Abfrageparameter

Die Abfrage der Parametersyntax basiert auf einem Abfrage-String-Format. Dieses Format weist den angegebenen Parametern Werte zu, wobei der Abfrage-String selbst Teil der URL ist.

Klicken Sie im Editor für Verbindungsfunktionen auf Parameter hinzufügen, um einen neuen Abfrageparameter zu erstellen.

Ein Abfrageparameter besteht aus zwei Teilen: einem Schlüssel und einem Wert. Der Schlüssel ist der Name des Parameters und der Wert ist die Information, die den Parameter für die Ergebnisse festlegt.

Die Syntax der Abfrageparameter verwendet die Dot Notation, die den genauen Typ des Parameters angibt. Achten Sie darauf, dass die Schreibweise mit dem API-Standard des anderen Systems übereinstimmt.

Gemeinsame Parameter auf Verbindungsfunktionen anwenden

Um Ihrer Konnektor-Funktion einen Parameter zuzuweisen, müssen Sie zunächst in der API-Dokumentation den Parameter identifizieren, den Sie verwenden möchten. Für jeden Parameter gibt es unterschiedliche Anforderungen, daher gehen wir kurz darauf ein, wie sie aussehen.

:::(Info) (HINWEIS) Aus Gründen der Kontinuität verwenden wir in allen folgenden Beispielen dieselbe Anfrage API Call. Dies ist die GET-Anfrage, die eine Liste von Datensätzen in einer Tulip-Tabelle über die Tulip Table API abruft. Andere APIs, die Sie verwenden, werden andere Spezifikationen für Parameter haben, sehen Sie sich die Anforderungen der API-Dokumentation an:

Begrenzungen

Limits legen eine bestimmte Obergrenze für die zurückgegebenen Ergebnisse fest. Beachten Sie, dass einige Grenzwerte Standardeinstellungen haben. Schauen Sie also unbedingt in der API-Dokumentation nach, um den Anfangswert zu verstehen.

BeispielWir möchten nicht mehr als 70 Datensätze erhalten, wenn die Konnektorfunktion ausgeführt wird. Glücklicherweise ist der Standardwert für das Limit in dieser Abfrage 10 und der höchste Wert 100. Die Syntax für den Abfrageparameter sollte wie folgt aussehen:

Filter

Filter trennen und verfeinern die Ergebnisse auf der Grundlage der im Parameter angegebenen Informationen.

Filter bestehen aus drei Teilen, die Sie in einzelne Parameter schreiben müssen:

• Feld - der Name der Spalte in der Tabelle
• Funktionstyp - der Typ der Vergleichsfunktion
• Argument - der Wert, mit dem die Ergebnisse verglichen werden sollen

Jeder Filter besteht aus 3 Teilen und jeder vollständige Filter ist ein Objekt. Verwenden Sie die Punktnotation, um jeden Schlüssel zu schreiben, und geben Sie die Art des Parameters ("filter"), die Filternummer (0 bis n) und den Teil des Filters ("field", "functionType" oder "arg") an. Für alle drei Teile des Filters muss es einen Parameter geben.

BeispielWir wollen sicherstellen, dass die Ergebnisse der Konnektor-Funktion nur Werte eines bestimmten Feldes (eubmc_value) anzeigen, die dem angegebenen Eingabewert (consumable) der Funktion entsprechen. Da dies unser erster Filter in den Parametern der Funktion ist, ist die Filternummer 0. Das bedeutet, dass jeder Schlüssel für diesen Filter mit "filter.0" beginnt. Die Syntax für diesen Filter sollte wie folgt aussehen:

Sortieren

Die Sortierung der Ergebnisse priorisiert die Ansicht auf der Grundlage der Informationen des Parameters. Die sortierten Ergebnisse bestimmen, welche in Aggregationen einbezogen werden. Sie können mehrere Sortierfunktionen verwenden, wobei die Reihenfolge der Optionen die Priorität der Sortierung bestimmt.

Sortierfunktionen bestehen aus zwei Teilen:

• sortBy - das Feld, nach dem Sie die Ergebnisse sortieren möchten
• sortDir - die Richtung der Sortierung, entweder aufsteigend (asc) oder absteigend (desc)

Jede Sortierfunktion besteht aus 3 Teilen. Verwenden Sie die Punktnotation, um jeden Schlüssel zu schreiben, und geben Sie die Art des Parameters ('sortOptions'), die Sortiernummer (0 bis n) und das Sortierargument ('sortBy' oder 'sortDir') an. Es muss ein Parameter für alle drei Teile der Sortierfunktion vorhanden sein, damit sie funktioniert.

BeispielWir möchten, dass die Ergebnisse der Verbindungsfunktion nach dem zuletzt aktualisierten Feld in aufsteigender Reihenfolge sortiert werden. Da dies unsere erste Sortierfunktion ist, ist die Sortiernummer 0. Das bedeutet, dass beide Schlüssel für diese Sortierung mit "sortOptions.0" beginnen. Für den sortBy-Schlüssel ist der Wert ein spezieller Wert ("_updatedAt"), der aus der API-Dokumentation abgeleitet wurde, um durch aktualisierte Felder zu sortieren. Die Syntax für diese Parameter sollte wie folgt aussehen:

Offsets

Offsets bestimmen den Index, bei dem das zurückgegebene Ergebnis beginnen soll. Dieser Parameter wird für die Paginierung verwendet, nicht für die Reihenfolge der Datensätze, die durch Sortierparameter bestimmt wird. Der Wert des Parameters muss eine ganze Zahl sein, die größer oder gleich 0 ist.

BeispielWir möchten nur die Datensätze ab der 5. Position anzeigen, so dass wir nicht die ersten 5 Ergebnisse sehen. Die Syntax für den Abfrageparameter sollte wie folgt aussehen:

Filter-Aggregatoren

Filteraggregatoren bestimmen, wie die Filter in den Parametern kombiniert werden. Die beiden zur Auswahl stehenden Werte sind "any" und "all". Der Wert "all" bedeutet, dass alle Filter einen Datensatz enthalten müssen, damit der Datensatz in die Ergebnisse aufgenommen werden kann. Der Wert "any" bedeutet, dass mindestens einer der Filter einen Datensatz enthalten muss, damit er in die Ergebnisse aufgenommen wird. Der Standardwert ist "alle", unabhängig davon, ob Sie den Parameter setzen oder nicht.

BeispielWir haben eine Reihe von Filtern in den Abfrageparametern, aber nur einer dieser Filter muss wahr sein, damit die Datensätze mit unserer Anfrage übereinstimmen. Die Syntax für den Abfrageparameter sollte wie folgt aussehen:

Mehrere Filter

In manchen Fällen müssen Sie vielleicht mehrere Filter in der Tabelle überprüfen. In diesem Fall können Sie mehrere zum Filterobjekt hinzufügen. Dies könnte etwa so aussehen:

filters=[{"field": "maytq\_scrap\_count", "arg":15, "functionType": "greaterThan"},{"field": "maytq\_scrap\_reason", "arg": "scratch", "functionType": "equal"}]

Weitere Lektüre

• Ein Überblick über HTTP-Konnektoren
• Erstellen und Konfigurieren einer HTTP-Konnektorfunktion
• Wie man die Tabellen-API verwendet