Benutzerdefinierte API-Konfiguration in Jitterbit API Manager

Einführung

Diese Seite beschreibt, wie Sie eine benutzerdefinierte API über die Seite APIs von Jitterbit API Manager erstellen und konfigurieren. Benutzerdefinierte APIs sind einer der drei API-Typen, die über API Manager konfiguriert werden können. Für die beiden anderen Typen – OData-Service und Proxy-API – finden Sie unter OData-Service-Konfiguration und Proxy-API-Konfiguration weitere Informationen.

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

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

• Die Seite APIs von API Manager.
• Die Registerkarte Ressourcen im Projektbereich für das Studio-Projekt der benutzerdefinierten API.

Voraussetzungen

Eine benutzerdefinierte API stellt eine Harmony-Operation zur Verfügung. Sie müssen diese Operation zunächst 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.

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

• Studio
  • Operation erstellen und konfigurieren
  • Operation bereitstellen und ausführen
• Design Studio
  • Operation erstellen

Neue benutzerdefinierte API erstellen

Wenn Sie die Seite APIs von API Manager öffnen und keine benutzerdefinierten APIs, OData-Services 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 Assistant, um eine API mit natürlichsprachigen Eingabeaufforderungen zu erstellen. Weitere Informationen finden Sie unter Verwende den AI-Assistenten.

  Hinweis

  Um den APIM AI Assistant zu verwenden, muss Ihre 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 eine neue benutzerdefinierte API manuell zu erstellen. Diese Option ist nur aktiviert, wenn eine entsprechende API-URL verfügbar ist.

Benutzerdefinierte API konfigurieren

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

• Registerkarte Profil (erforderlich)
• Registerkarte Einstellungen (optional)
• Registerkarte Dienste (erforderlich)
• Registerkarte Sicherheitsprofile (optional)
• Registerkarte Benutzerrollen (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 API-Service-URL verwendet wird. Standardmäßig wird dieses Feld mit dem API-Namen in Camel Case ausgefüllt. Dieses Feld erlaubt keine Leerzeichen oder bestimmte Sonderzeichen. Die Verwendung von Sonderzeichen außer 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 in Echtzeit bei jedem Tastendruck gefiltert.

  Hinweis

  Nach der API-Erstellung kann die Umgebung nicht geändert werden. Um eine API zwischen Umgebungen zu verschieben, können Sie die API klonen oder die API exportieren und importieren in einer anderen Umgebung. Beim Export können Sie die Studio-Projekte einbeziehen, die von den Services der API verwendet werden.

• Versionsnummer: Geben Sie eine optionale Versionsnummer ein, die als Teil der API-Service-URL verwendet wird. Dieses Feld erlaubt maximal 48 Zeichen und keine Leerzeichen oder bestimmte Sonderzeichen. Die Verwendung von Sonderzeichen außer Punkt (.) oder Bindestrich (-) wird nicht empfohlen. Zu den gängigen Namenskonventionen gehören inkrementelle Versionen wie v1.0, v1.1, v1.2 oder ein Datum, an dem die API veröffentlicht wurde, wie 2025-08-28.

Nachdem Sie die Registerkarte Profile abgeschlossen haben, klicken Sie auf Next, um zur Registerkarte Settings zu gelangen, oder klicken Sie auf Save as draft, um Ihren Fortschritt zu speichern.

Settings tab

Die Registerkarte Settings ist optional und enthält erweiterte Konfigurationsoptionen für die API.

Konfigurieren Sie die folgenden Einstellungen je nach Bedarf:

• Timeout: Geben Sie die Anzahl der Sekunden ein, bevor die API-Zeitüberschreitung erfolgt. Der Standardwert ist 30 Sekunden. Der maximal zulässige Wert ist 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 nur verwendet, wenn ein Private Agent verwendet wird und die Einstellung EnableAPITimeout in der Private-Agent-Konfigurationsdatei aktiviert ist.

• SSL only: Dieser Toggle ist standardmäßig aktiviert und erfordert HTTPS für die API. Wenn aktiviert, werden Daten durch 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, werden Daten, die über API-Anfragen und -Antworten übertragen werden, nicht verschlüsselt und können von anderen abgefangen und angezeigt werden. Dies könnte möglicherweise sensible Informationen offenlegen.

• CORS: Aktivieren Sie diesen Toggle, 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 mit der Methode OPTIONS ohne Authentifizierung ausgeführt werden.

• Verbose logging: Aktivieren Sie diesen Toggle, um unformatierte Anfrage- und Antwortdaten – einschließlich Header, Parameter und Body – zum Aufrufprotokoll hinzuzufügen, wenn eine API-Anfrage gestellt wird. Diese Daten erscheinen auf der Seite API Logs und auf der Seite Runtime der Verwaltungskonsole für erfolgreiche und fehlerhafte Ausführungen. Verbose Logging generiert keine Studio-Operationsprotokolle für erfolgreiche Ausführungen. Um erfolgreiche Operationsausführungen in Studio zu protokollieren, verwenden Sie stattdessen Enable debug mode until.

  Warnung

  Ausführliches Logging kann vertrauliche Daten wie Authentifizierungsdaten oder persönlich identifizierbare Informationen enthalten. Werte für maskierte Header werden ausgeblendet, aber Parameter und Bodies werden vollständig protokolliert. Verwenden Sie diese Einstellung mit Vorsicht.

• Debug-Modus aktivieren bis: Aktivieren Sie diesen Schalter, um detailliertes Logging zur Fehlerbehebung 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, werden Request- und Response-Daten (werden 30 Tage lang gespeichert) auf der Seite API Logs, auf der Seite Runtime der Management Console und in Studio-Operationslogs für erfolgreiche und nicht erfolgreiche Ausführungen angezeigt. Das Debug-Logging auf Aktivitätsebene ist auch aktiviert und erfasst Komponenteneingabe- und Ausgabedaten auf der Registerkarte Debug Logging. Diese Einstellung überschreibt Ausführliches Logging und Request- und Response-Payloads in Logs anzeigen: 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 vertraulicher Informationen wie Passwörter und persönlich identifizierbare Informationen (PII). Mit Ausnahme der Werte für maskierte Header werden diese Daten in Harmony Cloud-Logs 30 Tage lang im Klartext angezeigt.

• Request- und Response-Payloads in Logs anzeigen: Aktivieren Sie diesen Schalter, um Request- und Response-Payloads auf der Seite API Logs und auf 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 die Request- und Response-Bodies für erfolgreiche und nicht erfolgreiche Ausführungen angezeigt. Diese Einstellung generiert keine Studio-Operationslogs 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 vertrauliche Daten wie Authentifizierungsdaten oder persönlich identifizierbare Informationen enthalten. Verwenden Sie diese Einstellung mit Vorsicht.

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.

Services tab

Auf der Registerkarte Services konfigurieren Sie die API-Services, die definieren, wie die API auf Anfragen antwortet. 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 beschreibenden 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 die 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. Um eine benutzerdefinierte API zusammen mit ihren Studio-Projekten zu migrieren, siehe Include linked Studio projects.

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

• Auszulösender Betrieb: Wählen Sie den spezifischen Betrieb aus dem gewählten Projekt aus, den dieser Service beim Aufrufen ausführt.

  Informationen darüber, was in Betriebsprotokollen für API-ausgelöste Betriebe angezeigt wird und wie Sie zusätzliche Protokollierung aktivieren, finden Sie unter API-Anfrage- und Antwortdaten in Betriebsprotokolle.

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

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

  • System Variable: Die API-Antwort wird in einer Jitterbit-Variable in der Betriebskette festgelegt. Wenn Sie diesen Antworttyp wählen, muss der ausgewählte Betrieb als Teil der Betriebskette ein Skript haben, 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. Falls die Anfrage zur Ausführung des ausgewählten Betriebs akzeptiert wird, gibt die API sofort eine leere Antwort mit HTTP-Code 202 zurück.

• Aktionen: Bewegen Sie den Mauszeiger über eine Service-Zeile, um zusätzliche Aktionen einzublenden.

  • API-Service-URL kopieren: Klicken Sie, um die Service-URL der API zu kopieren.
  • Zum Betrieb gehen: Klicken Sie, um das Studio-Projekt in einem neuen Browser-Tab zu öffnen. Der Betrieb im Feld Auszulösender Betrieb ist auf der Design Canvas von Studio hervorgehoben. Diese Aktion ist für Design Studio-Betriebe deaktiviert.
  • 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 unter der Service-Konfiguration konfigurieren:

Registerkarte „Path params"

Wenn Anfrageparameter in den Path eingebunden sind, werden auf dieser Registerkarte die im Path definierten Parameter angezeigt:

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

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

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 „Sicherheitsprofile" zu wechseln, oder klicken Sie auf Zurück, um zur Registerkarte „Einstellungen" zurückzukehren.

Registerkarte „Sicherheitsprofile"

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

Konfigurieren Sie die folgenden Einstellungen:

• Zuweisen: Verwenden Sie den Umschalter, 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-Schlüssel.

• Benutzername: Für die Standardauthentifizierung wird der Benutzername angezeigt. Für andere Authentifizierungstypen wird der gleiche Wert wie in der Spalte Typ angezeigt.

• Aktionen: Zeigen Sie auf eine Sicherheitsprofilzeile, um zusätzliche Aktionen anzuzeigen.

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

Je nach 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. Anweisungen finden Sie unter Sicherheitsprofile konfigurieren.

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

Registerkarte „Benutzerrollen"

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

Konfigurieren Sie 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. Schalten Sie den Status um, um Rollen zuzuweisen oder die Zuweisung aufzuheben.

• Aktionen: Zeigen Sie auf eine Benutzerrollenzeile, um zusätzliche Aktionen anzuzeigen.

  • Zur Benutzerrolle: Klicken Sie, 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
• Analyse

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 kontrolliert.

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.

Klicken Sie auf Neue Benutzerrolle, um eine neue Benutzerrolle zu erstellen. Anweisungen finden Sie unter 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.

Speicher- und Veröffentlichungsoptionen

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 werden nicht auf das Kontingent für API-URLs angerechnet. Eine API, deren Status zum Zeitpunkt der Verwendung von Als Entwurf speichern auf Veröffentlicht gesetzt war, wird als Veröffentlicht mit Entwurf gespeichert. Eine veröffentlichte API wird auf das Kontingent für API-URLs angerechnet, obwohl der zugehörige 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 das Kontingent für API-URLs angerechnet. Ein Dialogfeld zeigt an, dass die API live ist:

  

  Das Dialogfeld 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 das Dialogfeld.

API bearbeiten

Nach dem Speichern der API können Sie diese an folgenden Orten 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 auf Bearbeiten in der Spalte Aktionen.

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.