OData-Servicekonfiguration in Jitterbit API Manager

Einführung

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

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

OData-Services (veröffentlicht und Entwurf) werden an diesen Orten angezeigt:

• Die Seite APIs des API Manager.
• Die Registerkarte Ressourcen im Projektbereich für das Design-Studio-Projekt, das dem OData-Service zugeordnet ist.

Voraussetzungen

Ein OData-Service macht eine Jitterbit-iPaaS-API-Entity-Operation zur Nutzung verfügbar. Sie müssen diese Operation zunächst erstellen und bereitstellen, bevor Sie den OData-Service konfigurieren können. Die Operation, die ein OData-Service auslöst, muss eine Design-Studio-API-Entity-Operation sein.

Informationen zum Erstellen und Bereitstellen einer API-Entity-Operation in Design Studio finden Sie in diesen Ressourcen:

• Design-Studio-Schnellstartanleitung
• Jitterbit-Entity erstellen
• API-Entity-Operation erstellen

Neuen OData-Service erstellen

Um einen neuen OData-Service 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 Ihre Harmony-Lizenz die Option APIM AI Assistant enthalten. Kontaktieren Sie Ihren Customer Success Manager (CSM), um diese Option zu Ihrer Lizenz hinzuzufügen.

• OData-Service: Öffnet den Konfigurationsbildschirm des OData-Service, um manuell einen neuen OData-Service zu erstellen. Diese Option ist nur aktiviert, wenn eine entsprechende API-URL verfügbar ist.

OData-Service konfigurieren

Wenn Sie einen OData-Service 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 „Services" (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 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 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 in Echtzeit bei jedem Tastendruck 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 werden soll. 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 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, 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, ein privater Agent wird verwendet und 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 rohe Anfrage- und Antwortdaten – einschließlich Header, Parameter und Bodies – 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. Ausführliches Logging generiert keine Studio-Operationsprotokolle für erfolgreiche Ausführungen. Um erfolgreiche Operationsausführungen in Studio zu protokollieren, verwenden Sie stattdessen Debug-Modus aktivieren bis.

  Warnung

  Ausführliches Logging kann sensible Daten wie Authentifizierungsanmeldedaten oder persönlich identifizierbare Informationen enthalten. Werte für maskierte Header sind verborgen, aber Parameter und Bodies 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, und klicken Sie dann auf das Kalendersymbol, um ein Datum auszuwählen, das bis zu zwei Wochen ab heute liegt, wenn der Debug-Modus automatisch deaktiviert wird. Wenn aktiviert, werden Anfrage- und Antwortdaten (30 Tage lang gespeichert) auf der Seite API-Protokolle, der Seite Runtime der Management Console und Studio-Operationsprotokollen für erfolgreiche und erfolglose Ausführungen angezeigt. Das Debug-Logging auf Aktivitätsebene ist ebenfalls aktiviert und erfasst Komponenteneingabe- und -ausgabedaten auf der Registerkarte Debug-Logging. Diese Einstellung setzt Ausführliches Logging und Anfrage- und Antwort-Payloads in Protokollen anzeigen außer Kraft: Wenn der Debug-Modus aktiviert ist, werden Anfrage- und Antwortdaten unabhängig davon in Protokolle aufgenommen, ob diese Einstellungen aktiviert sind.

• Anfrage- und Antwort-Payloads in Protokollen anzeigen: Aktivieren Sie diesen Schalter, um Anfrage- und Antwort-Payloads auf der Seite API-Protokolle und der Seite Laufzeit der Verwaltungskonsole zu erfassen und anzuzeigen, wenn eine API-Anfrage gestellt wird. Die Payloads werden in einer formatierten Ansicht mit separaten Bereichen für die Anfrage- und Antworttexte angezeigt, sowohl für erfolgreiche als auch für fehlgeschlagene Ausführungen. Diese Einstellung generiert keine Studio-Operationsprotokolle 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

  Anfrage- und Antwort-Payloads können vertrauliche Daten wie Authentifizierungsdaten oder personenbezogene Daten enthalten. Verwenden Sie diese Einstellung mit Bedacht.

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

Registerkarte Services

Die Registerkarte Services ist der Ort, an dem Sie die API-Services konfigurieren, die definieren, wie die API auf Anfragen reagiert. Für OData-Services weisen Sie Jitterbit-Entity-Operationen zu, die Daten über das OData-Protokoll verfügbar machen.

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

• Entity: Wählen Sie aus den bereitgestellten Projekten aus, die eine Design Studio API-Entity-Operation in der Umgebung enthalten, in der Sie die API konfigurieren. Der Entity-Name entspricht dem Projektnamen in Design Studio.

• Projekt: Zeigt den Design Studio-Projektnamen an, der die ausgewählte Entity enthält.

• Operation: Wählen Sie aus den bereitgestellten Design Studio API-Entity-Operationen in der ausgewählten Entity. Es kann nur eine Operation mit jeder Methode zugewiesen werden.

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

• Methode: Wählen Sie die HTTP-Methode aus, die für die ausgewählte Operation erstellt werden soll. Verfügbare Methoden sind GET, PUT, POST, DELETE, PATCH, MERGE oder ALL. Wenn Sie ALL auswählen, werden separate GET-, PUT-, POST-, DELETE-, PATCH- und MERGE-Methoden für die ausgewählte Operation erstellt. Um eine nicht aufgelistete Methode zu verwenden, geben Sie den Methodennamen in das Textfeld Neue Methode eingeben ein und drücken Sie Enter.

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

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

Sie können mehrere Services für einen einzelnen OData-Service konfigurieren. Sie müssen mindestens eine Entity hinzufügen, um zur nächsten Registerkarte zu wechseln.

Nachdem Sie die Registerkarte Services konfiguriert haben, 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 Nutzung der API einzuschränken.

Konfigurieren Sie die folgenden Einstellungen:

• Zuweisen: Verwenden Sie 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: Bewegen Sie den Mauszeiger über eine Sicherheitsprofilzeile, um zusätzliche Aktionen anzuzeigen.

  • Zum Sicherheitsprofil wechseln: 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 „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 im 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 Administrator.

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

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

  • Zur Benutzerrolle wechseln: 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 Generierung von API-Dokumentation
• API Portal
• API-Protokolle
• Analytics

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

Alle definierten Benutzerrollen mit der Berechtigung Administrator haben immer vollständigen Zugriff auf alle APIs und können daher nicht aus der Auswahl gelöscht 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.

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 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 Ihr Abonnementlimit für API-URLs angerechnet, auch wenn ihr Entwurf nicht zugänglich ist.

• Publish: Speichert die API im Status Published. Die API ist live und innerhalb von fünf Minuten verfügbar. Eine veröffentlichte API wird auf das Abonnementlimit für API-URLs angerechnet. Ein Dialog zeigt an, dass die API live ist:

  

  Der Dialog bietet diese Optionen:

  • Copy URL: Kopiert die Service-URL der API in die Zwischenablage.
  • Generate OpenAPI Document: Öffnet die Seite Portal Manager. Um Dokumentation für einzelne APIs zu generieren, verwenden Sie die Registerkarte „Documentation" beim Bearbeiten der API auf der Seite APIs.
  • Close: Schließt den Dialog.

OData-Abfrageparameter

Sie können die zurückgegebenen Daten filtern, indem Sie OData-Abfrageparameter an die Service-URL eines OData-Dienstes anhängen. Die unterstützten Abfrageparameter hängen von der zugrunde liegenden Datenbank ab.

Häufige OData-Abfrageparameter sind:

https://jbexample.jitterbit.net/Sandbox/customers?$top=10&$orderby=name

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 Actions auf Edit.

Beim Bearbeiten einer veröffentlichten API aus der Listenansicht ist auch eine Registerkarte Documentation 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 „Documentation" auf der Seite APIs.

Fehlerbehebung

Weitere Informationen zur Fehlerbehebung finden Sie in folgendem Abschnitt im API Manager-Fehlerbehebungsleitfaden:

• OData $count oder $inlinecount gibt einen Fehler zurück, wenn keine Datensätze übereinstimmen