OData-Dienstkonfiguration im Jitterbit API Manager

Einführung

Diese Seite beschreibt, wie man einen OData-Dienst von der APIs Seite des Jitterbit API Managers erstellt und konfiguriert. Ein OData-Dienst ist einer der drei Typen von APIs, die über den API Manager konfiguriert werden. Für die beiden anderen Typen — benutzerdefinierte API und Proxy-API — siehe Benutzerdefinierte API-Konfiguration oder Proxy-API-Konfiguration.

Voraussetzungen

Da ein OData-Dienst eine Jitterbit iPaaS API-Entitätsoperation zur Nutzung bereitstellt, muss eine solche Operation zuerst erstellt und bereitgestellt werden. Die Operation, die ein OData-Dienst auslöst, muss eine Design Studio API-Entitätsoperation sein. Die vorhandene API-Entitätsoperation wird dann während der Konfiguration des OData-Dienstes referenziert. Auf dieser Seite wird das Wort API verwendet, um sich auf einen OData-Dienst zu beziehen.

Für Informationen zur Erstellung und Bereitstellung einer API-Entitätsoperation im Design Studio siehe diese Ressourcen:

• Design Studio Schnellstartanleitung
• Erstellen einer Jitterbit-Entität
• Erstellen einer API-Entitätsoperation

Erstellen eines neuen OData-Dienstes

Wenn Sie die API Manager APIs Seite aufrufen und keine benutzerdefinierten APIs, OData-Dienste oder Proxy-APIs in der ausgewählten Organisation vorhanden sind, ist dieser Bildschirm leer.

Um einen neuen OData-Dienst zu erstellen, klicken Sie auf Neu > Benutzerdefinierte API:

Beim Klicken auf Benutzerdefinierte API öffnet sich der Bildschirm zur API-Konfiguration. Details zur Konfiguration eines neuen OData-Dienstes finden Sie in Konfigurieren eines OData-Dienstes weiter unten.

OData-Dienst konfigurieren

Der Konfigurationsbildschirm umfasst vier Konfigurationsschritte, die im Folgenden behandelt werden:

• Schritt 1: Einstellungen
• Schritt 2: Servicetyp auswählen und Operationen zuweisen
• Schritt 3: Benutzerrollen und Sicherheitsprofile zuweisen
• Schritt 4: Zusammenfassung und Bestätigung

Die Dienst-URL einer API ist die URL, die verwendet wird, um die API mit einer konfigurierten Authentifizierungsmethode zu konsumieren. Die Teile der Dienst-URL einer API werden in API-Dienst-URL beschrieben.

Die Dienst-URL wird oben in jedem Schritt angezeigt:

Schritt 1: Einstellungen

• API-Name: Geben Sie einen Namen für die API ein, der zur internen Identifizierung verwendet wird. Diese Sonderzeichen sind erlaubt:

  ( ) - _

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

  Hinweis

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

• 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 umgewandelt wurde. In diesem Feld sind keine Leerzeichen oder bestimmte Sonderzeichen erlaubt. Die Verwendung von Sonderzeichen außer einem Unterstrich (_) wird nicht empfohlen. Folgende Sonderzeichen sind erlaubt:

  . _ ~ ( ) $ ; / ? : @ = & ' ! * , + -

• Version: Geben Sie eine optionale Version an, die als Teil der Service-URL der API verwendet werden soll. Dieses Feld erlaubt maximal 48 Zeichen und lässt keine Leerzeichen oder bestimmte Sonderzeichen zu. Die Verwendung von Sonderzeichen außer einem Punkt (.) oder einem Bindestrich (-) wird nicht empfohlen. Übliche Namenskonventionen umfassen die Erhöhung von Versionen, wie v1.0, v1.1, v1.2, oder die Verwendung eines Datums, an dem die API veröffentlicht wurde, wie 2021-08-28.

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

• Timeout: Geben Sie die Anzahl der Sekunden an, bevor die API eine Zeitüberschreitung hat. Der Standardwert beträgt 30 Sekunden. Das Maximum sind 180 Sekunden.

  Hinweis

  Diese Einstellung ist unabhängig von der Einstellung zur Zeitüberschreitung der Operation in Integration Studio oder Design Studio. Einstellungen zur Zeitüberschreitung der Operation werden nicht verwendet, es sei denn, ein privater Agent wird verwendet und die Einstellung EnableAPITimeout in der Konfigurationsdatei des privaten Agents ist aktiviert.

• SSL Nur: Wenn ausgewählt (Standard), werden Daten über SSL verschlüsselt und HTTPS wird für alle API-Anfragen und -Antworten durchgesetzt (empfohlen).

  Wenn nicht ausgewählt, sind die über API-Anfragen und -Antworten übermittelten Daten nicht verschlüsselt und können von anderen abgefangen und eingesehen werden. Dies könnte potenziell sensible Informationen offenbaren.

• CORS aktivieren: Wählen Sie aus, um Cross-Origin Resource Sharing (CORS) zu aktivieren (nicht empfohlen). CORS aktivieren ist standardmäßig ausgewählt.

  Warning

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

• Verbose Logging aktivieren: Wählen Sie diese Option, um das ausführliche Protokollieren zu aktivieren. Das ausführliche Protokollieren für APIs umfasst Anforderungs- und Antwortdaten in jedem API-Protokoll, um eingehende und ausgehende Daten zu überwachen und das Debugging zu erleichtern. Da dies große Protokolldateien erzeugen kann, ist standardmäßig das ausführliche Protokollieren deaktiviert.

• Debug-Modus aktivieren bis: Wählen Sie diese Option, um den Debug-Modus zu aktivieren und ein entsprechendes Datum und eine Uhrzeit einzugeben, zu denen der Debug-Modus deaktiviert wird. Die maximale Dauer der Aktivierung beträgt zwei Wochen. Der Debug-Modus ermöglicht eine vollständige Nachverfolgung jeder über die Service-URL der API empfangenen Anfrage. Wenn aktiviert, behält das System den vollständigen Inhalt jeder API-Anfrage und -Antwort bis zu 24 Stunden nach dem Zeitpunkt, an dem der API-Aufruf empfangen wurde, und gilt für alle durch die API ausgelösten Vorgänge.

  Hinweis

  Das Durchsuchen der Ereignisdaten kann bei großen Volumina (Lasttests, Vorproduktionstests usw.) schwierig werden. Die Erhöhung der gespeicherten Daten kann zu Speicherplatz- und Sicherheitsbedenken führen. Wir empfehlen nicht, den Debug-Modus in einer Produktionsumgebung zu verwenden.

• Weiter: Klicken Sie, um die Konfiguration für diesen Schritt vorübergehend zu speichern und zum nächsten Schritt fortzufahren.

• Änderungen speichern: Klicken Sie, um die Konfiguration für diesen Schritt zu speichern und zu Schritt 4: Zusammenfassung und Bestätigung zu navigieren.

Schritt 2: Servicetyp auswählen und Vorgänge zuweisen

• Servicetyp: Wählen Sie OData-Dienst.

• Jitterbit-Entitäten zuweisen: Verwenden Sie die Dropdown-Menüs, um eine Entität (Projekt), Vorgang und Methode für den OData-Dienst auszuwählen:

  • Entität (Projekt): Wählen Sie aus den bereitgestellten Projekten, die eine Design Studio API-Entitätsoperation in der Umgebung enthalten, in der die API konfiguriert wird.

  • Vorgang: Wählen Sie aus den bereitgestellten Design Studio API-Entitätsoperationen in der ausgewählten Entität (Projekt). Es kann jeweils nur ein Vorgang mit jeder Methode zugewiesen werden.

    Wichtig

    Standardmäßig werden erfolgreiche Vorgänge, die für einen OData-Dienst konfiguriert sind, nicht in den Vorgangsprotokollen aufgeführt, es sei denn, eine dieser Einstellungen ist aktiviert:

    • Cloud-Agenten: Für API-Vorgänge auf einem Cloud-Agenten muss das Vorgangs-Debug-Logging für den Vorgang aktiviert sein.
    • Private Agenten: Für API-Vorgänge auf einem privaten Agenten muss entweder das Vorgangs-Debug-Logging für den Vorgang aktiviert sein oder Sie müssen EnableLogging=true im Abschnitt [APIOperation] der Konfigurationsdatei des privaten Agenten festlegen.

    Nicht erfolgreiche Vorgänge werden in den Vorgangsprotokollen aufgeführt, unabhängig davon, ob die oben genannten Einstellungen aktiviert sind oder nicht.

  • Methode: Wählen Sie eine der GET, PUT, POST, DELETE, PATCH, MERGE oder ALL Methoden aus, die für die ausgewählte Operation erstellt werden soll. Die Auswahl von ALL erstellt separate GET, PUT, POST, DELETE, PATCH und MERGE Methoden für die ausgewählte Operation.

• Entität zuweisen: Sobald alle Dropdowns ausgefüllt sind, klicken Sie auf Entität zuweisen, um die Entität zur Tabelle unten hinzuzufügen. Mindestens eine Entität muss hinzugefügt werden, um die Weiter-Schaltfläche zu aktivieren.

  Hinweis

  Nach dem Klicken auf Entität zuweisen können Sie den Diensttyp nicht mehr ändern.

• Zugewiesene Entitäten: Eine Tabelle zeigt alle zugewiesenen Entitäten an. Um eine zugewiesene Entität zu entfernen, klicken Sie auf das Entfernen-Symbol.

• Weiter: Klicken Sie, um die Konfiguration für diesen Schritt vorübergehend zu speichern und zum nächsten Schritt fortzufahren.

• Änderungen speichern: Klicken Sie, um die Konfiguration für diesen Schritt zu speichern und zu Schritt 4: Zusammenfassung und Bestätigung zu navigieren.

Schritt 3: Benutzerrollen und Sicherheitsprofile zuweisen

• Benutzerrollen zuweisen: Wählen Sie die Organisationsrollen aus, deren Mitglieder über die unten aufgeführten Seiten im API-Manager auf die API zugreifen können. Die auszuwählenden Rollen sind die, die auf der Seite Benutzerverwaltung der Management-Konsole definiert sind.

  Dies bestimmt den Zugriff auf diese spezifische API von diesen Seiten:

  • APIs
  • Portal-Manager, einschließlich der Erstellung von API-Dokumentationen
  • Portal
  • API-Protokolle
  • Analytik

  Der Zugriff auf die Seite Sicherheitsprofile und der Zugriff zur Nutzung der API sind von dieser Auswahl nicht betroffen. (Der Zugriff zur Nutzung einer API wird durch Sicherheitsprofile gesteuert.)

  Alle definierten Benutzerrollen mit der Admin-Berechtigung haben immer vollen Zugriff auf alle APIs und können daher nicht von der Auswahl entfernt werden. (In dem oben gezeigten Beispiel-Screenshot können die Rollen Administrator und Operations aus diesem Grund nicht abgewählt werden.)

  Hinweis

  APIs, die vor Harmony 10.22 erstellt wurden, haben standardmäßig alle Benutzerrollen ausgewählt, um den fortgesetzten Zugriff für alle Benutzer sicherzustellen.

• Sicherheitsprofil(e) zuweisen: Verwenden Sie das Dropdown-Menü, um ein vorhandenes Sicherheitsprofil auszuwählen, das verwendet wird, um den Zugriff zur Nutzung der API einzuschränken. Sie können jeden Teil des Namens des Sicherheitsprofils in das Menü eingeben, um die Liste der Sicherheitsprofile zu filtern. Die Menüergebnisse werden in Echtzeit mit jedem Tastendruck gefiltert. Ein Sicherheitsprofil kann erforderlich sein, um zugewiesen zu werden, um die API zu speichern, abhängig von den Richtlinien der Harmony-Organisation.

  • Profil zuweisen: Klicken Sie, um ein ausgewähltes Sicherheitsprofil der API zuzuweisen. Zugewiesene Sicherheitsprofile werden in der Tabelle mit dem Profilnamen und Typ aufgeführt, wie für das Sicherheitsprofil in der Konfiguration des Sicherheitsprofils konfiguriert. Wenn der Typ Basic ist, zeigt die Spalte Benutzername den während der Konfiguration angegebenen Benutzernamen an. Wenn der Typ ein anderer Typ ist, zeigt die Spalte Benutzername denselben Wert wie der Typ an. Um ein zugewiesenes Profil zu entfernen, klicken Sie auf das Entfernen-Symbol.

• Neues Profil erstellen: Klicken Sie, um ein neues Sicherheitsprofil zu erstellen. Für Anweisungen siehe Sicherheitsprofile.

• Weiter: Klicken Sie, um die Konfiguration für diesen Schritt vorübergehend zu speichern und zum nächsten Schritt fortzufahren. Wenn der API kein erforderliches Sicherheitsprofil zugewiesen ist, ist diese Option deaktiviert.

• Änderungen speichern: Wenn aktiviert, klicken Sie, um die Konfiguration für diesen Schritt zu speichern. Wenn der API kein erforderliches Sicherheitsprofil zugewiesen ist, ist diese Option deaktiviert.

• Diesen Schritt überspringen: Wenn vorhanden, klicken Sie, um zum nächsten Schritt fortzufahren, ohne die Konfiguration für diesen Schritt zu speichern. Wenn der API kein erforderliches Sicherheitsprofil zugewiesen ist, ist diese Option nicht vorhanden.

Schritt 4: Zusammenfassung und Bestätigung

• API-Name und Umgebung: Der API-Name gefolgt von der Umgebung in Klammern, wie in Schritt 1: Einstellungen konfiguriert.

  • Beschreibung, Zeitüberschreitung, Nur SSL, CORS aktiviert und Ausführliches Protokollieren aktiviert: Die API-Beschreibung und andere Einstellungen, die aktiviert () oder deaktiviert () sind. Um Änderungen an diesen Einstellungen vorzunehmen, klicken Sie auf das Bearbeitungssymbol, um zu Schritt 1: Einstellungen zurückzukehren.
  • Debug-Modus aktivieren bis: Diese Option ist dieselbe wie die, die in Schritt 1: Einstellungen beschrieben ist. Sie können diese Einstellung direkt von diesem Schritt aus ändern, anstatt zum ersten Schritt zurückkehren zu müssen.

• Operationen: Die in Schritt 2: Diensttyp auswählen und Operationen zuweisen zugewiesenen Operationen mit den entsprechenden Informationen für den ausgewählten Diensttyp. Um Änderungen vorzunehmen, klicken Sie auf das Bearbeitungssymbol, um zu Schritt 2: Diensttyp auswählen und Operationen zuweisen zurückzukehren.

• Benutzerrollen und Sicherheitsprofile: Die Rollen und Sicherheitsprofile, die in Schritt 3: Benutzerrollen und Sicherheitsprofile zuweisen zugewiesen sind. Um Änderungen vorzunehmen, klicken Sie auf das Bearbeitungssymbol, um zu Schritt 3: Benutzerrollen und Sicherheitsprofile zuweisen zurückzukehren.

• Export: Generiert und initiiert den Download einer APK-Datei (apis-export.apk), die einen Export der API enthält (siehe Exportieren und Importieren von APIs).

• Klonen: Erstellt eine Kopie einer vorhandenen API. In der API-Kopie wird der API-Name mit Kopie von vorangestellt, der Service Root wird mit Kopie von vorangestellt, und die Version wird mit -2 angehängt. Die API-Kopie wird sofort in ihrem eigenen Schritt 4: Zusammenfassung und Bestätigung geöffnet.

• Löschen: Löscht die API dauerhaft und schließt die Konfiguration. Ein Dialog fordert Sie auf, zu bestätigen, dass Sie die API löschen möchten.

  Hinweis

  Wenn der Status der API zum Zeitpunkt der Löschung Veröffentlicht oder Veröffentlicht mit Entwurf war, wird sie auch von der Anzahl der API-URLs entfernt, die gegen Ihr Abonnementlimit verwendet werden. Wenn der Status der API zum Zeitpunkt der Löschung Entwurf war, ändert sich die Anzahl der API-URLs, die gegen Ihr Abonnementlimit verwendet werden, nicht, da die API im Status Entwurf nicht zugänglich war.

• Als Entwurf speichern: Speichert die API im Status Entwurf oder Veröffentlicht mit Entwurf:

• Entwurf: Eine neue API oder eine API, deren Status zum Zeitpunkt der Verwendung von Als Entwurf speichern Entwurf war. Entwürfe zählen nicht gegen Ihr API-URL-Abonnementlimit.

• Veröffentlicht mit Entwurf: Eine API, deren Status zum Zeitpunkt der Verwendung von Als Entwurf speichern Veröffentlicht war. Eine API, die mit einem Entwurf veröffentlicht wird, zählt gegen Ihr API-URL-Abonnementlimit, da die API zugänglich ist, obwohl ihr Entwurf nicht.

• Speichern und 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 zählt gegen Ihr API-URL-Abonnementlimit, da die API zugänglich ist. Ein Dialog zeigt an, dass die API live ist:

  

• URL kopieren: Kopiert die Dienst-URL der API (siehe API-Dienst-URL).

• OpenAPI-Dokument generieren: Öffnet die Seite Portal Manager, auf der Sie die API-Dokumentation für die Seite Portal generieren können. Obwohl dieser Link für OData-Dienste erscheint, kann die OpenAPI-Dokumentation nur für benutzerdefinierte APIs generiert werden.
• Schließen: Schließt den Dialog.

OData-Dienstabfragen

Je nach Datenbank können Sie die zurückgegebenen Daten filtern, indem Sie OData-Abfrageparameter (wie $count, $inlinecount und $filter) an eine OData-Dienst-URL anhängen.

API bearbeiten

Nachdem Sie den OData-Dienst gespeichert haben, können Sie ihn von diesen Standorten aus bearbeiten:

• Verwenden Sie die Kachelansicht auf der Seite APIs, klicken Sie auf Anzeigen/Bearbeiten.
• Verwenden Sie die Listenansicht auf der Seite APIs, klicken Sie auf Bearbeiten in der Spalte Aktionen.