Operation als API in Jitterbit Studio veröffentlichen

Einführung

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

Alternativ können Custom APIs über den API Manager mit der Benutzeroberfläche oder dem KI-Assistenten erstellt werden.

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

Custom APIs (veröffentlicht und als Entwurf) werden an folgenden Orten angezeigt:

• Die Seite APIs des API Managers.
• Die Registerkarte Ressourcen im Projektbereich für das Studio-Projekt, das der Custom 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 über die entsprechenden Rollenberechtigungen und Zugriffsstufen für Umgebungen verfügen. 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

Nachdem Sie die Option Als API veröffentlichen im Aktionsmenü der Operation anklicken, wird eine API-Konfigurationsleiste am unteren Rand des Projekt-Designers geöffnet. Die fünf Schritte des Konfigurationsprozesses werden nachfolgend beschrieben:

Profil

Geben Sie die folgenden grundlegenden Informationen zur API ein.

• API-Name: Geben Sie einen Namen für die API ein, der zur internen Identifikation verwendet wird.

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

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

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

• Umgebung: Dieses Feld wird auf die Umgebung des aktuell aufgerufenen Projekts gesetzt und kann nicht geändert werden.

• Versionsnummer: Geben Sie eine optionale Version ein, die als Teil der Service-URL der API verwendet wird. Dieses Feld erlaubt maximal 50 Zeichen und keine Leerzeichen oder bestimmte Sonderzeichen. Die Verwendung von Sonderzeichen außer einem Punkt (.) oder einem Bindestrich (-) ist nicht empfohlen. Häufige Namenskonventionen sind 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

Fahren Sie mit der Konfiguration der API fort. 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 liegt bei 180 Sekunden.

  Hinweis

  Diese Einstellung ist unabhängig von der Einstellung Operation Timeout, die auf der Registerkarte Optionen des Vorgangs verfügbar ist. Einstellungen für das Timeout von Vorgängen werden nicht für API Manager-APIs 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 ermöglichen (nicht empfohlen). Das Aktivieren dieser Option zeigt die folgende Meldung an:

  Dialogtext

  CORS aktivieren
  Es wird nicht empfohlen, dass eine beliebige Quelle auf eine API zugreift, da dies potenzielle Sicherheitsrisiken mit sich bringt. Ein wichtiges Problem besteht darin, dass der dem OPTIONS-Verfahren zugewiesene Vorgang ohne Authentifizierung ausgeführt wird. Bitte bestätigen Sie vor der Aktivierung dieser Einstellung, dass sie mit den Sicherheitsrichtlinien Ihres Unternehmens konform ist.

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

  
  FortfahrenAbbrechen

• Ausführliches Logging: Aktivieren Sie diese Option, um ausführliches Logging zu aktivieren. Ausführliche Protokolle für APIs enthalten in jedem API-Protokoll Request- und Response-Daten, um eingehende und ausgehende Daten zu überwachen und das Debugging zu erleichtern. Da dies zu großen Protokolldateien führen kann, ist ausführliches Logging standardmäßig deaktiviert. Das Aktivieren dieser Option zeigt die folgende Meldung an:

  Dialogtext

  Ausführliches Logging aktivieren
  Mit ausführlichem Logging für APIs kann der Benutzer entscheiden, ob jedes API-Protokoll Request- und Response-Daten enthalten soll. Diese Funktionalität hilft bei der Überwachung ein- und ausgehender Daten sowie beim Debuggen von API-Problemen.

  
  FortfahrenAbbrechen

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

  Dialogtext

  Debug-Modus aktivieren
  Der Debug-Modus aktiviert die vollständige Nachverfolgung aller Anforderungen, die über diese URL eingehen. Bei Aktivierung erfasst das System den vollständigen Inhalt jeder API-Anfrage und Antwort bis zu 24 Stunden lang. Dies umfasst alle vom API ausgelösten Vorgänge. Aufgrund des hohen Datenaufkommens und möglicher Auswirkungen auf den Speicher kann der Debug-Modus maximal zwei Wochen lang aktiviert werden.

  
  FortfahrenAbbrechen

Services

Konfigurieren Sie Services für Ihre API.

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

• Methode: Wählen Sie aus ALL, CUSTOM, DELETE, GET, POST oder PUT als Request-Methode, die für den ausgewählten Vorgang verwendet werden soll. Wenn Sie ALL wählen, werden separate DELETE-, GET-, POST- und PUT-Request-Methoden für den Vorgang erstellt (die CUSTOM-Methode ist nicht enthalten).

  Hinweis

  API-Services, die eine CUSTOM-Methode verwenden, lassen sich aufgrund einer Einschränkung der OpenAPI-Spezifikation nicht über die Seite Portal Manager dokumentieren.

• Pfad: Der Pfad für die Anfrage.

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

• Auszuführender 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 einen der folgenden Optionen: 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 enthalten. Wird ein anderes finales Ziel verwendet, ist die API-Antwort leer.

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

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

• Aktionen: Fahren Sie über die Servicezeile, um zusätzliche Aktionen anzuzeigen:

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

  • Zum Vorgang gehen: Öffnet das Studio-Projekt in einem neuen Browser-Tab. Der Vorgang im Feld Auszuführender Vorgang wird auf der Entwurfsfläche von Studio hervorgehoben. Diese Aktion ist für Design-Studio-Vorgänge deaktiviert.

  • 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 diesen Feldern gefüllt:

• Parameter: Zeigt die im Pfad definierten Anfrageparameter an.

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

Registerkarte „Abfrageparameter"

Diese Registerkarte ermöglicht es Ihnen, Abfrageparameter zum API-Service hinzuzufügen:

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

  • Parameter: Geben Sie den Namen des Abfrageparameters ein.

  • Beschreibung: Geben Sie optional die Beschreibung des Abfrageparameters ein.

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

Registerkarte „Header"

Diese Registerkarte ermöglicht es Ihnen, Anfrage-Header zum API-Service hinzuzufügen:

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

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

  • Beschreibung: Geben Sie optional die Beschreibung des Anfrage-Header ein.

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

  • 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 Sicherheitsprofilnamens, des Typs oder des Benutzernamens in das Suchfeld ein, um die Serviceliste zu filtern. Verwenden Sie nur alphanumerische Zeichen. Die Suche unterscheidet nicht zwischen Groß- und Kleinschreibung.

• Neues Sicherheitsprofil: Öffnet eine Schublade zum Konfigurieren eines neuen Sicherheitsprofils (siehe Sicherheitsprofile):

  

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

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

  Zuweisungsregeln für Sicherheitsprofile

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

  • Veröffentlichungsänderungen: Wenn Sie ein Sicherheitsprofil über den Schalter von einer API aufheben, wird die Änderung als Entwurf gespeichert. Sie müssen die API veröffentlichen, damit die Änderung wirksam wird. Bis die API veröffentlicht wird, wird das Sicherheitsprofil immer noch als „verwendet" betrachtet und kann auf der Seite Sicherheitsprofile nicht gelöscht werden.

• Profilname: Der Name des Sicherheitsprofils.

• Typ: Der Authentifizierungstyp, einer der folgenden: Anonym, API-Schlüssel, Basic oder OAuth 2.0.

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

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

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

Benutzerrollen

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

Die Tabelle kann durch Klicken auf die jeweilige Kopfzeile nach Benutzerrolle sortiert werden.

• Suche: Geben Sie einen beliebigen Teil der Benutzerrolle, Berechtigung oder des Status in das Suchfeld ein, um die Serviceliste zu filtern. Verwenden Sie nur alphanumerische Zeichen. Die Suche unterscheidet nicht zwischen Groß- und Kleinschreibung.

• Neue Benutzerrolle: Öffnet eine Schublade zum Konfigurieren 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 dann 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 aufgehoben werden.

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

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

• Berechtigungen: Die Berechtigungen, über die ein Benutzer derzeit verfügt.

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

• Aktionen: Fahren Sie mit der Maus über die Benutzerrollenzeile, um eine zusätzliche Aktion anzuzeigen:

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

Fußzeile

Die Fußzeile der Schublade zeigt diese Optionen. Sie können je nachdem, wie viel Sie bereits konfiguriert haben, aktiviert oder deaktiviert werden:

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

• Zurück: Kehrt zum vorherigen Schritt zurück.

• Weiter: Geht 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. Eine Entwurfs-API zählt nicht als API-URL gegen Ihr Harmony-Abonnement. Man kann die Konfiguration der Entwurfs-API auf der Seite APIs des API-Managers aufrufen und 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 Ihr Harmony-Abonnement. Man kann die veröffentlichte API auf der Seite APIs des API-Managers aufrufen.