Benutzerdefinierte API-Konfiguration in Jitterbit API Manager

Einführung

Diese Seite beschreibt, wie man eine benutzerdefinierte API auf der Seite APIs des Jitterbit API Manager erstellt und konfiguriert. Benutzerdefinierte APIs sind einer der drei API-Typen, die man über API Manager konfigurieren kann. Für die beiden anderen Typen, OData-Dienst und Proxy-API, siehe OData-Dienst-Konfiguration und Proxy-API-Konfiguration.

Alternativ können benutzerdefinierte APIs mit dem APIM AI Assistant oder in Studio mit der Option Als API veröffentlichen aus dem Aktionsmenü einer Operation erstellt werden.

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

• Die Seite APIs von API Manager.
• Der Tab Ressourcen im Projektbereich für das Studio-Projekt, das der benutzerdefinierten API zugeordnet ist.

Voraussetzungen

Eine benutzerdefinierte API macht eine Harmony-Operation zur Nutzung verfügbar. Man muss diese Operation zunächst in Harmony erstellen und bereitstellen, bevor man die benutzerdefinierte API konfigurieren kann. Die Operation, die eine benutzerdefinierte API auslöst, kann entweder eine Studio- oder Design Studio-Operation sein.

Anweisungen zum Erstellen und Bereitstellen einer Operation finden Sie in diesen Ressourcen:

• Studio
  • Operation – Erstellung und Konfiguration
  • Operation – Bereitstellung und Ausführung
• Design Studio
  • Operation erstellen

Neue benutzerdefinierte API erstellen

Wenn Sie die Seite APIs von API Manager aufrufen und in der ausgewählten Organisation keine benutzerdefinierten APIs, OData-Dienste oder Proxy-APIs 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 Assistant, um eine API mit natürlichsprachigen Eingabeaufforderungen zu erstellen. Weitere Informationen finden Sie unter Verwendung des AI Assistant.

  Hinweis

  Um den APIM AI Assistant zu nutzen, muss die Harmony-Lizenz die Option APIM AI Assistant enthalten. Kontaktieren Sie Ihren Customer Success Manager (CSM), um diese Option zu Ihrer Lizenz hinzuzufügen.

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

• Benutzerdefinierte API: Öffnet den Konfigurationsbildschirm für benutzerdefinierte APIs, um manuell eine neue benutzerdefinierte API zu erstellen. Diese Option ist nur aktiviert, wenn eine entsprechende API-URL verfügbar ist.

Benutzerdefinierte API konfigurieren

Wenn man eine benutzerdefinierte API manuell konfiguriert, enthält der Konfigurationsbildschirm mehrere Tabs. Der Konfigurationsbildschirm enthält zwei erforderliche Tabs und drei optionale Tabs:

• Profil-Tab (erforderlich)
• Einstellungen-Tab (optional)
• Services-Tab (erforderlich)
• Sicherheitsprofile-Tab (optional)
• Benutzerrollen-Tab (optional)

Registerkarte "Profil"

Verwenden Sie die Registerkarte Profil, 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 zulässig: ( ) - _.

• 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 konvertiert wird. Dieses Feld erlaubt keine Leerzeichen oder bestimmte Sonderzeichen. Die Verwendung von Sonderzeichen außer einem Unterstrich (_) wird nicht empfohlen. Die folgenden Sonderzeichen sind zulässig: . _ ~ ( ) $ ; / ? : @ = & ' ! * , + -.

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

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

  Hinweis

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

• Versionsnummer: Geben Sie eine optionale Version ein, die als Teil der Service-URL der API verwendet wird. Dieses Feld erlaubt maximal 48 Zeichen und keine Leerzeichen oder bestimmte Sonderzeichen. Die Verwendung von Sonderzeichen außer einem Punkt (.) oder einem Bindestrich (-) wird nicht empfohlen. Gängige Namenskonventionen sind 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 die Registerkarte Profil abgeschlossen haben, klicken Sie auf Weiter, um zur Registerkarte Einstellungen zu wechseln, oder klicken Sie auf Als Entwurf speichern, um Ihren Fortschritt zu speichern.

Registerkarte "Einstellungen"

Die Registerkarte Einstellungen 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 das Zeitlimit überschreitet. Der Standardwert beträgt 30 Sekunden. Der maximal zulässige Wert ist 180 Sekunden.

  Hinweis

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

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

  Warnung

  Wenn diese Option deaktiviert ist, werden Daten, die durch API-Anfragen und -Antworten übertragen werden, nicht verschlüsselt und können von anderen abgefangen und angezeigt werden. Dies könnte möglicherweise vertrauliche Informationen offenlegen.

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

  Warnung

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

• Ausführliches Logging: Aktivieren Sie diese Umschaltfläche, um Rohanfrage- und Antwortdaten – einschließlich Header, Parameter und Text – zum Anrufprotokoll hinzuzufügen, wenn eine API-Anfrage gestellt wird. Diese Daten werden auf der Seite API-Protokolle und auf der Seite Runtime der Management Console für erfolgreiche und erfolglose Ausführungen angezeigt. Das ausführliche Logging generiert keine Studio-Vorgangsprotokolleinträge für erfolgreiche Ausführungen. Um erfolgreiche Vorgangsausführungen in Studio zu protokollieren, verwenden Sie stattdessen Debug-Modus aktivieren bis.

  Warnung

  Ausführliches Logging kann sensible Daten wie Authentifizierungsanmeldedaten oder personenbezogene Informationen enthalten. Werte für maskierte Header werden ausgeblendet, aber Parameter und Text werden vollständig protokolliert. Verwenden Sie diese Einstellung mit Bedacht.

• Debug-Modus aktivieren bis: Aktivieren Sie diesen Schalter, um detailliertes Logging zur Fehlerbehebung zu aktivieren. Klicken Sie dann auf das Kalendersymbol, um ein Datum bis zu zwei Wochen ab heute auszuwählen, an dem sich der Debug-Modus automatisch ausschaltet. Wenn aktiviert, werden Request- und Response-Daten (30 Tage lang gespeichert) auf der Seite API Logs, der Seite Runtime der Management Console und in Studio-Operationsprotokollen für erfolgreiche und erfolglose Ausführungen angezeigt. Das Logging auf Aktivitätsebene wird ebenfalls aktiviert und erfasst Komponenteneingabe- und -ausgabedaten auf der Registerkarte Debug Logging. Diese Einstellung setzt Ausführliches Logging und Request- und Response-Payloads in Logs anzeigen außer Kraft: Wenn der Debug-Modus aktiviert ist, werden Request- und Response-Daten unabhängig davon in Logs aufgenommen, ob diese Einstellungen aktiviert sind.

  Warnung

  Debug-Logs enthalten alle Request- und Response-Daten, einschließlich sensible Informationen wie Passwörter und personenbezogene Informationen (PII). Mit Ausnahme der Werte für maskierte Header werden diese Daten im Klartext in Harmony-Cloud-Logs für 30 Tage angezeigt.

• Request- und Response-Payloads in Logs anzeigen: Aktivieren Sie diesen Schalter, um Request- und Response-Payloads auf der Seite API Logs und der Seite Runtime der Management Console zu erfassen und anzuzeigen, wenn eine API-Anfrage gestellt wird. Die Payloads werden in einer formatierten Ansicht mit separaten Bereichen für Request- und Response-Text für erfolgreiche und erfolglose Ausführungen angezeigt. Diese Einstellung generiert keine Studio-Operationsprotokolleinträge für erfolgreiche Ausführungen. Um erfolgreiche Operationsausführungen in Studio zu protokollieren, verwenden Sie stattdessen Debug-Modus aktivieren bis. Dieser Schalter gilt nur für benutzerdefinierte APIs und OData-Services.

  Warnung

  Request- und Response-Payloads können sensible Daten wie Authentifizierungsanmeldedaten oder personenbezogene Informationen enthalten. Verwenden Sie diese Einstellung mit Bedacht.

Nachdem Sie die Registerkarte Settings konfiguriert haben, klicken Sie auf Next, um zur Registerkarte Services zu wechseln, oder klicken Sie auf Prev, um zur Registerkarte Profile zurückzukehren.

Registerkarte „Services"

Auf der Registerkarte Services konfigurieren Sie die API-Services, die definieren, wie die API auf Anfragen reagiert. Sie können mehrere Services für eine einzelne benutzerdefinierte API konfigurieren. Jeder Service muss eine eindeutige Kombination aus HTTP-Methode und Pfad haben.

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

• Service Name: Geben Sie einen aussagekräftigen Namen für diesen API-Service ein.

• Method: Wählen Sie die HTTP-Methode für diesen Service aus der Dropdown-Liste aus. Verfügbare Methoden sind GET, POST, PUT, DELETE und ALL. Um eine nicht aufgelistete Methode zu verwenden, geben Sie den Methodennamen in das Textfeld Type a new method ein und drücken Sie Enter.

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

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

  • Go to project: Klicken Sie, um ein Studio-Projekt in einer neuen Browser-Registerkarte 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 Service bei Aufruf ausführt.

  Informationen darüber, was in Operationsprotokollen für API-ausgelöste Operationen angezeigt wird und wie Sie zusätzliches Logging aktivieren, finden Sie unter API request and response data in Operation logs.

• Antworttyp: Wählen Sie aus, wie die API die Operationsantwort zurückgibt. Verfügbare Optionen sind Final Target, System Variable und No Response.

  • Final Target: Die API-Antwort ist das finale Ziel der Operationskette. Wenn Sie diesen Antworttyp wählen, muss die ausgewählte Operation als finales Ziel der Operationskette eine Studio-API Response-Aktivität oder Variable Write-Aktivität oder ein Design Studio API Response-Ziel oder Global Variable-Ziel haben. Wenn die Operation ein anderes finales Ziel verwendet, ist die API-Antwort leer.

  • System Variable: Die API-Antwort wird in einer Jitterbit-Variable in der Operationskette gespeichert. Wenn Sie diesen Antworttyp wählen, muss die ausgewählte Operation als Teil der Operationskette ein Skript enthalten, das die Jitterbit-Variable jitterbit.api.response auf die Antwort setzt, die die API zurückgeben soll. Wenn das Skript diese Variable nicht setzt, ist die API-Antwort leer.

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

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

  • API-Service-URL kopieren: Klicken Sie, um die Service-URL der API zu kopieren.
  • Zu API-Service wechseln: Klicken Sie, um eine Übersichtsseite der Konfiguration des benutzerdefinierten API anzuzeigen.
  • Duplizieren: Klicken Sie, um den API-Service zu duplizieren.
  • Löschen: Klicken Sie, um den API-Service zu löschen.

Nach der Konfiguration der grundlegenden Service-Einstellungen können Sie zusätzliche Parameter über die Registerkarten unterhalb der Service-Konfiguration konfigurieren:

Registerkarte „Path params"

Wenn Anfrageparameter im Path enthalten sind, zeigt diese Registerkarte die im Path definierten Parameter an:

• Parameter: Zeigt jeden im Path definierten Anfrageparameter an.

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

Registerkarte „Query params"

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

• Parameter hinzufügen: Klicken Sie, um einen Abfrageparameter zum API-Service 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.

Registerkarte „Headers"

Diese Registerkarte ermöglicht es Ihnen, Anfrage-Header zum API-Service hinzuzufügen:

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

  • Parameter: Geben Sie den Namen des Anfrage-Headers ein.

  • Beschreibung: Geben Sie optional eine Beschreibung für den Anfrage-Header ein.

  • 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 Anfrage-Header, um diesen Header zu löschen.

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

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

Nach der Konfiguration der Registerkarte Services klicken Sie auf Weiter, um zur Registerkarte „Security profiles" zu wechseln, oder klicken Sie auf Zurück, um zur Registerkarte „Settings" zurückzukehren.

Registerkarte „Sicherheitsprofile"

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

Konfiguriere die folgenden Einstellungen:

• Zuweisen: Verwende den Schalter, um Sicherheitsprofile für die API zuzuweisen oder die Zuweisung aufzuheben.

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

• Typ: Der Authentifizierungstyp für das Sicherheitsprofil, z. B. Basic, OAuth 2.0 oder API Key.

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

• Aktionen: Fahre mit der Maus über eine Sicherheitsprofilzeile, um zusätzliche Aktionen anzuzeigen.

  • Zum Sicherheitsprofil gehen: Klicke, um die Konfiguration des Sicherheitsprofils zu öffnen.

Je nach Richtlinien der Harmony-Organisation kann es erforderlich sein, ein Sicherheitsprofil zuzuweisen, um die API zu speichern.

Klicke auf Neues Sicherheitsprofil, um ein neues Sicherheitsprofil zu erstellen. Anweisungen findest du unter Sicherheitsprofile konfigurieren.

Nachdem du die Registerkarte Sicherheitsprofile konfiguriert hast, klicke auf Weiter, um zur Registerkarte „Benutzerrollen" zu wechseln, oder klicke auf Zurück, um zur Registerkarte „Services" zurückzukehren.

Registerkarte „Benutzerrollen"

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

Konfiguriere die folgenden Einstellungen:

• Benutzerrolle: Der Name der Organisationsrolle, wie auf der Registerkarte „Rollen" der Seite „Benutzerverwaltung" definiert.

• Berechtigungen: Die dieser Rolle zugewiesenen Berechtigungen, z. B. Lesen oder Admin.

• Status: Gibt an, ob die Rolle dieser API zugewiesen ist. Schalte den Status um, um Rollen zuzuweisen oder die Zuweisung aufzuheben.

• Aktionen: Fahre mit der Maus über eine Benutzerrollenzeile, um zusätzliche Aktionen anzuzeigen.

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

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

• APIs
• Portal Manager, einschließlich der Generierung von API-Dokumentation
• API Portal
• API-Protokolle
• Analytik

Der Zugriff auf die Seite Sicherheitsprofile und der Zugriff auf die API-Nutzung werden durch diese Auswahl nicht beeinflusst. Der Zugriff auf die Nutzung einer API wird durch Sicherheitsprofile gesteuert.

Alle definierten Benutzerrollen mit der Berechtigung Admin haben immer vollständigen Zugriff auf alle APIs und können daher nicht aus der Auswahl entfernt werden.

Klicke auf Neue Benutzerrolle, um eine neue Benutzerrolle zu erstellen. Anweisungen findest du unter Rollen in Benutzerverwaltung.

Nachdem du die Registerkarte Benutzerrollen konfiguriert hast, klicke auf Veröffentlichen, um die API zu veröffentlichen, oder klicke auf Als Entwurf speichern, um deinen Fortschritt zu speichern.

Optionen zum Speichern und Veröffentlichen

Nachdem du alle erforderlichen Registerkarten konfiguriert hast, kannst du die API speichern oder veröffentlichen:

• Als Entwurf speichern: Speichert die API im Status Entwurf oder Veröffentlicht mit Entwurf. Entwurf-APIs werden nicht auf dein Abonnementlimit für API-URLs angerechnet. 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 wird auf dein Abonnementlimit für API-URLs angerechnet, 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 verfügbar. Eine veröffentlichte API wird auf Ihr Abonnementlimit für API-URLs angerechnet. Ein Dialog zeigt an, dass die API live ist:

  

  Der Dialog bietet diese Optionen:

  • URL kopieren: Kopiert die Service-URL der API in die Zwischenablage.
  • OpenAPI-Dokument generieren: Öffnet die Seite Portal Manager, auf der Sie API-Dokumentation für alle APIs in einer Umgebung generieren können. Um Dokumentation für einzelne APIs zu generieren, verwenden Sie die Registerkarte „Dokumentation" beim Bearbeiten der API auf der Seite APIs.
  • Schließen: Schließt den Dialog.

API bearbeiten

Nach dem Speichern der API können Sie diese von diesen Orten aus bearbeiten:

• Verwenden Sie die Kartenansicht auf der Seite APIs und klicken Sie auf die Karte.
• Verwenden Sie die Listenansicht auf der Seite APIs und klicken Sie in der Spalte Aktionen auf Bearbeiten.

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