Zum Inhalt springen

Benutzerdefinierte API-Konfiguration im Jitterbit API Manager

Einführung

Diese Seite beschreibt, wie man eine benutzerdefinierte API von der APIs Seite des Jitterbit API Managers erstellt und konfiguriert. Benutzerdefinierte APIs sind eine der drei API-Typen, die über den API Manager konfiguriert werden. Für die beiden anderen Typen — OData-Dienst und Proxy-API — siehe OData-Dienstkonfiguration und Proxy-API-Konfiguration.

Alternativ können benutzerdefinierte APIs im Integration Studio mit der Option Als API veröffentlichen erstellt werden, die über das Aktionsmenü einer Operation zugänglich ist.

Hinweis

Nach der Veröffentlichung zählt jede benutzerdefinierte API als eine API-URL gegen Ihr Harmony-Abonnement.

Benutzerdefinierte APIs (veröffentlicht und Entwurf) werden an diesen Orten angezeigt:

  • Auf der APIs Seite des API Managers.
  • Im Ressourcen-Tab des Projektfensters für das Integration Studio-Projekt, das mit der benutzerdefinierten API verbunden ist.

Voraussetzungen

Da eine benutzerdefinierte API eine Harmony-Operation zur Nutzung bereitstellt, muss eine solche Operation zuerst in Harmony erstellt und bereitgestellt werden. Die vorhandene Operation wird dann während der Konfiguration der benutzerdefinierten API referenziert. Die Operation, die eine benutzerdefinierte API auslöst, kann entweder eine Integration Studio oder Design Studio Operation sein.

Für Anleitungen zur Erstellung und Bereitstellung einer Operation siehe diese Ressourcen:

Erstellen einer neuen benutzerdefinierten API

Wenn Sie die API-Manager-Seite APIs aufrufen und keine benutzerdefinierten APIs, OData-Dienste oder Proxy-APIs in der ausgewählten Organisation vorhanden sind, ist dieser Bildschirm leer.

Um eine neue benutzerdefinierte API zu erstellen, klicken Sie auf Neu > Benutzerdefinierte API:

no APIs new API

Beim Klicken auf Neue API öffnet sich der Bildschirm zur Konfiguration der benutzerdefinierten API. Einzelheiten zur Konfiguration einer neuen benutzerdefinierten API finden Sie in Konfigurieren einer benutzerdefinierten API weiter unten.

Konfigurieren einer benutzerdefinierten API

Der Konfigurationsbildschirm umfasst vier Konfigurationsschritte, die im Folgenden behandelt werden:

Die Dienst-URL einer API ist die URL, die verwendet wird, um die API mit einer konfigurierten Authentifizierungsmethode zu konsumieren. Die Teile der Dienst-URL einer API werden unter API-Manager Erste Schritte in API-Dienst-URL beschrieben.

Die Dienst-URL wird oben in jedem Schritt nach Abschluss von Schritt 1 angezeigt:

publish new API step 1 settings service URL

Schritt 1: Einstellungen

publish new API step 1 settings

  • API-Name: Geben Sie einen Namen für die API ein, der für interne Identifikationszwecke verwendet wird. Diese Sonderzeichen sind erlaubt:

    ( ) - _

  • Umgebung: Verwenden Sie das Menü, um die Umgebung auszuwählen, in der die API reside. Sie können einen Teil des Umgebungsnamens in das Menü eingeben, um die Liste der Umgebungen zu filtern. Die Menüergebnisse werden in Echtzeit mit jedem Tastendruck gefiltert.

    Hinweis

    Nach der Erstellung der API kann die Umgebung nicht mehr geändert werden. Um eine API zwischen Umgebungen zu verschieben, können Sie die API klonen oder die API in einer anderen Umgebung exportieren und importieren.

  • Service-Root: Der öffentliche Name der API, der als Teil der Service-URL der API verwendet wird. Standardmäßig wird dieses Feld mit dem API-Namen gefüllt, der in Camel Case umgewandelt wurde. Dieses Feld erlaubt keine Leerzeichen oder bestimmte Sonderzeichen. Die Verwendung von Sonderzeichen außer einem Unterstrich (_) wird nicht empfohlen. Diese Sonderzeichen sind erlaubt:

    . _ ~ ( ) $ ; / ? : @ = & ' ! * , + -

  • Version: Geben Sie eine optionale Version ein, die als Teil der Service-URL der API verwendet wird. Dieses Feld erlaubt maximal 48 Zeichen und erlaubt keine Leerzeichen oder bestimmte Sonderzeichen. Die Verwendung von Sonderzeichen außer einem Punkt (.) oder einem Bindestrich (-) wird nicht empfohlen. Häufige Namenskonventionen umfassen die Erhöhung von Versionen, wie v1.0, v1.1, v1.2, oder die Verwendung eines Datums, an dem die API veröffentlicht wurde, wie 2021-08-28.

  • Beschreibung: Geben Sie eine optionale Beschreibung für die API ein.

  • Timeout: Geben Sie die Anzahl der Sekunden ein, bevor die API eine Zeitüberschreitung hat. Der Standardwert beträgt 30 Sekunden. Das Maximum sind 180 Sekunden.

    Hinweis

    Diese Einstellung ist unabhängig von der Timeout-Einstellung für Operationen in Integration Studio oder Design Studio. Timeout-Einstellungen für Operationen werden nicht verwendet, es sei denn, es wird ein privater Agent verwendet und die Einstellung EnableAPITimeout in der Konfigurationsdatei des privaten Agents ist aktiviert.

  • Nur SSL: Wenn ausgewählt (Standard), werden Daten über SSL verschlüsselt und HTTPS wird für alle API-Anfragen und -Antworten durchgesetzt (empfohlen).

    Wenn nicht ausgewählt, sind die über API-Anfragen und -Antworten übermittelten Daten nicht verschlüsselt und können von anderen abgefangen und eingesehen werden. Dies könnte potenziell sensible Informationen offenlegen.

  • CORS aktivieren: Wählen Sie aus, um Cross-Origin Resource Sharing (CORS) zu aktivieren (nicht empfohlen). CORS aktivieren ist standardmäßig ausgewählt.

    Warnung

    Das Aktivieren von CORS führt dazu, dass Vorgänge, die die OPTIONS-Methode verwenden, ohne Authentifizierung ausgeführt werden.

  • Ausführliches Protokollieren aktivieren: Wählen Sie aus, um das ausführliche Protokollieren zu aktivieren. Das ausführliche Protokollieren für APIs umfasst Anforderungs- und Antwortdaten in jedem API-Protokoll, um eingehende und ausgehende Daten zu überwachen und das Debuggen zu erleichtern. Da dies große Protokolldateien erstellen kann, ist standardmäßig das ausführliche Protokollieren deaktiviert.

  • Debug-Modus aktivieren bis: Wählen Sie aus, um den Debug-Modus zu aktivieren und ein entsprechendes Datum und eine Uhrzeit einzugeben, zu denen der Debug-Modus deaktiviert wird. Die maximale Dauer der Aktivierung beträgt zwei Wochen. Der Debug-Modus ermöglicht eine vollständige Nachverfolgung jeder Anfrage, die über die Dienst-URL der API empfangen wird. Wenn aktiviert, behält das System den vollständigen Inhalt jeder API-Anfrage und -Antwort bis zu 24 Stunden nach dem Zeitpunkt, an dem der API-Aufruf empfangen wurde, und gilt für alle durch die API ausgelösten Vorgänge.

    Hinweis

    Das Durchsuchen der Ereignisdaten kann bei großen Volumina (Lasttests, Vorproduktionstests usw.) schwierig werden. Die Erhöhung der gespeicherten Daten kann zu Speicherplatz- und Sicherheitsbedenken führen. Wir empfehlen nicht, den Debug-Modus in einer Produktionsumgebung zu verwenden.

  • Next: Klicken Sie, um die Konfiguration für diesen Schritt vorübergehend zu speichern und zum nächsten Schritt fortzufahren.

  • Save Changes: Klicken Sie, um die Konfiguration für diesen Schritt zu speichern und zu Schritt 4: Zusammenfassung und Bestätigung zu navigieren.

Schritt 2: Wählen Sie den Diensttyp und weisen Sie Operationen zu

Wählen Sie den Diensttyp

  • Diensttyp: Wählen Sie Benutzerdefinierte API.

  • API-Dienst hinzufügen: Klicken Sie, um einen API-Dienst hinzuzufügen, um eine Harmony-Operation zur Nutzung bereitzustellen. Nach dem Klicken wird die Konfiguration des einzelnen API-Dienstes geöffnet (siehe unten). Mehrere API-Dienste können zu einer benutzerdefinierten API hinzugefügt werden.

Nachdem Sie auf API-Dienst hinzufügen geklickt haben, wird die Konfiguration für einen API-Dienst geöffnet:

Veröffentlichen Sie neue API Schritt 2 Operationen zuweisen benutzerdefiniert

  • Anforderungsmethode: Verwenden Sie das Menü, um die Anforderungsmethode für den API-Dienst auszuwählen, eine der GET, POST, PUT, DELETE, ALL oder CUSTOM. Die Auswahl von ALL erstellt separate GET, PUT, POST und DELETE Methoden für die ausgewählte Operation (die CUSTOM Methode ist nicht enthalten). Standardmäßig ist die Anforderungsmethode auf GET eingestellt.

    Hinweis

    API-Dienste, die eine CUSTOM Methode verwenden, haben aufgrund einer Einschränkung der OpenAPI-Spezifikation keine OpenAPI-Dokumentation, die über den Portal Manager generiert wird.

  • Dienstname: Geben Sie einen Namen für den API-Dienst ein.

  • Pfad: Geben Sie optional einen Pfad für die Anfrage ein. Der Pfad muss mit einem Schrägstrich / beginnen und alle Anfrageparameter müssen in geschweifte Klammern { } eingeschlossen sein. Andere Sonderzeichen sind nicht erlaubt.

    Hinweis

    Die Kombination aus Anforderungsmethode und Pfad muss für jeden API-Dienst in der benutzerdefinierten API eindeutig sein.

  • Benutzerdefinierter Methodenname: Sichtbar, wenn CUSTOM als Anforderungsmethode ausgewählt ist. Geben Sie den Namen der zu verwendenden Methode ein, zum Beispiel PATCH. (Nur Alpha-Zeichen, Bindestriche - und Unterstriche _.)

  • Operation: Im Tab Operation wählen Sie ein Projekt und eine Operation aus, die dem API-Dienst zugewiesen werden sollen (erforderlich, um die Schaltfläche Speichern zu aktivieren):

    • Projekt zuweisen: Verwenden Sie das Menü, um ein bereitgestelltes Projekt aus der Umgebung auszuwählen, in der die API konfiguriert wird (angegeben in Schritt 1: Einstellungen). Sie können einen Teil des Projektnamens in das Menü eingeben, um die Liste der Projekte zu filtern. Die Menüergebnisse werden in Echtzeit mit jedem Tastendruck gefiltert.

    • Projekt bearbeiten: Wenn ein Integration Studio-Projekt ausgewählt ist, wird diese Schaltfläche aktiviert. Ein Klick auf Projekt bearbeiten öffnet das Projekt im Integration Studio in einem neuen Tab.

      Hinweis

      Sie müssen alle Änderungen, die am Projekt vorgenommen wurden, bereitstellen, damit sie wirksam werden.

    • Operation(en) zuweisen: Verwenden Sie die Menüs, um eine Operation und einen Antworttyp für den API-Dienst auszuwählen:

      • Operation: Wählen Sie aus den bereitgestellten Operationen im ausgewählten Projekt. Sie können einen Teil des Operationsnamens in das Menü eingeben, um die Liste der bereitgestellten Operationen zu filtern. Die Menüergebnisse werden in Echtzeit mit jedem Tastendruck gefiltert.

        Wichtig

        Standardmäßig sind erfolgreiche Operationen, die für eine benutzerdefinierte API konfiguriert sind, nicht in den Operationsprotokollen enthalten, es sei denn, eine dieser Einstellungen ist aktiviert:

        Nicht erfolgreiche Operationen sind in den Operationsprotokollen enthalten, unabhängig davon, ob die obigen Einstellungen aktiviert sind oder nicht.

      • Antworttyp: Wählen Sie einen der Endziel, Systemvariable oder Keine Antwort:

        • Endziel: Die API-Antwort ist das Endziel der Operationenkette. Wenn dieser Antworttyp ausgewählt ist, muss die ausgewählte Operation als Endziel der Operationenkette eine Integration Studio API-Antwortaktivität oder Variable Write-Aktivität, oder ein Design Studio API-Antwortziel oder Globales Variablenziel. Wenn ein anderes Endziel verwendet wird, bleibt die API-Antwort leer.

        • Systemvariable: Die API-Antwort wird in einer Jitterbit-Variable in der Operationenkette festgelegt. Wenn dieser Antworttyp ausgewählt ist, muss die ausgewählte Operation als Teil der Operationenkette ein Skript enthalten, das die Jitterbit-Variable jitterbit.api.response gleich der Antwort setzt, die die API zurückgeben soll. Wenn diese Variable nicht gesetzt ist, bleibt die API-Antwort leer.

        • Keine Antwort: Die API-Antwort ist leer. Wenn die Anfrage zur Ausführung der ausgewählten Operation akzeptiert wird, gibt die API sofort eine leere Antwort mit dem HTTP-Code 202 zurück.

  • Pfadparameter: Wenn Anforderungsparameter im Pfad enthalten sind, wird dieser Tab mit diesen Feldern gefüllt:

    path params tab

    • Parameter: Zeigt die im Pfad definierten Anforderungsparameter an.

    • Beschreibung: Geben Sie optional eine Beschreibung für die Anforderungsparameter ein.

  • Abfrageparameter: Dieser Tab ermöglicht es Ihnen, beliebige Abfrageparameter zum API-Dienst hinzuzufügen:

    query params tab

    • Parameter hinzufügen: Klicken Sie, um einen Abfrageparameter zum API-Dienst hinzuzufügen. Nach dem Klicken werden diese Felder verfügbar:

      • Parameter: Geben Sie den Namen des Abfrageparameters ein.

      • Beschreibung: Geben Sie optional die Beschreibung des Abfrageparameters ein.

      • Löschen: Klicken Sie auf das Löschen-Symbol neben einem Abfrageparameter, um diesen Parameter zu löschen.

  • Header: Dieser Tab ermöglicht es Ihnen, beliebige Anforderungsheader zum API-Dienst hinzuzufügen:

    headers tab

    • Parameter hinzufügen: Klicken Sie, um einen Anforderungsheader zum API-Dienst hinzuzufügen. Nach dem Klicken werden diese Felder verfügbar:

      • Parameter: Geben Sie den Namen des Anforderungsheaders ein.

      • Beschreibung: Geben Sie optional die Beschreibung des Anforderungsheaders ein.

      • Erforderlich: Wählen Sie aus, ob der Anforderungsheader für jede API-Dienstanforderung erforderlich sein soll.

      • Löschen: Klicken Sie auf das Löschen-Symbol neben einem Anforderungsheader, um diesen Header zu löschen.

  • Duplizieren: Klicken Sie auf das Duplizieren-Symbol, um eine Kopie des API-Dienstes zu erstellen.

    Hinweis

    Sobald der API-Dienst dupliziert wurde, müssen Sie entweder die Anforderungsmethode oder den Pfad ändern, da jeder API-Dienst eine eindeutige Kombination dieser Felder haben muss.

  • Löschen: Klicken Sie auf das Löschen-Symbol neben einem API-Dienst, um ihn aus der benutzerdefinierten API zu löschen.

  • Speichern: Klicken Sie, um den API-Dienst zu speichern. Wenn die Konfiguration für alle API-Dienste abgeschlossen ist, sind die Schaltflächen Weiter und Änderungen speichern aktiviert. Eine unvollständige API-Dienstkonfiguration wird durch ein Fehler-Symbol neben dem Namen des API-Dienstes angezeigt:

    incomplete API service

Um die Schaltflächen Weiter und Änderungen speichern zu aktivieren, vervollständigen Sie die Konfiguration oder löschen Sie den API-Dienst.

  • Abbrechen: Klicken Sie, um die Konfiguration des API-Dienstes abzubrechen.

  • Weiter: Klicken Sie, um die Konfiguration für diesen Schritt vorübergehend zu speichern und zum nächsten Schritt fortzufahren.

  • Änderungen speichern: Klicken Sie, um die Konfiguration für diesen Schritt zu speichern und zu Schritt 4: Zusammenfassung und Bestätigung zu navigieren.

Schritt 3: Benutzerrollen und Sicherheitsprofile zuweisen

neuen API Schritt 3 Benutzerrollen Sicherheitsprofile veröffentlichen

  • Benutzerrollen zuweisen: Wählen Sie die Organisationsrollen aus, deren Mitglieder über die unten aufgeführten Seiten im API-Manager auf die API zugreifen können. Die auszuwählenden Rollen sind die, die auf der Registerkarte Rollen der Benutzerverwaltungsseite definiert sind.

    Dies bestimmt den Zugriff auf diese spezifische API von diesen Seiten aus:

    Der Zugriff auf die Seite Sicherheitsprofile und der Zugriff auf die Nutzung der API sind von dieser Auswahl nicht betroffen. (Der Zugriff auf die Nutzung einer API wird durch Sicherheitsprofile gesteuert.)

    Alle definierten Benutzerrollen mit der Berechtigung Admin haben immer vollen Zugriff auf alle APIs und können daher nicht von der Auswahl entfernt werden. (Im obigen Beispielbild kann die Rolle Administrator aus diesem Grund nicht abgewählt werden.)

    Hinweis

    APIs, die vor Harmony 10.22 erstellt wurden, haben standardmäßig alle Benutzerrollen ausgewählt, um den fortgesetzten Zugriff für alle Benutzer sicherzustellen.

  • Sicherheitsprofil(e) zuweisen: Verwenden Sie das Dropdown-Menü, um ein vorhandenes Sicherheitsprofil auszuwählen, das verwendet wird, um den Zugriff auf die API zu beschränken. Sie können einen beliebigen Teil des Namens des Sicherheitsprofils in das Menü eingeben, um die Liste der Sicherheitsprofile zu filtern. Die Menüergebnisse werden in Echtzeit mit jedem Tastendruck gefiltert. Ein Sicherheitsprofil kann erforderlich sein, um die API zu speichern, abhängig von den Richtlinien der Harmony-Organisation.

    • Profil zuweisen: Klicken Sie, um ein ausgewähltes Sicherheitsprofil der API zuzuweisen. Zugewiesene Sicherheitsprofile werden in der Tabelle mit dem Profilnamen und Typ angezeigt, wie im Sicherheitsprofilkonfiguration konfiguriert. Wenn der Typ Basic ist, zeigt die Spalte Benutzername den während der Konfiguration angegebenen Benutzernamen an. Wenn der Typ ein anderer Typ ist, zeigt die Spalte Benutzername denselben Wert wie der Typ an. Um ein zugewiesenes Profil zu entfernen, klicken Sie auf das Entfernen-Symbol.
    • Neues Profil erstellen: Klicken Sie, um ein neues Sicherheitsprofil zu erstellen. Für Anweisungen siehe Sicherheitsprofile.

  • Weiter: Klicken Sie, um die Konfiguration für diesen Schritt vorübergehend zu speichern und zum nächsten Schritt fortzufahren. Wenn der API kein erforderliches Sicherheitsprofil zugewiesen ist, ist diese Option deaktiviert.

  • Änderungen speichern: Wenn aktiviert, klicken Sie, um die Konfiguration für diesen Schritt zu speichern. Wenn der API kein erforderliches Sicherheitsprofil zugewiesen ist, ist diese Option deaktiviert.

  • Diesen Schritt überspringen: Wenn vorhanden, klicken Sie, um zum nächsten Schritt fortzufahren, ohne die Konfiguration für diesen Schritt zu speichern. Wenn der API kein erforderliches Sicherheitsprofil zugewiesen ist, ist diese Option nicht vorhanden.

Schritt 4: Zusammenfassung und Bestätigung

veröffentlichen neuer API Schritt 4 Zusammenfassung

  • API-Name und Umgebung: Der API-Name gefolgt von der Umgebung in Klammern, wie in Schritt 1: Einstellungen konfiguriert.

    • Beschreibung, Zeitüberschreitung, Nur SSL, CORS aktiviert und Ausführliches Protokollieren aktiviert: Die API-Beschreibung und andere Einstellungen, die aktiviert () oder deaktiviert () sind. Um Änderungen an diesen Einstellungen vorzunehmen, klicken Sie auf das Bearbeitungssymbol, um zu Schritt 1: Einstellungen zurückzukehren.
    • Debug-Modus aktivieren bis: Diese Option ist dieselbe wie die, die in Schritt 1: Einstellungen beschrieben ist. Sie können diese Einstellung direkt aus diesem Schritt ändern, anstatt zum ersten Schritt zurückkehren zu müssen.

  • Operationen: Die in Schritt 2: Diensttyp auswählen und Operationen zuweisen zugewiesenen Operationen mit den entsprechenden Informationen für den ausgewählten Diensttyp. Um Änderungen vorzunehmen, klicken Sie auf das Bearbeitungssymbol, um zu Schritt 2: Diensttyp auswählen und Operationen zuweisen zurückzukehren.

  • Benutzerrollen und Sicherheitsprofile: Die in Schritt 3: Benutzerrollen und Sicherheitsprofile zuweisen zugewiesenen Rollen und Sicherheitsprofile. Um Änderungen vorzunehmen, klicken Sie auf das Bearbeitungssymbol, um zu Schritt 3: Benutzerrollen und Sicherheitsprofile zuweisen zurückzukehren.

  • Export: Generiert und initiiert den Download einer APK-Datei (apis-export.apk), die einen Export der API enthält (siehe Exportieren und Importieren von APIs).

  • Klonen: Erstellt eine Kopie einer bestehenden API. In der API-Kopie wird der API-Name mit Kopie von vorangestellt, der Dienststamm wird mit Kopie von vorangestellt, und die Version wird mit -2 angehängt. Die API-Kopie wird sofort in ihrem eigenen Schritt 4: Zusammenfassung und Bestätigung geöffnet.

  • Löschen: Löscht die API dauerhaft und schließt die Konfiguration. Ein Dialog fragt Sie, ob Sie die API wirklich löschen möchten.

    Hinweis

    Wenn der Status der API Veröffentlicht oder Veröffentlicht mit Entwurf zum Zeitpunkt der Löschung war, wird sie auch von der Anzahl der API-URLs entfernt, die gegen Ihr Abonnementlimit verwendet werden. Wenn der Status der API zum Zeitpunkt der Löschung Entwurf war, ändert sich die Anzahl der API-URLs, die gegen Ihr Abonnementlimit verwendet werden, nicht, da die API im Status Entwurf nicht zugänglich war.

  • Als Entwurf speichern: Speichert die API im Status Entwurf oder Veröffentlicht mit Entwurf:

  • Entwurf: Eine neue API oder eine API, deren Status zum Zeitpunkt der Verwendung von Als Entwurf speichern Entwurf war. Entwürfe zählen nicht gegen Ihr API-URL-Abonnementlimit.

  • Veröffentlicht mit Entwurf: Eine API, deren Status zum Zeitpunkt der Verwendung von Als Entwurf speichern Veröffentlicht war. Eine API, die mit einem Entwurf veröffentlicht wird, zählt gegen Ihr API-URL-Abonnementlimit, da die API zugänglich ist, obwohl ihr Entwurf nicht.

  • Speichern und Veröffentlichen: Speichert die API im Status Veröffentlicht. Die API ist live und innerhalb von fünf Minuten zugänglich. Eine veröffentlichte API zählt gegen Ihr API-URL-Abonnementlimit, da die API zugänglich ist. Ein Dialog zeigt an, dass die API live ist:

    alles bereit, Ihre API ist live benutzerdefinierte API

  • URL kopieren: Kopiert die Service-URL der API (siehe API-Service-URL).

  • OpenAPI-Dokument generieren: Öffnet die Seite Portal Manager, auf der Sie API-Dokumentation für die Seite Portal generieren können.
  • Schließen: Schließt den Dialog.

API bearbeiten

Nachdem Sie die API gespeichert haben, können Sie sie von diesen Standorten aus bearbeiten:

  • Verwenden Sie die Kachelansicht auf der Seite APIs, klicken Sie auf Anzeigen/Bearbeiten.
  • Verwenden Sie die Listenansicht auf der Seite APIs, klicken Sie auf Bearbeiten in der Spalte Aktionen.