Proxy-API-Konfiguration in Jitterbit API Manager

Einführung

Diese Seite beschreibt, wie man eine Proxy-API auf der Seite APIs von Jitterbit API Manager erstellt und konfiguriert. Eine Proxy-API ist einer der drei API-Typen, die über API Manager konfiguriert werden. Für die beiden anderen Typen, Custom API und OData-Service, siehe Custom-API-Konfiguration und OData-Service-Konfiguration.

Alternativ können OData-Services mit dem APIM AI Assistant erstellt werden.

Voraussetzungen

Im Gegensatz zu einer Custom API oder einem OData-Service, die einen Harmony-Vorgang zur Nutzung bereitstellen, wird eine Proxy-API mit einer vorhandenen API verwendet. Proxy-APIs werden nicht über Jitterbit-Agenten weitergeleitet. Das Gateway, das die API verarbeitet, muss auf die zu proxierende API zugreifen können:

• Cloud-API-Gateway: Bei Verwendung des Cloud-API-Gateways (gehostet von Jitterbit) muss die vorhandene API öffentlich zugänglich sein, auch wenn sie gesichert ist. Die API, die proxiert werden soll, darf sich nicht hinter einer Firewall befinden. Um die IP-Adressen des Cloud-API-Gateways auf die Whitelist zu setzen und dem Gateway den Zugriff auf die zu proxierende API zu ermöglichen, siehe Whitelist-Informationen und navigieren Sie zu https://services.jitterbit für Ihre Region.

• Private API Gateway: Bei Verwendung eines Private API Gateways (gehostet in einem privaten Netzwerk) muss das Private API Gateway auf die vorhandene API zugreifen können.

Obwohl jede Proxy-API mehrere Services einer eindeutigen URL zuordnen kann, verbraucht die Basis-Proxy-URL die Berechtigung.

Neue Proxy-API erstellen

Um eine neue Proxy-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.

• Proxy-API: Öffnet den Konfigurationsbildschirm der Proxy-API, um manuell eine neue Proxy-API zu erstellen. Diese Option ist nur aktiviert, wenn eine entsprechende API-URL verfügbar ist.

Proxy-API konfigurieren

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

• Registerkarte „Profil" (erforderlich)
• Registerkarte „Einstellungen" (optional)
• Registerkarte „Vorhandene API" (erforderlich)
• Registerkarte „Services" (erforderlich)
• Registerkarte „Sicherheitsprofile" (optional)
• Registerkarte „Request-Header" (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 Proxy-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 Proxy-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 einen beliebigen 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 kann die Umgebung nicht mehr 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.

• 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 umfassen 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 wechseln, oder klicken Sie auf Save as draft, um Ihren Fortschritt zu speichern.

Registerkarte „Settings"

Die Registerkarte Settings 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, nach denen 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 Operationen in Studio oder Design Studio. Timeout-Einstellungen für Operationen werden nicht verwendet, es sei denn, die Einstellung EnableAPITimeout in der Konfigurationsdatei des privaten Agenten ist aktiviert.

• Nur SSL: Dieser Schalter 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 durch 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 Schalter, um CORS (Cross-Origin Resource Sharing) zu unterstützen. CORS ist ein Mechanismus, der es Webanwendungen, die in einem Webbrowser auf einer Domäne ausgeführt werden, ermöglicht, auf Ressourcen von einem Server auf einer anderen Domäne zuzugreifen.

  Warnung

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

• Ausführliches Logging: Aktivieren Sie diesen Schalter, 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-Operationsprotokolle für erfolgreiche Ausführungen. Um erfolgreiche Operationsausführungen in Studio zu protokollieren, verwenden Sie stattdessen Enable debug mode until.

  Warnung

  Das ausführliche Logging kann sensible Daten wie Authentifizierungsanmeldedaten oder persönlich identifizierbare Informationen enthalten. Werte für maskierte Header sind verborgen, 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 einzuschalten. Klicken Sie dann auf das Kalendersymbol, um ein Datum auszuwählen, das bis zu zwei Wochen ab heute liegt. Der Debug-Modus wird dann automatisch deaktiviert. Bei Aktivierung werden Request- und Response-Daten (30 Tage lang gespeichert) auf der Seite API-Protokolle, auf der Seite Laufzeit 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 außer Kraft: Wenn der Debug-Modus aktiviert ist, werden Request- und Response-Daten in Protokolle aufgenommen, unabhängig davon, ob Ausführliches Logging aktiviert ist.

  Warnung

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

• Request- und Response-Payloads in Protokollen anzeigen: Dieser Schalter ist in den Proxy-API-Einstellungen sichtbar, hat aber keine Auswirkung. Das Logging von Request- und Response-Payloads wird für Proxy-APIs nicht unterstützt.

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

Registerkarte „Vorhandene API"

Verwenden Sie die Registerkarte Vorhandene API, um die Basis-URL der API anzugeben, die Sie als Proxy verwenden möchten, und stellen Sie optional ein OpenAPI-Dokument für die automatische Dienstermittlung bereit.

Konfigurieren Sie die folgenden Einstellungen:

• Basis-API-URL: Geben Sie die Basis-URL der API ein, die als Proxy verwendet werden soll.

  Hinweis

  Wenn die API einen einzelnen Dienst bereitstellt, können Sie die vollständige API-URL einschließlich des Dienstpfads eingeben. Zusätzliche Dienstpfade werden auf der Registerkarte Dienste definiert.

• OpenAPI-Dokument bereitstellen: Wenn Sie ein OpenAPI-Dokument bereitstellen, verwendet API Manager dieses zur automatischen Ermittlung der API-Dienste. Wählen Sie Nein, um zu überspringen, oder Ja, um einen zusätzlichen Bereich zur Bereitstellung des OpenAPI-Dokuments zu erweitern:

  

  • URL laden: Öffnet ein Dialogfeld zum Laden eines OpenAPI-Dokuments im YAML- oder JSON-Format von einer URL:

    

  • Datei hochladen: Öffnet ein Dialogfeld zum Hochladen eines OpenAPI-Dokuments im YAML- oder JSON-Format, nachdem Sie mit Durchsuchen die Datei ausgewählt haben:

    

  • Löschen: Löscht ein bereits bereitgestelltes OpenAPI-Dokument und ändert die Auswahl OpenAPI-Dokument bereitstellen zu Nein. Ein Bestätigungsdialogfeld Editor-Inhalte löschen wird angezeigt und fordert Sie auf, vor dem Entfernen des Dokuments zu bestätigen. Das Löschen des Dokuments entfernt auch alle Dienste, die automatisch daraus ermittelt wurden (siehe Automatische Ermittlung von OpenAPI-Dokumenten), wirkt sich aber nicht auf manuell hinzugefügte Dienste oder andere API-Einstellungen aus. Das Löschen des Dokuments wird als ungespeicherte Änderung behandelt, bis Sie die API-Konfiguration speichern.

  • Dokument-Editor: Ermöglicht das Anzeigen und Bearbeiten eines bereitgestellten OpenAPI-Dokuments. Sie können auch ein OpenAPI-Dokument bereitstellen, indem Sie es hier direkt eingeben. Um das OpenAPI-Dokument in einem größeren Bereich anzuzeigen und zu bearbeiten, klicken Sie auf das Popout-Symbol. Nachdem Sie diesen Bereich geöffnet haben, klicken Sie auf das Rückgabesymbol, um zu diesem Bildschirm zurückzukehren.

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

Services-Tab

Verwenden Sie die Services-Tab, um die Services und HTTP-Methoden zu definieren, die die Proxy-API verfügbar macht. Die Art und Weise, wie Sie Services definieren, hängt davon ab, ob Sie ein OpenAPI-Dokument auf der Registerkarte „Existing API" bereitgestellt haben.

Manuelle Service-Definition

Wenn Sie kein OpenAPI-Dokument bereitgestellt haben, müssen Sie Services und Methoden manuell definieren:

Klicken Sie auf New Service, um einen Service hinzuzufügen. Konfigurieren Sie die folgenden Einstellungen:

• Service Name: Geben Sie einen Namen ein, um den Service zu identifizieren.

• Path: Geben Sie einen Pfad für den Service ein. Wenn die API keinen Service-Pfad hat, geben Sie einen Schrägstrich (/) ein.

  Hinweis

  Bei der manuellen Definition von Services können Sie keine Zeichen wie geschweifte Klammern ({ }) in einem Service-Pfad verwenden. Um nicht zulässige Zeichen in einem Service-Pfad zu verwenden, stellen Sie stattdessen ein OpenAPI-Dokument bereit, das den Pfad auf der Registerkarte „Existing API" definiert.

• Methods: Wählen Sie jede Methode aus, die für den Service erstellt werden soll. Verfügbare Methoden sind GET, PUT, POST und DELETE. Um eine nicht aufgelistete Methode zu verwenden, geben Sie den Methodennamen in das Textfeld Type a new method ein und drücken Sie Enter.

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

  • Copy API service URL: Klicken Sie, um die Service-URL der API zu kopieren.
  • Duplicate: Klicken Sie, um den Service zu duplizieren.
  • Delete: Klicken Sie, um den Service zu löschen.

Sie müssen mindestens einen Service hinzufügen, um zur nächsten Registerkarte zu gelangen.

OpenAPI-Dokument-Autodiscovery

Wenn Sie ein OpenAPI-Dokument auf der Registerkarte „Existing API" bereitgestellt haben, erkennt API Manager Services automatisch und listet sie in einer Tabelle auf:

• Assign: Verwenden Sie den Schalter, um die Services zur Proxy-API hinzuzufügen.
• Service Name: Der Name, der zur Identifizierung des Service verwendet wird.
• Methods: Die HTTP-Methode, die für den Service gilt.
• Path: Der Pfad des Service.

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

  • Copy API service URL: Klicken Sie, um die Service-URL der API zu kopieren.
  • Go to API Service: Klicken Sie, um die API in einer Assistenten-Oberfläche zu konfigurieren.

Nachdem Sie die Services-Tab konfiguriert haben, klicken Sie auf Next, um zur Registerkarte „Security profiles" zu gelangen, oder klicken Sie auf Prev, um zur Registerkarte „Existing API" zurückzukehren.

Security profiles-Tab

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

Konfigurieren Sie die folgenden Einstellungen:

• Assign: Verwenden Sie den Schalter, um Sicherheitsprofile für die API zuzuweisen oder die Zuweisung aufzuheben.

• Profile Name: Der Name des Sicherheitsprofils, wie in Security Profiles konfiguriert.

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

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

• Actions: Bewegen Sie den Mauszeiger über eine Sicherheitsprofilzeile, um zusätzliche Aktionen anzuzeigen.

  • Go to security profile: 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.

Nachdem Sie die Registerkarte Sicherheitsprofile konfiguriert haben, klicken Sie auf Weiter, um zur Registerkarte „Anforderungsheader" zu wechseln, oder klicken Sie auf Zurück, um zur Registerkarte „Services" zurückzukehren.

Registerkarte „Anforderungsheader"

Die Registerkarte Anforderungsheader ist optional und ermöglicht es Ihnen, neue Anforderungsheader hinzuzufügen oder vorhandene Anforderungsheader zu überschreiben.

Klicken Sie auf Neuer Header, um einen Anforderungsheader hinzuzufügen. Konfigurieren Sie die folgenden Einstellungen:

• Schlüssel: Geben Sie einen Schlüssel für den Anforderungsheader ein.

• Wert: Geben Sie einen Wert für den Anforderungsheader ein. Der Wert darf nur Buchstaben, Zahlen, Leerzeichen und Satzzeichen enthalten, keine führenden oder nachfolgenden Leerzeichen und darf 8192 Zeichen nicht überschreiten. Dies ermöglicht Werte wie JSON Web Tokens (JWTs), die Punkte (.) als Teil ihres Formats erfordern.

• Eingehende überschreiben: Aktivieren Sie diesen Schalter, um einen vorhandenen Anforderungsheader mit demselben Schlüssel zu überschreiben. Die Standardeinstellung ist deaktiviert.

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

  • Löschen: Klicken Sie, um den Anforderungsheader zu löschen.

Nachdem Sie die Registerkarte Anforderungsheader 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 werden nicht auf Ihr Proxy-URL-Abonnementlimit 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 Ihr Proxy-URL-Abonnementlimit 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 zugänglich. Eine veröffentlichte API wird auf Ihr Proxy-URL-Abonnementlimit angerechnet. Ein Dialogfeld zeigt an, dass die API live ist:

  

  Das Dialogfeld bietet diese Optionen:

  • URL kopieren: Kopiert die Service-URL der API in Ihre Zwischenablage.
  • Schließen: Schließt das Dialogfeld.

API bearbeiten

Nach dem Speichern der API können Sie diese von folgenden 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.

Fehlerbehebung

Weitere Informationen zur Fehlerbehebung finden Sie in den folgenden Abschnitten im Leitfaden zur Fehlerbehebung in API Manager:

• Proxy-API: Servicepfad-Parameter erfordern ein OpenAPI-Dokument

• Cloud-Proxy-API: Ziel-API muss öffentlich zugänglich sein

• Proxy API: Bindestriche in Request-Headern durch Unterstriche ersetzt

• Einstellung „Show Request & Response Payloads" hat keine Auswirkung auf Proxy-APIs