OData-Service-Konfiguration 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 den 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-KI-Assistenten 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 stellt einen Jitterbit-iPaaS-API-Entity-Vorgang zur Nutzung bereit. Sie müssen diesen Vorgang zunächst erstellen und bereitstellen, bevor Sie den OData-Service konfigurieren können. Der Vorgang, den ein OData-Service auslöst, muss ein Design-Studio-API-Entity-Vorgang sein.

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

• Design-Studio-Schnellstartanleitung
• Erstellen einer Jitterbit-Entity
• Erstellen eines API-Entity-Vorgangs

Erstellen eines neuen OData-Service

Klicken Sie auf Neu, um einen neuen OData-Service zu erstellen, und wählen Sie eine der folgenden Optionen:

• Mit KI erstellen: Öffnet den APIM-Assistenten, um eine API mit natürlichsprachigen Eingaben zu erstellen. Weitere Informationen finden Sie unter Verwenden 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.

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

Konfigurieren eines OData-Service

Wenn Sie einen OData-Service manuell konfigurieren, umfasst der Konfigurationsbildschirm mehrere Registerkarten. Der Konfigurationsbildschirm enthält 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 zu Identifikationszwecken intern 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 camelCase konvertiert wurde. 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: Wählen Sie über das Menü die Umgebung aus, 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 mehr ändern. Um eine API zwischen Umgebungen zu verschieben, können Sie die API klonen oder exportieren und importieren Sie die API in einer anderen Umgebung.

• Versionsnummer: Geben Sie optional eine 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 Benennungskonventionen umfassen inkrementelle Versionen wie v1.0, v1.1, v1.2 oder ein Datum, an dem die API veröffentlicht wurde, z. B. 2025-08-28.

Klicken Sie nach Abschluss der Registerkarte Profil auf Weiter, um zur Registerkarte Einstellungen zu wechseln, oder klicken Sie auf Als Entwurf speichern, um Ihre Änderungen 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 abläuft. 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. Die Timeout-Einstellungen für Vorgänge werden nur verwendet, wenn ein privater Agent verwendet wird und die Einstellung EnableAPITimeout in der Konfigurationsdatei des privaten Agents aktiviert ist.

• Nur SSL: Dieser Schalter 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 weitergeleitet werden, nicht verschlüsselt und können von anderen abgefangen und angezeigt werden. Dies könnte möglicherweise zu einer Offenlegung vertraulicher Informationen führen.

• CORS: Aktivieren Sie diesen Schalter, um CORS (Cross-Origin Resource Sharing) zu unterstützen. CORS ist ein Mechanismus, der es Web-Anwendungen, 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

  Durch das Aktivieren von CORS werden Vorgänge mit der Methode OPTIONS ohne Authentifizierung ausgeführt.

• Ausführliches Logging: Aktivieren Sie diesen Schalter, um Rohanfrage- und Antwortdaten – einschließlich Header, Parameter und Textkörper – zum Anrufprotokoll hinzuzufügen, wenn eine API-Anfrage gestellt wird. Diese Daten erscheinen auf der Seite API-Protokolle und der Seite Runtime der Management Console für erfolgreiche und erfolglose Ausführungen. Die ausführliche Protokollierung generiert keine Studio-Vorgangsprotokolle für erfolgreiche Ausführungen. Um erfolgreiche Vorgänge in Studio zu protokollieren, verwenden Sie stattdessen Debugmodus aktivieren bis.

  Warnung

  Die ausführliche Protokollierung kann vertrauliche Daten wie Authentifizierungsdaten oder personenbezogene Informationen enthalten. Werte für maskierte Header sind ausgeblendet, aber Parameter und Textkörper werden vollständig protokolliert. Verwenden Sie diese Einstellung mit Bedacht.

• Debugmodus 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 Debugmodus automatisch deaktiviert wird. Wenn dieser aktiviert ist, erscheinen Anfrage- und Antwortdaten (behalten für 30 Tage) auf der Seite API-Protokolle, der Seite Runtime der Management Console und Studio-Vorgangsprotokolle für erfolgreiche und erfolglose Ausführungen. 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 & Response Payloads in Logs anzeigen außer Kraft: Wenn der Debugmodus aktiviert ist, werden Anfrage- und Antwortdaten unabhängig davon in Protokollen einbezogen, ob diese Einstellungen aktiviert sind.

  Warnung

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

• Anfrage- und Antwort-Payloads in Protokollen anzeigen: Aktivieren Sie diese Umschaltfläche, um Anfrage- und Antwort-Payloads auf der Seite API-Protokolle und der Seite Runtime der Management Console zu erfassen und anzuzeigen, wenn eine API-Anfrage erfolgt. Die Payloads werden in einer formatierten Ansicht mit separaten Bereichen für Anfrage- und Antworttexte angezeigt, sowohl für erfolgreiche als auch für erfolglose Ausführungen. Diese Einstellung generiert für erfolgreiche Ausführungen keine Studio-Operationsprotokolle. Um erfolgreiche Operationsausführungen in Studio zu protokollieren, verwenden Sie stattdessen Debug-Modus aktivieren bis. Diese Umschaltfläche gilt nur für benutzerdefinierte APIs und OData-Services.

  Warnung

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

Klicken Sie nach der Konfiguration der Registerkarte Einstellungen 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-Entitätsvorgänge 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:

• Entität: Wählen Sie aus den bereitgestellten Projekten aus, die einen API-Entitätsvorgang von Design Studio in der Umgebung enthalten, in der Sie die API konfigurieren. Der Entitätsname entspricht dem Projektnamen in Design Studio.

• Projekt: Zeigt den Namen des Design Studio-Projekts an, das die ausgewählte Entität enthält.

• Vorgang: Wählen Sie aus den bereitgestellten API-Entitätsvorgängen von Design Studio in der ausgewählten Entität aus. Pro Methode kann nur ein Vorgang zugewiesen werden.

  Informationen darüber, was in Vorgangsprotokollen für API-ausgelöste Vorgänge angezeigt wird und wie zusätzliche Protokollierung aktiviert wird, finden Sie unter API-Anfrage- und Antwortdaten in Vorgangsprotokolle.

• Methode: Wählen Sie die HTTP-Methode aus, die für den ausgewählten Vorgang 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 den ausgewählten Vorgang 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: Zeigen Sie auf eine Service-Zeile, um zusätzliche Aktionen anzuzeigen.

  • API-Service-URL kopieren: Klicken Sie, um die Service-URL der API zu kopieren.
  • 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 Entität hinzufügen, um zur nächsten Registerkarte zu wechseln.

Klicken Sie nach der Konfiguration der Registerkarte Services 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 die Einschränkung des Zugriffs für die Nutzung der API.

Konfigurieren Sie die folgenden Einstellungen:

• Zuweisen: Nutzen Sie den Schieberegler, 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 Basic-Authentifizierung wird der Benutzername angezeigt. Bei anderen Authentifizierungstypen wird derselbe Wert wie in der Spalte Typ angezeigt.

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

  • Zum Sicherheitsprofil wechseln: 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. 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. Nutzen Sie den Schieberegler, um Rollen zuzuweisen oder die Zuweisung aufzuheben.

• Aktionen: Fahren Sie mit der Maus ü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 aus:

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

Der Zugriff auf die Seite Sicherheitsprofile und der Zugriff zum Verwenden der API werden durch diese Auswahl nicht beeinflusst. Der Zugriff zum Verwenden 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 mit dem Status Entwurf oder Veröffentlicht mit Entwurf. Entwurfs-APIs werden nicht auf Ihr Abonnementlimit API-URL 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 API-URL angerechnet, auch wenn der 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-URL angerechnet. Ein Dialog zeigt an, dass die API live ist:

  

  Der Dialog bietet folgende 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 Dokumentationsregisterkarte 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:

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

API bearbeiten

Nach dem Speichern der API können Sie diese an folgenden Stellen bearbeiten:

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

Beim Bearbeiten einer veröffentlichten API in 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 Dokumentationsregisterkarte auf der Seite APIs.

Fehlerbehebung

Weitere Informationen zur Fehlerbehebung finden Sie in folgendem Abschnitt des API Manager-Handbuchs zur Fehlerbehebung:

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