Datenbanken-Abfrageergebnisse mithilfe von API-Request-Parametern in Jitterbit Studio filtern

Einführung

Wenn eine Operation als benutzerdefinierte API veröffentlicht wird, können Aufrufer Werte als Abfrageparameter über die URL übergeben. Diese Anleitung zeigt, wie diese Werte mithilfe von API-Jitterbit-Variablen gelesen werden und wie man sie zum Filtern von Ergebnissen in einer Datenbank-Abfrage-Aktivität WHERE-Klausel nutzt, um anschließend die übereinstimmenden Datensätze als API-Antwort zurückzugeben.

Dieses Muster ist nützlich zum Erstellen von Datenabfrage-Endpunkten, bei denen der Aufrufer steuert, welche Datensätze zurückgegeben werden: beispielsweise ein GET-Endpunkt, der einen Kunden nach ID sucht, Bestellungen für einen bestimmten Datumsbereich abruft oder Produkte nach Kategorie filtert.

Diese Anleitung setzt Folgendes voraus:

• Eine Datenbankverbindung ist konfiguriert und im Projekt zugänglich.
• Die Operation wird als benutzerdefinierte API mit dem Antworttyp Variable veröffentlicht. Informationen zu Einrichtungsschritten finden Sie unter Expose a Studio operation as a REST API (Studio-Operation als REST-API bereitstellen).

Design-Muster

Teil 1: Ein Parametervalidierungsskript hinzufügen

URL-Parameter, die an die API gesendet werden, sind als Jitterbit-Variablen im Format $jitterbit.api.request.parameters.<name> verfügbar, wobei <name> dem Parameterschlüssel in der URL entspricht. Wenn ein Aufrufer beispielsweise GET /customers?CustomerID=123 sendet, enthält $jitterbit.api.request.parameters.CustomerID den Wert 123.

Fügen Sie eine Script-Komponente als ersten Schritt der Operation hinzu. Dieses Skript liest den Parameterwert, speichert ihn in einer kürzeren globalen Variablen zur Verwendung in der Abfrage und gibt einen 400-Fehler zurück, wenn der Parameter fehlt oder leer ist:

<trans>
$customer_id = $jitterbit.api.request.parameters.CustomerID;

If(IsNull($customer_id) || Length($customer_id) == 0,
  $err = Dict();
  $err["error"] = "Missing required parameter: CustomerID";
  $jitterbit.api.response = JSONStringify($err);
  $jitterbit.api.response.status_code = 400;
  RaiseError("Missing required parameter");
);
</trans>

IsNull und Length schützen gemeinsam vor fehlenden und leeren Werten. RaiseError stoppt die Ausführung sofort und löst die konfigurierte Fehleraktion der Operation aus.

Ersetzen Sie CustomerID durch den Namen des URL-Parameters, wie in der Dokumentation für Ihre API angegeben. Parameternamen unterscheiden zwischen Groß- und Kleinschreibung.

Teil 2: Datenbank-Abfrage-Aktivität konfigurieren

Fügen Sie nach dem Validierungsskript eine Datenbank-Abfrage-Aktivität hinzu und konfigurieren Sie sie, um Datensätze mithilfe des erfassten Parameterwerts zu filtern. Die durch das Validierungsskript gesetzte Variable customer_id ist der Aktivität zur Laufzeit verfügbar.

Mit dem Assistenten

In Schritt 2: Bedingungen hinzufügen der Aktivitätskonfiguration:

1. Wählen Sie unter Felder auswählen die zurückzugebenden Felder aus (beispielsweise CustomerID, Name und Email).

2. Verwenden Sie unter WHERE-Klausel die Dropdowns, um das Feld und den Operator für die Filterbedingung auszuwählen.

3. Geben Sie im Feld Wert die Variable mit Klammersyntax ein:

   [customer_id]
   

   Das Variablensymbol im Feld weist darauf hin, dass globale Variablen, Projektvariablen und Jitterbit-Variablen alle hier akzeptiert werden. Beginnen Sie mit der Eingabe einer öffnenden Klammer ([) oder klicken Sie auf das Symbol, um verfügbare Variablen anzuzeigen.

4. Klicken Sie auf Hinzufügen, um die Bedingung an die WHERE-Klausel anzuhängen.

5. Klicken Sie auf Query testen, um die Abfrage für die Datenbank zu validieren.

   Tipp

   Da customer_id eine global Variable ist, die nur zur Laufzeit gesetzt wird, schlägt Query testen fehl, wenn kein Wert vorhanden ist. Legen Sie einen Standardwert für customer_id in diesem Feld fest (siehe Define a default value (Standardwert definieren)), damit Query testen einen Wert zum Ersetzen hat, ohne dass ein Beispielwert im Validierungsskript hartcodiert und entfernt werden muss.

6. Klicken Sie auf Weiter, überprüfen Sie das Datenschema und klicken Sie auf Fertig.

Manuelle SQL verwenden

Für JDBC-Verbindungen klicken Sie im ersten Schritt auf Assistent überspringen / SQL-Anweisung schreiben und geben Sie die Abfrage direkt ein. Variablen in eckigen Klammern werden durch ihre Laufzeitwerte ersetzt, bevor die Abfrage ausgeführt wird:

SELECT CustomerID, Name, Email
FROM Customers
WHERE CustomerID = '[customer_id]'

Für numerische Spalten lassen Sie die umschließenden Anführungszeichen weg:

SELECT OrderID, Total, Status
FROM Orders
WHERE CustomerID = [customer_id]

Teil 3: Die Ergebnisse als API-Antwort zurückgeben

Fügen Sie nach der Database-Aktivität Abfrage eine Transformation hinzu, um die Ergebnisfelder den Ausgabevariablen zuzuordnen. Nach der Transformation fügen Sie eine nachfolgende Script-Komponente hinzu, um die Ergebnisse zu serialisieren und $jitterbit.api.response festzulegen:

<trans>
$result = Dict();
$result["CustomerID"] = $out_CustomerID;
$result["Name"] = $out_Name;
$result["Email"] = $out_Email;
$jitterbit.api.response = JSONStringify($result);
$jitterbit.api.response.status_code = 200;
</trans>

Ersetzen Sie $out_CustomerID, $out_Name und $out_Email durch die globalen Variablen, auf die die Transformation die Abfrageergebnisfelder abbildet. Für Abfragen, die mehrere Datensätze zurückgeben können, erfassen Sie diese in einem Array in der Transformation und serialisieren Sie das Array.

Falls $jitterbit.api.response vor Abschluss des Vorgangs nicht festgelegt wird, gibt API Manager eine leere 200 OK-Antwort zurück. Die vollständige Liste der verfügbaren Variablen zur Steuerung der API-Antwort finden Sie unter API Jitterbit-Variablen.

Die Integration überprüfen

1. Stellen Sie das Projekt bereit.

2. Senden Sie eine Testanfrage an den veröffentlichten Endpunkt mit einem gültigen Parameterwert:

   GET https://<host>/<service-root>/<version>/<path>?CustomerID=123
   

   Bestätigen Sie, dass der Antwortteil den erwarteten Datensatz enthält.

3. Senden Sie eine Anfrage ohne den Parameter:

   GET https://<host>/<service-root>/<version>/<path>
   

   Bestätigen Sie, dass der Endpunkt eine 400-Antwort mit der Fehlermeldung aus dem Validierungsskript zurückgibt.

4. Senden Sie eine Anfrage mit einem Parameterwert, der keinen Datensätzen entspricht. Bestätigen Sie, dass die Antwort ein leeres Ergebnis oder einen entsprechenden Fehler widerspiegelt, je nachdem, wie die Transformation eine Abfrage mit null Zeilen verarbeitet.

5. Falls ein Schritt ein unerwartetes Ergebnis zurückgibt, öffnen Sie die Vorgangsprotokolle in Studio und die API-Protokolle in API Manager, um das Problem zu diagnostizieren.