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 Sie über den API Manager konfigurieren können. Für die beiden anderen Typen, OData API und Proxy API, siehe OData API-Konfiguration und Proxy API-Konfiguration.

Alternativ können Sie benutzerdefinierte APIs mit dem APIM AI Assistant oder im Studio über die Option Als API veröffentlichen im Aktionsmenü einer Operation erstellen.

Der API Manager zeigt benutzerdefinierte APIs (veröffentlicht und Entwurf) an diesen Orten an:

• Die APIs Seite des API Managers.
• Die Ressourcen-Registerkarte im Projektbereich des mit der benutzerdefinierten API verbundenen Studio-Projekts.

Voraussetzungen

Eine benutzerdefinierte API stellt eine Harmony-Operation zur Verfügung. Sie müssen diese Operation zuerst in Harmony erstellen und bereitstellen, bevor Sie die benutzerdefinierte API konfigurieren können. Die Operation, die eine benutzerdefinierte API auslöst, kann entweder eine Studio oder Design Studio Operation sein.

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

• Studio
  • Erstellung und Konfiguration von Operationen
  • Bereitstellung und Ausführung von Operationen
• Design Studio
  • Erstellen einer Operation

Erstellen einer neuen benutzerdefinierten API

Wenn Sie die API-Manager-Seite APIs aufrufen und keine benutzerdefinierten APIs, OData-APIs 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 und wählen Sie eine der folgenden Optionen:

• Mit KI erstellen: Öffnet den APIM-Assistenten, um eine API mit natürlichen Sprachaufforderungen zu erstellen. Weitere Informationen finden Sie unter Verwendung des KI-Assistenten.

  Hinweis

  Um den APIM-KI-Assistenten zu verwenden, muss Ihre Harmony-Lizenz die Option APIM-KI-Assistent enthalten. Kontaktieren Sie Ihren Customer Success Manager (CSM), um diese Option zu Ihrer Lizenz hinzuzufügen.

Der API-Manager zeigt die folgende Option nur an, wenn eine entsprechende API-URL verfügbar ist:

• Benutzerdefinierte API: Öffnet den Bildschirm zur Konfiguration der benutzerdefinierten API, um manuell eine neue benutzerdefinierte API zu erstellen. Diese Option ist nur verfügbar, wenn eine entsprechende API-URL vorhanden ist.

Konfigurieren einer benutzerdefinierten API

Wenn Sie eine benutzerdefinierte API manuell konfigurieren, enthält der Konfigurationsbildschirm mehrere Registerkarten. Der Konfigurationsbildschirm umfasst zwei erforderliche Registerkarten und drei optionale Registerkarten:

• Profil-Registerkarte (erforderlich)
• Einstellungen-Registerkarte (optional)
• Dienste-Registerkarte (erforderlich)
• Sicherheitsprofile-Registerkarte (optional)
• Benutzerrollen-Registerkarte (optional)

Profil-Registerkarte

Verwenden Sie die Profil-Registerkarte, um grundlegende Informationen einzugeben, die die API identifizieren.

Konfigurieren Sie die folgenden Einstellungen:

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

• Service Root: Der öffentliche Name der API, der als Teil der API-Dienst-URL 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. Die folgenden Sonderzeichen sind erlaubt: . _ ~ ( ) $ ; / ? : @ = & ' ! * , + -.

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

• Environment: Verwenden Sie das Menü, um die Umgebung auszuwählen, in der die API reside. Sie können jeden 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 können Sie die Umgebung nicht mehr ändern. Um eine API zwischen Umgebungen zu verschieben, können Sie die API klonen oder die API in einer anderen Umgebung exportieren und importieren.

• Version number: Geben Sie eine optionale Version ein, die als Teil der API-Dienst-URL 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. Übliche Namenskonventionen umfassen inkrementelle Versionen wie v1.0, v1.1, v1.2 oder die Verwendung eines Datums, an dem die API veröffentlicht wurde, wie 2025-08-28.

Nachdem Sie den Profil-Tab abgeschlossen haben, klicken Sie auf Weiter, um zum Einstellungen-Tab zu gelangen, oder klicken Sie auf Als Entwurf speichern, um Ihren Fortschritt zu speichern.

Settings tab

Der Einstellungen-Tab ist optional und enthält erweiterte Konfigurationsoptionen für die API.

Konfigurieren Sie die folgenden Einstellungen nach Bedarf:

• Timeout: Geben Sie die Anzahl der Sekunden ein, bevor die API eine Zeitüberschreitung hat. Der Standardwert beträgt 30 Sekunden. Der maximal zulässige Wert beträgt 180 Sekunden.

  Hinweis

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

• Nur SSL: Dieser Schalter ist standardmäßig aktiviert und erfordert HTTPS für die API. Wenn aktiviert, werden Daten über SSL verschlüsselt, und eine HTTP-Anfrage gibt einen Fehler zurück. Wenn deaktiviert, werden sowohl HTTP- als auch HTTPS-Anfragen unterstützt.

  Warnung

  Wenn deaktiviert, 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 offenbaren.

• CORS: Aktivieren Sie diesen Schalter, um CORS (Cross-Origin Resource Sharing) zu unterstützen. CORS ist ein Mechanismus, der es Webanwendungen, die in einem Webbrowser auf einer Domain ausgeführt werden, ermöglicht, auf Ressourcen von einem Server auf einer anderen Domain zuzugreifen.

  Warnung

  Das Aktivieren von CORS führt dazu, dass Operationen, die die Methode OPTIONS verwenden, ohne Authentifizierung ausgeführt werden.

• Ausführliches Protokollieren: Aktivieren Sie diesen Schalter, um rohe Anforderungs- und Antwortdaten – einschließlich Header, Parameter und Inhalte – zum Protokoll hinzuzufügen, wenn eine API-Anfrage gestellt wird. Diese Daten erscheinen auf der Seite API-Protokolle und auf der Seite Runtime der Management-Konsole für sowohl erfolgreiche als auch erfolglose Durchläufe. Ausführliches Protokollieren erzeugt keine Studio-Operation-Protokolle für erfolgreiche Durchläufe. Um erfolgreiche Betriebsdurchläufe in Studio zu protokollieren, verwenden Sie stattdessen Debug-Modus bis.

  Warnung

  Ausführliches Protokollieren kann sensible Daten wie Authentifizierungsanmeldeinformationen oder personenbezogene Informationen enthalten. Verwenden Sie diese Einstellung mit Vorsicht.

• Debug-Modus bis: Aktivieren Sie diesen Schalter, um detailliertes Protokollieren zur Fehlersuche zu aktivieren, und klicken Sie dann auf das Kalendersymbol, um ein Datum bis zu zwei Wochen ab heute auszuwählen, an dem der Debug-Modus automatisch deaktiviert wird. Wenn aktiviert, erscheinen Anforderungs- und Antwortdaten (30 Tage lang aufbewahrt) auf der Seite API-Protokolle, auf der Seite Runtime der Management-Konsole und in den Studio-Operation-Protokollen für sowohl erfolgreiche als auch erfolglose Durchläufe. Das Protokollieren auf Aktivitätsniveau wird ebenfalls aktiviert, wobei Eingabe- und Ausgabedaten der Komponenten im Debug-Protokoll-Tab erfasst werden. Diese Einstellung überschreibt Ausführliches Protokollieren und Anforderungs- und Antwortpayloads in Protokollen anzeigen: Wenn der Debug-Modus aktiviert ist, werden Anforderungs- und Antwortdaten unabhängig davon in Protokollen enthalten, ob diese Einstellungen aktiviert sind oder nicht.

  Warnung

  Debug-Protokolle enthalten alle Anforderungs- und Antwortdaten, einschließlich sensibler Informationen wie Passwörter und personenbezogene Daten (PII). Diese Daten erscheinen im Klartext in den Harmony-Cloud-Protokollen für 30 Tage.

• Anforderungs- und Antwortpayloads in Protokollen anzeigen: Aktivieren Sie diesen Schalter, um Anforderungs- und Antwortpayloads auf der Seite API-Protokolle und der Management Console-Seite Laufzeit anzuzeigen, wenn eine API-Anforderung gestellt wird. Die Payloads erscheinen in einer formatierten Ansicht mit separaten Panels für die Anforderungs- und Antwortkörper, sowohl für erfolgreiche als auch für nicht erfolgreiche Durchläufe. Diese Einstellung erzeugt keine Protokolleinträge für erfolgreiche Durchläufe im Studio. Um erfolgreiche Durchläufe im Studio zu protokollieren, verwenden Sie stattdessen Debug-Modus bis aktivieren. Dieser Schalter gilt nur für benutzerdefinierte und OData-APIs.

  Warnung

  Anforderungs- und Antwortpayloads können sensible Daten wie Authentifizierungsanmeldeinformationen oder personenbezogene Informationen enthalten. Verwenden Sie diese Einstellung mit Vorsicht.

Nachdem Sie die Registerkarte Einstellungen konfiguriert haben, klicken Sie auf Weiter, um zur Registerkarte Dienste zu gelangen, oder klicken Sie auf Zurück, um zur Registerkarte Profil zurückzukehren.

Registerkarte Dienste

Die Registerkarte Dienste ist der Ort, an dem Sie die API-Dienste konfigurieren, die definieren, wie die API auf Anforderungen reagiert. Sie können mehrere Dienste für eine einzelne benutzerdefinierte API konfigurieren. Jeder Dienst muss eine eindeutige Kombination aus HTTP-Methode und Pfad haben.

Klicken Sie auf Neuer Dienst, um einen neuen API-Dienst hinzuzufügen. Konfigurieren Sie die folgenden Einstellungen für jeden Dienst:

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

• Methode: Wählen Sie die HTTP-Methode für diesen Dienst aus dem Dropdown-Menü aus. Verfügbare Methoden sind GET, POST, PUT, DELETE und ALL. Um eine nicht aufgeführte Methode zu verwenden, geben Sie den Methodennamen in das Textfeld Geben Sie eine neue Methode ein ein und drücken Sie Enter.

• Pfad: Geben Sie den URL-Pfad ein, der diesen Dienst auslöst. Der Pfad wird an die Dienst-Root in der API-Dienst-URL angehängt.

• Projekt: Wählen Sie das Harmony-Projekt aus, das die Operation enthält, die dieser Dienst auslöst.

  • Zum Projekt gehen: Klicken Sie, um ein Studio-Projekt in einem neuen Browser-Tab zu öffnen. Diese Option ist für Design Studio-Projekte deaktiviert.

• Operation To Trigger: Wählen Sie die spezifische Operation aus dem gewählten Projekt aus, die dieser Dienst bei Aufruf ausführt.

  Für Informationen darüber, was in den Betriebsprotokollen für API-ausgelöste Operationen erscheint und wie Sie zusätzliche Protokollierung aktivieren können, siehe API-Anforderungs- und Antwortdaten in Betriebsprotokollen.

• Antworttyp: Wählen Sie aus, wie die API die Betriebsantwort zurückgibt. Verfügbare Optionen sind Endziel, Systemvariable und Keine Antwort.

  • Endziel: Die API-Antwort ist das Endziel der Operationenkette. Wenn Sie diesen Antworttyp auswählen, muss die ausgewählte Operation als Endziel der Operationenkette eine Studio- API-Antwortaktivität oder Variable Write-Aktivität oder ein Design Studio API-Antwortziel oder Globales Variablenziel haben. Wenn die Operation ein anderes Endziel verwendet, ist die API-Antwort leer.

  • Systemvariable: Die API-Antwort wird in einer Jitterbit-Variable in der Operationenkette festgelegt. Wenn Sie diesen Antworttyp auswählen, muss die ausgewählte Operation als Teil der Operationenkette ein Skript haben, das die Jitterbit-Variable jitterbit.api.response gleich der Antwort setzt, die Sie von der API zurückgeben möchten. Wenn das Skript diese Variable nicht setzt, ist 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.

• Aktionen: Fahren Sie mit der Maus über eine Dienstzeile, um zusätzliche Aktionen anzuzeigen.

  • API-Dienst-URL kopieren: Klicken Sie, um die API-Dienst-URL zu kopieren.
  • Zum API-Dienst gehen: Klicken Sie, um eine Übersicht über die Konfiguration der benutzerdefinierten API auf einer einzelnen Seite zu sehen.
  • Duplizieren: Klicken Sie, um den API-Dienst zu duplizieren.
  • Löschen: Klicken Sie, um den API-Dienst zu löschen.

Nachdem Sie die grundlegenden Dienstkonfigurationen festgelegt haben, können Sie zusätzliche Parameter über die Registerkarten unter der Dienstkonfiguration konfigurieren:

Pfadparameter-Registerkarte

Wenn Anforderungsparameter im Pfad enthalten sind, zeigt diese Registerkarte die im Pfad definierten Parameter an:

• Parameter: Zeigt jeden im Pfad definierten Anforderungsparameter an.

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

Abfrageparameter-Registerkarte

Diese Registerkarte ermöglicht es Ihnen, Abfrageparameter zum API-Dienst hinzuzufügen:

• Parameter hinzufügen: Klicken Sie, um einen Abfrageparameter zum API-Dienst hinzuzufügen. Die folgenden Felder werden 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öschsymbol neben einem Abfrageparameter, um diesen Parameter zu löschen.

Header-Registerkarte

Diese Registerkarte ermöglicht es Ihnen, Anforderungsheader zum API-Dienst hinzuzufügen:

• Header hinzufügen: Klicken Sie, um einen Anforderungsheader zum API-Dienst hinzuzufügen. Die folgenden Felder werden verfügbar:

  • Parameter: Geben Sie den Namen des Anforderungsheaders ein.

• Beschreibung: Optional können Sie eine Beschreibung für den Anforderungsheader eingeben.

• Erforderlich: Aktivieren Sie das Kontrollkästchen, um diesen Header für API-Anfragen erforderlich zu machen.

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

Sie können mehrere Dienste für eine einzelne benutzerdefinierte API konfigurieren. Jeder Dienst muss eine eindeutige Kombination aus HTTP-Methode und Pfad haben.

Verwenden Sie die Aktionen-Spalte, um vorhandene Dienste zu bearbeiten oder zu löschen.

Nachdem Sie die Dienste-Registerkarte konfiguriert haben, klicken Sie auf Weiter, um zur Registerkarte Sicherheitsprofile zu gelangen, oder klicken Sie auf Zurück, um zur Registerkarte Einstellungen zurückzukehren.

Registerkarte Sicherheitsprofile

Die Sicherheitsprofile-Registerkarte ist optional und ermöglicht es Ihnen, den Zugriff auf die Nutzung der API einzuschränken.

Konfigurieren Sie die folgenden Einstellungen:

• Zuweisen: Verwenden Sie den Schalter, um Sicherheitsprofile für die API zuzuweisen oder zu entfernen.

• Profilname: Der Name des Sicherheitsprofils, wie in Sicherheitsprofilen konfiguriert.

• Typ: Der Authentifizierungstyp für das Sicherheitsprofil, wie Basic, OAuth 2.0 oder API-Schlüssel.

• Benutzername: Bei der Basis-Authentifizierung wird der Benutzername angezeigt. Bei anderen Authentifizierungstypen wird derselbe Wert wie in der Typ-Spalte angezeigt.

• Aktionen: Fahren Sie mit der Maus über eine Zeile eines Sicherheitsprofils, um zusätzliche Aktionen anzuzeigen.

  • Gehe zu Sicherheitsprofil: Klicken Sie, um die Konfiguration des Sicherheitsprofils zu öffnen.

Je nach den Richtlinien der Harmony-Organisation müssen Sie möglicherweise ein Sicherheitsprofil zuweisen, um die API zu speichern.

Klicken Sie auf Neues Sicherheitsprofil, um ein neues Sicherheitsprofil zu erstellen. Für Anweisungen siehe Sicherheitsprofile konfigurieren.

Nachdem Sie die Registerkarte Sicherheitsprofile konfiguriert haben, klicken Sie auf Weiter, um zur Benutzerrollen-Registerkarte zu gelangen, oder klicken Sie auf Zurück, um zur Dienste-Registerkarte zurückzukehren.

Benutzerrollen-Registerkarte

Die Registerkarte Benutzerrollen ist optional und bestimmt, welche Organisationsrollen Zugriff auf die API im API-Manager haben.

Konfigurieren Sie die folgenden Einstellungen:

• Benutzerrolle: Der Name der Organisationsrolle, wie auf der Registerkarte Rollen der Benutzerverwaltungsseite definiert.

• Berechtigungen: Die diesem Rolle zugewiesenen Berechtigungen, wie Lesen oder Admin.

• Status: Gibt an, ob die Rolle dieser API zugewiesen ist. Schalten Sie den Status um, um Rollen zuzuweisen oder abzuwählen.

• Aktionen: Fahren Sie mit der Maus über eine Zeile der Benutzerrolle, um zusätzliche Aktionen anzuzeigen.

  • Zur Benutzerrolle gehen: Klicken Sie, um die Konfiguration der Benutzerrolle zu öffnen.

Die hier ausgewählten Rollen bestimmen den Zugriff auf diese spezifische API von diesen Seiten:

• APIs
• Portal-Manager, einschließlich der Erstellung von API-Dokumentationen
• API-Portal
• API-Protokolle
• Analytik

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.

Klicken Sie auf Neue Benutzerrolle, um eine neue Benutzerrolle zu erstellen. Für Anweisungen siehe Rollen in Benutzerverwaltung.

Nachdem Sie die Registerkarte Benutzerrollen konfiguriert haben, klicken Sie auf Veröffentlichen, um die API zu veröffentlichen, oder klicken Sie auf Als Entwurf speichern, um Ihren Fortschritt zu speichern.

Optionen zum Speichern und Veröffentlichen

Nachdem Sie alle erforderlichen Registerkarten konfiguriert haben, können Sie die API speichern oder veröffentlichen:

• Als Entwurf speichern: Speichert die API im Status Entwurf oder Veröffentlicht mit Entwurf. Entwurfs-APIs zählen nicht gegen Ihr API-URL-Abonnementlimit. Eine API, deren Status zum Zeitpunkt der Verwendung von Als Entwurf speichern Veröffentlicht war, wird als Veröffentlicht mit Entwurf gespeichert. Eine veröffentlichte API zählt gegen Ihr API-URL-Abonnementlimit, auch wenn ihr Entwurf nicht zugänglich ist.

• 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. Ein Dialog zeigt an, dass die API live ist:

  

  Der Dialog bietet diese Optionen:

  • URL kopieren: Kopiert die Service-URL der API in Ihre Zwischenablage.
  • OpenAPI-Dokument generieren: Öffnet die Seite Portal-Manager, auf der Sie API-Dokumentationen für alle APIs in einer Umgebung generieren können. Um Dokumentationen für einzelne APIs zu generieren, verwenden Sie die Dokumentationsregisterkarte, wenn Sie die API von der Seite APIs bearbeiten.
  • 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 Kartenansicht auf der APIs-Seite, klicken Sie auf die Karte.
• Verwenden Sie die Listenansicht auf der APIs-Seite, klicken Sie auf Bearbeiten in der Spalte Aktionen.

Beim Bearbeiten einer veröffentlichten API aus der Listenansicht ist auch eine Dokumentation-Registerkarte verfügbar. Verwenden Sie diese Registerkarte, um die OpenAPI-Dokumentation für einzelne APIs anzuzeigen, zu bearbeiten und zu veröffentlichen. Weitere Informationen finden Sie auf der Seite Dokumentation-Registerkarte auf der Seite APIs.