Datenbankabfrageergebnisse mithilfe von API-Anfrageparametern in Jitterbit Studio filtern

Einführung

Wenn ein Vorgang als benutzerdefinierte API veröffentlicht wird, können Aufrufer Werte über die URL als Abfrageparameter übergeben. Diese Anleitung zeigt, wie man diese Werte mithilfe von API-Jitterbit-Variablen liest und sie zum Filtern von Ergebnissen in einer Datenbankabfrage-Aktivität WHERE-Klausel verwendet, um dann 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 über das Projekt zugänglich.
• Der Vorgang wird als benutzerdefinierte API mit dem Antworttyp Variable veröffentlicht. Anweisungen zum Einrichten finden Sie unter Studio-Vorgang als REST-API verfügbar machen.

Entwurfsmuster

Teil 1: Validierungsskript 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 des Vorgangs 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 zusammen vor einem fehlenden und einem leeren Wert. RaiseError stoppt die Ausführung sofort und löst die konfigurierte Fehleraktion des Vorgangs aus.

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

Teil 2: Datenbankabfrage-Aktivität konfigurieren

Fügen Sie eine Datenbankabfrage-Aktivität nach dem Validierungsskript hinzu und konfigurieren Sie sie so, dass Datensätze mithilfe des erfassten Parameterwerts gefiltert werden. Die vom Validierungsskript festgelegte Variable customer_id ist der Aktivität zur Laufzeit verfügbar.

Assistent verwenden

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 zeigt an, dass globale Variablen, Projektvariablen und Jitterbit-Variablen alle 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 anzufügen.

5. Klicken Sie auf Abfrage testen, um die Abfrage gegen die Datenbank zu validieren.

   Tipp

   Da customer_id eine globale Variable ist, die nur zur Laufzeit festgelegt wird, schlägt Abfrage testen fehl, wenn kein Wert vorhanden ist. Legen Sie einen Standardwert für customer_id in diesem Feld fest (siehe Standardwert definieren), damit Abfrage 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

Klicken Sie bei JDBC-Verbindungen 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]'

Lassen Sie bei numerischen Spalten 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 eine Transformation nach der Datenbankaktivität Abfrage hinzu, um die Ergebnisfelder den Ausgabevariablen zuzuordnen. Fügen Sie nach der Transformation 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, denen die Transformation die Abfrageergebnisfelder zuordnet. Erfassen Sie bei Abfragen, die mehrere Datensätze zurückgeben können, diese in einem Array in der Transformation und serialisieren Sie das Array.

Wenn $jitterbit.api.response nicht festgelegt wird, bevor der Vorgang abgeschlossen ist, gibt API Manager eine leere 200 OK-Antwort zurück. Eine vollständige Liste der verfügbaren Variablen zur Steuerung der API-Antwort finden Sie unter API-Jitterbit-Variablen.

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 Antwortkörper 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. Wenn 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.