Operation als API in Jitterbit Studio veröffentlichen

Einführung

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

Alternativ können benutzerdefinierte 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 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 des Projektbereichs 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 über ein Abonnement für API Manager verfügen und die entsprechenden Rollenberechtigung und Umgebungszugriffsstufen haben. 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 Klicken auf die Option Als API veröffentlichen im Aktionsmenü der Operation 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 für interne Identifikationszwecke 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 gefüllt. Dieses Feld erlaubt keine Leerzeichen oder bestimmte Sonderzeichen. Die Verwendung von Sonderzeichen außer Unterstrich (_) wird nicht empfohlen. Diese Sonderzeichen sind zulässig:

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

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

• Umgebung: Dieses Feld ist auf die Umgebung des aktuell aufgerufenen Projekts eingestellt 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 Punkt (.) oder 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 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 ist 30 Sekunden. Das Maximum beträgt 180 Sekunden.

  Hinweis

  Diese Einstellung ist unabhängig von der Einstellung Operation timeout auf der Registerkarte „Optionen" des Vorgangs. 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). Das Aktivieren dieser Option zeigt die folgende Meldung an:

  Dialogtext

  CORS aktivieren
  Es wird nicht empfohlen, dass jeder Ursprung auf eine API zugreift, da dies potenzielle Sicherheitsrisiken mit sich bringt. Ein wichtiges Problem besteht darin, dass die dem OPTIONS-Verfahren zugewiesene Operation ohne Authentifizierung ausgeführt wird. Bevor Sie diese Einstellung aktivieren, bestätigen Sie bitte, dass sie mit den Sicherheitsrichtlinien Ihrer Organisation übereinstimmt.

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

  
  WeiterAbbrechen

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

  Dialogtext

  Ausführliches Logging aktivieren
  Das ausführliche Logging für APIs ermöglicht 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 Uhrzeit einzugeben, 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 ermöglicht vollständiges Tracing für alle Anfragen, die über diese URL empfangen werden. Wenn aktiviert, 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 großen Datenvolumens und der möglichen Auswirkungen auf den Speicher 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.

• Methode: Wählen Sie eine der Optionen ALL, CUSTOM, DELETE, GET, POST oder PUT als Anfragemethode für den ausgewählten Vorgang. Wenn Sie ALL wählen, werden separate DELETE-, GET-, POST- und PUT-Anfragemethoden für den Vorgang erstellt (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 ist.

• 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 eine 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 haben. Wenn ein anderes finales Ziel verwendet wird, ist die API-Antwort leer.

  • Systemvariable: Die API-Antwort wird in einer Jitterbit-Variablen 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 auf die 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 eine sofortige leere Antwort mit HTTP-Code 202 zurück.

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

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

  • Zu API-Service wechseln: Ö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 benutzerdefinierte API-Service-Zeile 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-Headers ein.

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

  • 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 Namens, des Typs oder des Benutzernamens des Sicherheitsprofils in das Suchfeld ein, um die Liste der Dienste zu filtern. Verwenden Sie nur alphanumerische Zeichen. Die Suche ist nicht case-sensitiv.

• 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.

  Regeln für die Zuweisung von Sicherheitsprofilen

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

  • Änderungen veröffentlichen: Wenn Sie die Zuweisung eines Sicherheitsprofils zu einer API mithilfe des Schalters 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, 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, Basis oder OAuth 2.0.

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

• Aktionen: Bewegen Sie den Mauszeiger ü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.

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 Liste der Dienste zu filtern. Verwenden Sie nur alphanumerische Zeichen. Die Suche ist nicht case-sensitiv.

• 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 entfernt werden.

  • Speichern: Speichert die Rolle und fügt sie zur Tabelle der Rollen hinzu.

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

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

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

• Aktionen: Bewegen Sie den Mauszeiger ü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: Wechselt zum nächsten Schritt.

• Als Entwurf speichern: Speichert die API im Status Entwurf und ist über die Seite APIs des API-Managers zugänglich. Eine Entwurfs-API zählt nicht als API-URL gegen Ihr Harmony-Abonnementkontingent. Sie können die Konfiguration der Entwurfs-API über die 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-Abonnementkontingent. Sie können auf die veröffentlichte API über die Seite APIs des API-Managers zugreifen.