Zum Inhalt springen

Geschäftsobjekte als API-Endpunkte in Jitterbit App Builder konfigurieren und validieren

Übersicht

Diese Seite führt durch einen kompletten Workflow zum Bereitstellen von App Builder-Daten als REST-API und zur Kontrolle, was darin gespeichert wird: Konfigurieren eines Geschäftsobjekts als Endpunkt, den externe Systeme aufrufen können, Hinzufügen einer Validierungsregel, die fehlerhafte Daten vor der Persistierung ablehnt, und Testen des Ganzen mit einem API-Client eines Drittanbieters. Das Beispiel stellt ein Order-Geschäftsobjekt bereit und fügt eine Regel hinzu, die alle Bestellungen ablehnt, deren Required Date bereits in der Vergangenheit liegt.

Die Schritte sind:

  • API-Endpunkt konfigurieren
    Erstelle den Security Provider, den Anwendungsendpunkt und den Geschäftsobjekt-Endpunkt, die zum Bereitstellen von Daten als REST-API erforderlich sind, und generiere einen Schlüssel, damit sich ein bestimmter Benutzer dagegen authentifizieren kann.

  • Benutzerdefinierte Validierungsregel erstellen
    Füge eine Geschäftsregel hinzu, die eingehende Daten validiert, bevor sie gespeichert werden, und ordne sie dem Save-Event des Endpunkts zu.

  • API-Endpunkt testen
    Verwende Postman, um zu bestätigen, dass die Validierungsregel ungültige Daten ablehnt und der Endpunkt gültige Daten akzeptiert.

API-Endpunkt konfigurieren

Bevor externe Systeme Daten über die REST-API von App Builder lesen oder schreiben können, muss ein spezifisches Geschäftsobjekt als Endpunkt bereitgestellt werden, und es muss eine Möglichkeit für Aufrufer eingerichtet werden, sich dagegen zu authentifizieren. Dieser Abschnitt behandelt die erforderlichen Schritte für beides:

Schritt 1: API-Key-Security-Provider erstellen

Um Anfragen an den neuen Endpunkt zu authentifizieren, wird zunächst ein API-Key-Security-Provider benötigt, den App Builder zur Validierung des Schlüssels verwendet, den jeder Aufrufer präsentiert. Führe folgende Schritte aus:

  1. Wähle IDE > Security Providers.

  2. Klicke auf + Security Provider. Die Seite Provider wird geöffnet:

    Provider-Seite

  3. Konfiguriere den Provider mit diesen Einstellungen:

    • Name: Gib einen aussagekräftigen Namen ein, wie zum Beispiel API Key.

    • Type: Wähle API Key.

    • Enabled: Aktiviere, um den Provider zu aktivieren.

  4. Klicke auf Save.

  5. (Optional) Klicke unter Properties auf + Property, um optionale Parameter für den API-Schlüssel hinzuzufügen und zu konfigurieren.

Schritt 2: Anwendungsendpunkt definieren

Auf die REST-API jeder Anwendung wird über ein Pfadsegment zugegriffen, den Anwendungsendpunkt. Definiere einen jetzt, falls die Anwendung noch nicht über einen verfügt:

  1. Wähle IDE > REST APIs.

  2. Klicke auf Manage Endpoints. Das Dialogfeld Application Endpoints wird geöffnet und zeigt verfügbare Anwendungen und deren Endpunkte:

    Dialogfeld „Application Endpoints"

  3. Lokalisiere die Anwendung, die du bereitstellen möchtest, und klicke auf ihr Symbol Edit.

  4. Gib einen Namen für den Endpunkt ein, wie zum Beispiel endpoint-example.

  5. Klicke auf das Symbol (oder die Schaltfläche Proceed), um den Endpunktnamen zu speichern.

  6. Schließe das Dialogfeld Application Endpoints. Ein neuer Eintrag für den Endpunkt wird unter Services angezeigt.

Schritt 3: Einen Business-Object-Endpunkt veröffentlichen

Mit einem Anwendungsendpunkt können Sie nun ein spezifisches Business Object, wie eine Tabelle, als eine Ressource veröffentlichen, die Aufrufer lesen und beschreiben können:

  1. Klicken Sie im Bereich Services auf das Chevron-Symbol auf der Kachel Ihrer Anwendung. Die REST-API-Seite für diese Anwendung wird geöffnet.

  2. Klicken Sie im Bereich Resources auf + Resource. Das Dialogfeld Resource wird geöffnet:

    Resource-Dialogfeld

  3. Legen Sie die folgenden Werte fest:

    • Table: Öffnen Sie das Menü und wählen Sie die Tabelle aus, die Sie verfügbar machen möchten.

    • Endpoint: Geben Sie einen Namen für den Endpunkt der Tabelle ein.

    Eine vollständige Beschreibung aller Felder finden Sie unter Schritt 3: Eine Ressource veröffentlichen in Eine Jitterbit App Builder-App als REST-API-Endpunkt veröffentlichen.

  4. Klicken Sie auf Save und schließen Sie dann das Dialogfeld Resource.

  5. Um die vollständige URL für Ihren neuen Endpunkt zu ermitteln, kombinieren Sie die REST-API-Basis-URL Ihrer Instanz mit dem Endpunkt Ihrer Anwendung (aus dem vorherigen Schritt) und dem Endpunkt der Ressource (aus diesem Schritt). Weitere Informationen zum genauen URI-Muster finden Sie unter Datenobjekte als Ressourcen.

Schritt 4: Einen benutzerspezifischen API-Schlüssel generieren

Generieren Sie abschließend einen API-Schlüssel, der an einen bestimmten Benutzer gebunden ist, damit die Identität und die Berechtigungen dieses Benutzers für jede mit diesem Schlüssel gestellte Anfrage gelten:

  1. Wählen Sie IDE > User Management aus.

  2. Klicken Sie unter Users auf das Symbol Open record für den Benutzer, dem Sie API-Zugriff gewähren möchten. Das Dialogfeld User wird geöffnet.

  3. Erweitern Sie den Bereich Authentication und bestätigen Sie, dass Login Type auf Interactive gesetzt ist.

  4. Wählen Sie More > Keys aus. Das Dialogfeld Keys wird geöffnet.

  5. Klicken Sie auf Create. Das Dialogfeld Generate Key wird geöffnet:

    Dialogfeld "Generate Key"

  6. Legen Sie Werte für folgende Felder fest:

    • Provider: Wählen Sie den Sicherheitsanbieter aus, den Sie in Schritt 1 erstellt haben (beispielsweise API Key).

    • (Optional) Description: Geben Sie eine Beschreibung für diesen Schlüssel ein.

  7. Klicken Sie auf Save. App Builder generiert automatisch einen Wert für den Schlüssel. Kopieren Sie den generierten Schlüsselwert zum Testen.

    Wichtig

    Stellen Sie sicher, dass Sie den Schlüssel kopiert haben, bevor Sie das Dialogfeld Generate Key schließen, da er nicht erneut angezeigt werden kann.

Eine benutzerdefinierte Validierungsregel erstellen

Eine Validierungsregel ermöglicht es Ihnen, fehlerhafte Daten abzulehnen, bevor sie gespeichert werden, anstatt nachträglich. Dieses Beispiel erstellt eine Regel, die verhindert, dass ein Datensatz gespeichert wird, wenn das Datum „Required Date" in der Vergangenheit liegt, und fügt diese Regel dann zum Save-Ereignis des Endpunkts hinzu, damit sie tatsächlich ausgeführt wird.

Schritt 1: Eine Business Rule für die Validierung erstellen

Business Rules validieren Tabellendaten mithilfe von SQL-ähnlichen Bedingungen über ihre Spalten. Erstellen Sie eine, um die Überprüfung zu definieren, die Ihr Endpunkt anwenden sollte:

  1. Öffnen Sie Ihre App und wählen Sie App Workbench > Rules aus.

  2. Klicken Sie auf By Table und wählen Sie dann die Tabelle aus, die Sie verfügbar machen (beispielsweise Order).

  3. Klicken Sie unter Rules auf + Rule. Der Rule Builder wird geöffnet:

    Rule Builder

  4. Konfigurieren Sie auf der Seite Rule die grundlegenden Eigenschaften der Regel:

    • Name: Geben Sie einen aussagekräftigen Namen ein, beispielsweise Validation: Date Not in Past.

    • Purpose: Wählen Sie Validation aus.

    • Target: Die Tabelle sollte bereits ausgewählt sein (beispielsweise Order).

  5. Klicken Sie auf Create.

  6. Konfigurieren Sie die Logik der Regel:

    • Klicken Sie auf die Registerkarte Columns und fügen Sie die Spalten hinzu, die die Regel benötigt. Fügen Sie für dieses Beispiel Order ID und Required Date hinzu.

  7. Wählen Sie die Registerkarte Where aus, und fügen Sie dann eine Klausel hinzu, um die Fehlerbedingung zu definieren. In diesem Beispiel fügen Sie eine Bedingung hinzu, in der Required Date kleiner als oder gleich Now() ist, um zu prüfen, ob das erforderliche Datum in der Vergangenheit liegt.

  8. (Optional) Klicken Sie auf Validate.

Schritt 2: Die Validierungsregel an ein Ereignis anhängen

Eine Validierungsregel wird nicht von selbst ausgeführt. Sie müssen sie an ein bestimmtes Ereignis anhängen, in diesem Fall Save, damit sie tatsächlich ausgeführt wird, wenn ein Datensatz gespeichert werden soll:

  1. Wählen Sie in App Workbench > Rules mit ausgewähltem By Table die gleiche Tabelle aus (Order in diesem Beispiel).

  2. Klicken Sie auf das Symbol Events für (in diesem Beispiel) Orders (Source). Das Dialogfeld All Events wird geöffnet.

  3. Klicken Sie in der Zeile Save auf Rule Event Detail.

  4. Klicken Sie unter Validations auf Register. Das Dialogfeld Validation wird geöffnet:

    Validation dialog

  5. Wählen Sie im Menü Rule die Validierungsregel aus, die Sie gerade erstellt haben (Validation: Date Not in Past).

  6. Konfigurieren Sie die Validierungsaktion wie folgt:

    • Binding: Wählen Sie Implicit aus.

    • Failure: Wählen Sie Fail on data returned aus.

    • Severity: Wählen Sie Error aus.

    • Message: Geben Sie die Fehlermeldung ein, die angezeigt werden soll, wenn die Validierung fehlschlägt, z. B. The required date cannot be in the past.

  7. Klicken Sie auf Save.

API-Endpunkt testen

Nachdem der Endpunkt veröffentlicht und die Validierungsregel angehängt wurde, bestätigen Sie, dass alles end-to-end funktioniert, indem Sie einen API-Client von Drittanbietern verwenden. Dieser Abschnitt verwendet Postman, aber die gleichen Anfragen funktionieren mit jedem HTTP-Client, der authentifizierte JSON-Anfragen senden kann.

Schritt 1: Den Test-Client konfigurieren

Bevor Sie Anfragen senden, richten Sie Postman mit der Authentifizierung und dem Textformat ein, die Ihr Endpunkt erwartet:

  1. Erstellen Sie in Postman eine neue POST-Anfrage.

  2. Fügen Sie in das URL-Feld die Endpunkt-URL ein, die Sie in Schritt 3 des vorherigen Abschnitts kopiert haben.

  3. Konfigurieren Sie die Autorisierung:

    • Wählen Sie die Registerkarte Authorization aus.

    • Wählen Sie unter Type die Option API Key aus.

    • Geben Sie unter Key X-API-Key ein.

    • Fügen Sie unter Value den Benutzer-API-Schlüssel ein, den Sie in Schritt 4 kopiert haben.

  4. Konfigurieren Sie den Anfragebody:

    • Wählen Sie die Registerkarte Body aus.

    • Wählen Sie das Optionsfeld Raw aus.

    • Wählen Sie in der Formatdropdown-Liste die Option JSON aus.

Schritt 2: Die Validierungsregel testen (Fehlerfall)

Bestätigen Sie zunächst, dass die Validierungsregel ungültige Daten tatsächlich blockiert, indem Sie eine Anfrage senden, die fehlschlagen sollte:

  1. Fügen Sie in den JSON-Body einen Datensatz ein, um den Validierungsfehler auszulösen. Verwenden Sie für dieses Beispiel ein Required Date in der Vergangenheit.

    Example failure record
    {
    "OrderID": 11255,
    "OrderDate": "2014-05-26T00:00:00",
    "RequiredDate": "2014-05-20T00:00:00",
    "ShippedDate": "2014-05-28T00:00:00",
    "ShipCost": 1000.50,
    "ShipName": "Test Site",
    "ShipAddress": "508 Main Street",
    "ShipCity": "Harwich",
    "ShipState": "MA",
    "ShipZip": "02630",
    "ShipCountry": "USA",
    "AddedOn": null,
    "AddedBy": null,
    "EmployeeID": "0f9c520c-1890-11f1-b283-ab1e4a99c4ce",
    "ShipperID": "f4b1df98-188f-11f1-90ba-7a85ad06b57c"
}

  2. Klicken Sie auf Send.

  3. Überprüfen Sie die Antwort. Sie sollten einen Validierungsfehler mit der benutzerdefinierten Meldung sehen, die Sie konfiguriert haben: The required date cannot be in the past. Der Datensatz wird nicht erstellt.

Schritt 3: Den Endpunkt testen (Erfolgsfall)

Bestätigen Sie nun, dass der Endpunkt gültige Daten akzeptiert, sobald die gleiche fehlerhafte Bedingung nicht mehr zutrifft:

  1. Ändern Sie im JSON-Body die Daten so, dass sie gültig sind. Ändern Sie für dieses Beispiel das RequiredDate auf ein Datum in der Zukunft.

    Example success record
    {
    "OrderID": 11255,
    "OrderDate": "2014-05-26T00:00:00",
    "RequiredDate": "2114-05-20T00:00:00",
    "ShippedDate": "2014-05-28T00:00:00",
    "ShipCost": 1000.50,
    "ShipName": "Test Site",
    "ShipAddress": "508 Main Street",
    "ShipCity": "Harwich",
    "ShipState": "MA",
    "ShipZip": "02630",
    "ShipCountry": "USA",
    "AddedOn": null,
    "AddedBy": null,
    "EmployeeID": "0f9c520c-1890-11f1-b283-ab1e4a99c4ce",
    "ShipperID": "f4b1df98-188f-11f1-90ba-7a85ad06b57c"
}

  2. Klicken Sie auf Send.

  3. Überprüfen Sie die Antwort. Sie sollten einen 200 OK-Status sehen, und der Antworttext sollte keinen Validierungsfehler enthalten.

  4. Navigieren Sie zur Bestätigung zur Datentabelle in Ihrer App Builder-Anwendung und überprüfen Sie, ob der neue Datensatz erfolgreich erstellt wurde.