Operation als API in Jitterbit Studio veröffentlichen

Einführung

Diese Seite beschreibt, wie man eine benutzerdefinierte API konfiguriert und veröffentlicht (um eine Operation zur Nutzung freizugeben) von innerhalb von Studio. Die Option Als API veröffentlichen ist über das Aktionsmenü einer Operation erreichbar.

Alternativ können benutzerdefinierte APIs im API Manager über die Benutzeroberfläche oder den KI-Assistenten erstellt werden.

Eine aufgabenorientierte Anleitung zum Veröffentlichen einer Operation als REST-API, einschließlich Antwortkonfiguration und Sicherheit, finden Sie unter Studio-Operation als REST-API freigeben.

Benutzerdefinierte APIs (veröffentlicht und Entwurf) werden an diesen Orten angezeigt:

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

Voraussetzungen

Um die Option Als API veröffentlichen im Aktionsmenü der Operation zu verwenden, müssen diese Voraussetzungen erfüllt sein:

• Die Organisation, auf die zugegriffen wird, muss ein Abonnement für API Manager haben und verfügt über die entsprechenden Rollenberechtigungen und Zugriffsstufen für Umgebungen. Informationen zum Hinzufügen von API Manager zu Ihrer Lizenz erhalten Sie von Ihrem Customer Success Manager (CSM).

• Die Operation darf keine nicht bereitgestellten Änderungen aufweisen.

API konfigurieren

Nach dem Klick auf die Option Als API veröffentlichen im Aktionsmenü der Operation öffnet sich eine API-Konfigurationsleiste entlang der Unterseite des Projektgestalters. Die fünf Schritte des Konfigurationsprozesses sind nachfolgend beschrieben:

Profil

Geben Sie die folgenden grundlegenden Informationen zur API ein.

• API-Name: Geben Sie einen Namen für die API ein, der für interne Identifizierungszwecke verwendet werden soll.

• Service Root: Der öffentliche Name der API, der als Teil der Service-URL der API verwendet werden soll. Standardmäßig wird dieses Feld mit dem in Camel Case umgewandelten Operationsnamen gefüllt. Dieses Feld erlaubt keine Leerzeichen oder bestimmte Sonderzeichen. Die Verwendung von Sonderzeichen außer einem Unterstrich (_) wird nicht empfohlen. Diese Sonderzeichen sind zulässig:

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

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

• Umgebung: Dieses Feld ist auf die Umgebung des gerade aufgerufenen Projekts eingestellt und kann nicht geändert werden.

• Versionsnummer: Geben Sie optional eine Version ein, die als Teil der Service-URL der API verwendet werden soll. Dieses Feld erlaubt maximal 50 Zeichen und erlaubt 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 die Verwendung eines Datums, an dem die API veröffentlicht wurde, wie 2023-09-21.

Einstellungen

Konfigurieren Sie die API weiter. Diese Einstellungen sind optional.

• Timeout: Geben Sie die Anzahl der Sekunden ein, nach denen die API das Zeitlimit überschreitet. Der Standardwert beträgt 30 Sekunden. Das Maximum beträgt 180 Sekunden.

  Hinweis

  Diese Einstellung ist unabhängig von der Einstellung Operation timeout, die auf der Registerkarte Optionen des Vorgangs verfügbar ist. Die Timeout-Einstellungen für Vorgänge werden für API Manager-APIs nicht verwendet, es sei denn, es wird ein privater Agent verwendet und die Einstellung EnableAPITimeout in der Konfigurationsdatei des privaten Agenten ist aktiviert.

• Nur SSL: Diese Option ist standardmäßig aktiviert und erfordert die Verwendung von SSL-Verschlüsselung (empfohlen).

• CORS: Aktivieren Sie diese Option, um Cross-Origin Resource Sharing (CORS) zu aktivieren (nicht empfohlen). Die Aktivierung dieser Option zeigt die folgende Meldung:

  Dialogtext

  CORS aktivieren
  Es wird nicht empfohlen, dass jeder Origin auf eine API zugreifen kann, da dies potenzielle Sicherheitsrisiken birgt. Ein wichtiges Problem besteht darin, dass die dem OPTIONS-Verfahren zugewiesene Operation ohne Authentifizierung ausgeführt wird. Stellen Sie vor der Aktivierung dieser Einstellung sicher, dass sie den Sicherheitsrichtlinien Ihrer Organisation entspricht.

  Weitere Informationen finden Sie unter Cross-Origin Resource Sharing auf MDN.

  
  WeiterAbbrechen

• Ausführliches Logging: Aktivieren Sie diese Option, um das ausführliche Logging zu aktivieren. Ausführliche Protokolle für APIs enthalten in jedem API-Protokoll Anfrage- und Antwortdaten, um die Überwachung ein- und ausgehender Daten zu unterstützen und das Debuggen zu erleichtern. Da dies große Protokolldateien erzeugen kann, ist das ausführliche Logging standardmäßig deaktiviert. Die Aktivierung dieser Option zeigt die folgende Meldung:

  Dialogtext

  Ausführliches Logging aktivieren
  Das ausführliche Logging für APIs ermöglicht es dem Benutzer zu entscheiden, ob jedes API-Protokoll Anfrage- und Antwortdaten enthalten soll. Diese Funktionalität hilft bei der Überwachung ein- und ausgehender Daten und beim Debuggen von API-Problemen.

  
  WeiterAbbrechen

• Debug-Modus aktivieren bis: Wählen Sie diese Option, um den Debug-Modus zu aktivieren und ein entsprechendes Datum und eine Zeit einzugeben, zu dem der Debug-Modus deaktiviert wird. Die maximale Aktivierungsdauer beträgt zwei Wochen. Die Aktivierung dieser Option zeigt die folgende Meldung:

  Dialogtext

  Debug-Modus aktivieren
  Der Debug-Modus ermöglicht vollständige Verfolgung für alle Anfragen, die über diese URL empfangen werden. Nach der Aktivierung erfasst das System den vollständigen Inhalt jeder API-Anfrage und -Antwort für bis zu 24 Stunden. Dies umfasst alle durch die API ausgelösten Vorgänge. Aufgrund des hohen Datenvolumens und möglicher Speicherauswirkungen kann der Debug-Modus nur für bis zu zwei Wochen aktiviert werden.

  
  WeiterAbbrechen

Services

Konfigurieren Sie Services für Ihre API.

• Service-Name: Geben Sie einen Namen für den API-Service ein. Standardmäßig ist dieses Feld auf den Namen des Vorgangs eingestellt.

• Verfahren: Wählen Sie ALL, CUSTOM, DELETE, GET, POST oder PUT als die für den ausgewählten Vorgang verwendete Anfragemethode. Die Auswahl von ALL erstellt separate DELETE-, GET-, POST- und PUT-Anfragemethoden für den Vorgang (die CUSTOM-Methode ist nicht enthalten).

  Hinweis

  API-Services, die eine CUSTOM-Methode verwenden, haben keine OpenAPI-Dokumentation, die über die Seite Portal Manager generiert wird, da dies eine Einschränkung der OpenAPI-Spezifikation darstellt.

• Pfad: Der Pfad für die Anfrage.

• Projekt: (Nur für benutzerdefinierte APIs und OData-APIs sichtbar.) Der Name des Studio-Projekts.

• Auszulösender Vorgang: (Nur für benutzerdefinierte APIs und OData-APIs sichtbar.) Der Name des aufgerufenen Vorgangs.

• Antworttyp: (Nur für benutzerdefinierte APIs und OData-APIs sichtbar.) Dieses Feld ist erforderlich. Wählen Sie zwischen Finales Ziel, Systemvariable oder Keine Antwort:

  • Finales Ziel: Die API-Antwort ist das finale Ziel des Vorgangs. Wenn dieser Antworttyp ausgewählt ist, muss der Vorgang (als finales Ziel der Vorgangskette) eine Studio-API-Response-Aktivität haben. Wenn ein anderes finales Ziel verwendet wird, ist die API-Antwort leer.

  • Systemvariable: Die API-Antwort wird in einer Jitterbit-Variable im Vorgang festgelegt. Wenn dieser Antworttyp ausgewählt ist, muss der Vorgang (als Teil einer Vorgangskette) ein Skript haben, das die Jitterbit-Variable jitterbit.api.response gleich der Antwort setzt, die die API zurückgeben soll. Wenn diese Variable nicht festgelegt ist, ist die API-Antwort leer.

  • Keine Antwort: Die API-Antwort ist leer. Wenn die Anfrage zum Ausführen des ausgewählten Vorgangs akzeptiert wird, gibt die API sofort eine leere Antwort mit HTTP-Code 202 zurück.

• Aktionen: Halten Sie den Mauszeiger über die Service-Zeile, um zusätzliche Aktionen anzuzeigen:

  • API-Service-URL kopieren: Klicken Sie, um die API-Service-URL in die Zwischenablage zu kopieren. (Eine Bestätigung der Aktion wird angezeigt.)

  • Zum API-Service gehen: Öffnet die Seite Zusammenfassung & Bestätigung für die API, auf der Sie die API-Einstellungen bearbeiten können.

  • Duplizieren: (Nur für benutzerdefinierte APIs und OData-APIs sichtbar.) Erstellt ein Duplikat des API-Service. Sie müssen entweder die Anfragemethode oder den Pfad ändern, da jeder API-Service eine eindeutige Kombination dieser Felder haben muss.

  • Löschen: Löscht den API-Service.

Wenn Sie auf eine Zeile eines benutzerdefinierten API-Service klicken, werden diese Registerkarten angezeigt:

Registerkarte „Pfadparameter"

Wenn Anfrageparameter im Pfad enthalten sind, wird diese Registerkarte mit folgenden Feldern gefüllt:

• Parameter: Zeigt die im Pfad definierten Anfrageparameter an.

• Beschreibung: Optional können Sie eine Beschreibung für die Anfrageparameter eingeben.

Registerkarte „Abfrageparameter"

Auf dieser Registerkarte können Sie Abfrageparameter zum API-Service hinzufügen:

• Parameter hinzufügen: Klicken Sie, um einen Abfrageparameter zum API-Service hinzuzufügen. Nach dem Klicken werden folgende Felder verfügbar:

  • Parameter: Geben Sie den Namen des Abfrageparameters ein.

  • Beschreibung: Optional können Sie die Beschreibung des Abfrageparameters eingeben.

  • Löschen: Klicken Sie auf das -Lösch-Symbol neben einem Abfrageparameter, um diesen Parameter zu löschen.

Registerkarte „Header"

Auf dieser Registerkarte können Sie Anfrage-Header zum API-Service hinzufügen:

• Parameter hinzufügen: Klicken Sie, um einen Anfrage-Header zum API-Service hinzuzufügen. Nach dem Klicken werden folgende Felder verfügbar:

  • Parameter: Geben Sie den Namen des Anfrage-Header ein.

  • Beschreibung: Optional können Sie die Beschreibung des Anfrage-Header eingeben.

  • Erforderlich: Wählen Sie aus, ob der Anfrage-Header für jede API-Service-Anfrage erforderlich sein soll.

  • Löschen: Löscht den Anfrage-Header.

Sicherheitsprofile

Konfigurieren Sie Sicherheitsprofile für die API. Diese Einstellungen sind optional.

• Suche: Geben Sie einen beliebigen Teil des Sicherheitsprofil-Namens, des Typs oder des Benutzernamens in das Suchfeld ein, um die Serviceliste zu filtern. Es können nur alphanumerische Zeichen verwendet werden. Die Suche ist nicht case-sensitiv.

• Neues Sicherheitsprofil: Öffnet eine Schublade zur Konfiguration eines neuen Sicherheitsprofils (siehe Sicherheitsprofile):

  

Die Liste der vorhandenen Sicherheitsprofile zur Auswahl wird in einer Tabelle mit den folgenden Spalten angezeigt:

• Zuweisen: Verwenden Sie den Umschalter, um das Sicherheitsprofil der API zuzuweisen oder die Zuweisung aufzuheben.

  Regeln für die Zuweisung von Sicherheitsprofilen

  • Mehrere Profile: Sie können mehrere Sicherheitsprofile mit demselben Authentifizierungstyp einer API zuweisen. Es können nur die Authentifizierungstypen basic und API key zusammen verwendet werden.

  • Veröffentlichungsänderungen: Wenn Sie ein Sicherheitsprofil mithilfe des Umschalters von einer API entfernen, wird die Änderung als Entwurf gespeichert. Sie müssen die API veröffentlichen, damit die Änderung wirksam wird. Bis die API veröffentlicht wird, gilt das Sicherheitsprofil weiterhin als „in Verwendung" und kann nicht von der Seite Sicherheitsprofile gelöscht werden.

• Profilname: Der Name des Sicherheitsprofils.

• Typ: Der Authentifizierungstyp, einer von Anonym, API-Schlüssel, Standard oder OAuth 2.0.

• Benutzername: Zeigt den Benutzernamen für alle Sicherheitsprofile an, die die Standard-Authentifizierung verwenden. Andernfalls wird der Authentifizierungstyp angezeigt.

• Aktionen: Bewegen Sie den Mauszeiger über die Zeile des Sicherheitsprofils, um eine zusätzliche Aktion anzuzeigen:

  • Zum Sicherheitsprofil gehen: Öffnet den Konfigurationsbildschirm für das Sicherheitsprofil.

Benutzerrollen

Konfigurieren Sie Organisationsrollen, deren Mitglieder Zugriff auf die API haben. Diese Einstellungen sind optional.

Sie können die Tabelle nach Benutzerrolle sortieren, indem Sie auf die entsprechende Kopfzeile klicken.

• Suche: Geben Sie einen beliebigen Teil der Benutzerrolle, der Berechtigung oder des Status in das Suchfeld ein, um die Serviceliste zu filtern. Es können nur alphanumerische Zeichen verwendet werden. Die Suche ist nicht case-sensitiv.

• Neue Benutzerrolle: Öffnet eine Schublade zur Konfiguration einer neuen Benutzerrolle:

  

  • Rollenname: Geben Sie einen eindeutigen Namen für die Rolle ein.

  • Berechtigungen: Klicken Sie, um das Menü zu öffnen, und wählen Sie mindestens eine Berechtigung aus der Liste aus.

    Regeln für die Rollenverwaltung

    Diese Regeln gelten für die Verwaltung von Rollen in APIs:

    • Benutzer mit Admin-Berechtigung oder Schreib-Umgebungszugriff können Rollen zu APIs zuweisen oder die Zuweisung aufheben.
    • Benutzer mit Admin-Berechtigung können neue Rollen erstellen und zuweisen.
    • Benutzer mit Admin-Berechtigung können von keinem Benutzer von einer API entfernt werden.

  • Speichern: Speichert die Rolle und fügt sie zur Rollentabelle hinzu.

  • Abbrechen: Schließt die Schublade, ohne Änderungen zu speichern.

• Berechtigungen: Die Berechtigungen, die ein Benutzer aktuell hat.

• Status: Zeigt an, ob die Benutzerrolle der API zugewiesen oder nicht zugewiesen ist.

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

  • Zur Benutzerrolle gehen: Öffnet die Seite Benutzerverwaltung der Management Console.

Fußzeile

Die Fußzeile der Schublade zeigt diese Optionen. Sie können je nach bereits durchgeführter Konfiguration aktiviert oder deaktiviert werden:

• Abbrechen: Schließt das Dialogfeld, ohne zu speichern.

• Zurück: Kehren Sie zum vorherigen Schritt zurück.

• Weiter: Gehen Sie zum nächsten Schritt über.

• Als Entwurf speichern: Speichert die API im Status Entwurf und ist auf der Seite APIs des API-Managers zugänglich. Ein Entwurf einer API zählt nicht als API URL gegen Ihre Harmony-Abonnementgrenze. Sie können den Entwurf der API auf der Seite APIs des API-Managers aufrufen und die Konfiguration abschließen.

• 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 als API URL gegen Ihre Harmony-Abonnementgrenze. Sie können auf die veröffentlichte API auf der Seite APIs des API-Managers zugreifen.