Zum Inhalt springen

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

Übersicht

Diese Seite führt Sie durch einen vollständigen 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 dem Speichern ablehnt, und Testen des Ganzen mit einem API-Client eines Drittanbieters. Das durchgehend verwendete 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
    Erstellen Sie den Sicherheitsanbieter, den Anwendungsendpunkt und den Geschäftsobjekt-Endpunkt, die zum Bereitstellen von Daten als REST-API erforderlich sind, und generieren Sie dann einen Schlüssel, damit sich ein bestimmter Benutzer dagegen authentifizieren kann.

  • Benutzerdefinierte Validierungsregel erstellen
    Fügen Sie eine Geschäftsregel hinzu, die eingehende Daten vor dem Speichern validiert, und fügen Sie sie an das Save-Ereignis des Endpunkts an.

  • API-Endpunkt testen
    Verwenden Sie 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, müssen Sie ein bestimmtes Geschäftsobjekt als Endpunkt bereitstellen und eine Möglichkeit für Aufrufer einrichten, sich dagegen zu authentifizieren. In diesem Abschnitt werden die erforderlichen Schritte für beides behandelt:

Schritt 1: API-Schlüssel-Sicherheitsanbieter erstellen

Um Anfragen an Ihren neuen Endpunkt zu authentifizieren, benötigen Sie zunächst einen API-Schlüssel-Sicherheitsanbieter, den App Builder verwendet, um den Schlüssel zu validieren, den jeder Aufrufer präsentiert. Führen Sie diese Schritte aus:

  1. Wählen Sie IDE > Security Providers.

  2. Klicken Sie unter User Authentication auf + User Authentication. Das Dialogfeld Provider wird geöffnet:

    provider dialog

  3. Konfigurieren Sie den Anbieter mit diesen Einstellungen:

    • Name: Geben Sie einen aussagekräftigen Namen ein, z. B. API Key.

    • Type: Wählen Sie API Key.

    • Enabled: Wählen Sie diese Option, um den Anbieter zu aktivieren.

  4. Klicken Sie auf Save.

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

Schritt 2: Anwendungsendpunkt definieren

Die REST-API jeder Anwendung wird über ein Basissegment des Pfads erreicht, ihren Anwendungsendpunkt. Definieren Sie einen jetzt, wenn Ihre Anwendung noch keinen hat:

  1. Wählen Sie IDE > REST APIs.

  2. Klicken Sie auf Manage Endpoints. Das Dialogfeld Application Endpoints wird geöffnet und zeigt zugängliche Anwendungen und ihre Endpunkte:

    Application Endpoints dialog

  3. Suchen Sie die Anwendung, die Sie bereitstellen möchten, und klicken Sie auf das Symbol Edit.

  4. Geben Sie einen Namen für den Endpunkt ein, z. B. endpoint-example.

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

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

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

Mit einem Anwendungs-Endpoint können Sie jetzt ein spezifisches Business-Objekt, z. B. eine Tabelle, als Ressource veröffentlichen, die Aufrufer lesen und schreiben können:

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

  2. Klicken Sie im Panel 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 Endpoint 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-Endpoint 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 Endpoint zu finden, kombinieren Sie die REST-API-Basis-URL Ihrer Instanz mit dem Endpoint Ihrer Anwendung (aus dem vorherigen Schritt) und dem Endpoint der Ressource (aus diesem Schritt). Siehe Datenobjekte als Ressourcen für das genaue URI-Muster.

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 Berechtigungen dieses Benutzers für jede Anfrage gelten, die mit diesem Schlüssel gestellt wird:

  1. Wählen Sie IDE > User Management.

  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 Abschnitt Authentication und bestätigen Sie, dass Login Type auf Interactive eingestellt ist.

  4. Wählen Sie More > Keys. 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 Folgendes fest:

    • Provider: Wählen Sie den Sicherheitsanbieter aus, den Sie in Schritt 1 erstellt haben (z. B. 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 danach. Dieses Beispiel erstellt eine Regel, die verhindert, dass ein Datensatz gespeichert wird, wenn sein Required Date in der Vergangenheit liegt, und fügt diese Regel dann zum Save-Event des Endpoints hinzu, damit sie tatsächlich ausgeführt wird.

Schritt 1: Eine Business-Regel für die Validierung erstellen

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

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

  2. Klicken Sie auf By Table und wählen Sie dann die Tabelle aus, die Sie verfügbar machen (z. B. 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, z. B. Validation: Date Not in Past.

    • Purpose: Wählen Sie Validation.

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

  5. Klicken Sie auf Create.

  6. Konfigurieren Sie die Logik der Regel:

    • Wählen Sie 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 eine Klausel hinzu, um die Fehlerbedingung zu definieren. In diesem Beispiel fügen Sie eine Bedingung hinzu, bei der Required Date kleiner 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 dieselbe 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.

Den 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 eines Drittanbieters verwenden. In diesem Abschnitt wird Postman verwendet, 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, das Ihr Endpunkt erwartet:

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

  2. Fügen Sie im 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 für Type die Option API Key aus.

    • Geben Sie für Key X-API-Key ein.

    • Fügen Sie für 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 im Formatdropdown JSON aus.

Schritt 2: Die Validierungsregel testen (Fehlerfall)

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

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

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