Veröffentlichen Sie eine Operation als API in Jitterbit Studio

Einführung

Diese Seite beschreibt, wie Sie eine benutzerdefinierte API (um eine Operation zur Nutzung bereitzustellen) innerhalb von Studio konfigurieren und veröffentlichen. Die Option Als API veröffentlichen ist über das Aktionsmenü der Operation zugänglich.

Alternativ können benutzerdefinierte APIs über den API-Manager mit der UI oder dem AI Assistant erstellt werden.

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

• Auf der Seite APIs des API-Managers.
• Im Ressourcen-Tab des Projektfensters für das mit der benutzerdefinierten API verbundene Studio-Projekt.

Voraussetzungen

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

• Die aufgerufene Organisation muss ein Abonnement für den API-Manager haben und die entsprechenden Rollenberechtigungen sowie Zugriffslevel für Umgebungen besitzen. Für Informationen zur Hinzufügung des API-Managers zu Ihrer Lizenz wenden Sie sich an Ihren 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 angeklickt haben, öffnet sich ein API-Konfigurationsbereich am unteren Rand des Projektdesigners. Die fünf Schritte des Konfigurationsprozesses werden im Folgenden 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 umgewandelten Operationsnamen ausgefüllt. 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:

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

• 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 lässt keine Leerzeichen oder bestimmte Sonderzeichen zu. Die Verwendung von Sonderzeichen außer einem Punkt (.) oder einem Bindestrich (-) wird nicht empfohlen. Häufige 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 2023-09-21.

Einstellungen

Fahren Sie mit der Konfiguration der API fort. Diese Einstellungen sind optional.

• Timeout: Geben Sie die Anzahl der Sekunden ein, 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 Operation time out, die im Options-Tab der Operation verfügbar ist. Die Einstellungen zur Operationstimeout werden für APIs im API-Manager nicht verwendet, es sei denn, es wird ein privater Agent verwendet und die Einstellung EnableAPITimeout in der Konfigurationsdatei des privaten Agents ist aktiviert.

• SSL nur: 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 dieses Schalters zeigt die folgende Nachricht an:

  Dialogtext

  CORS aktivieren
  Es wird nicht empfohlen, allen Ursprüngen den Zugriff auf eine API zu erlauben, da dies potenzielle Sicherheitsrisiken birgt. Ein zentrales Anliegen ist, dass dies dazu führt, dass die dem OPTIONS-Methodenaufruf zugewiesene Operation ohne Authentifizierung ausgeführt wird. Bitte bestätigen Sie vor der Aktivierung dieser Einstellung, dass sie mit den Sicherheitsrichtlinien Ihrer Organisation übereinstimmt.

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

  
  WeiterAbbrechen

• Ausführliches Protokollieren: Aktivieren Sie diese Option, um das ausführliche Protokollieren zu aktivieren. Ausführliche Protokolle für APIs enthalten Anforderungs- und Antwortdaten in jedem API-Protokoll, um eingehende und ausgehende Daten zu überwachen und das Debuggen zu erleichtern. Da dies große Protokolldateien erzeugen kann, ist das ausführliche Protokollieren standardmäßig deaktiviert. Das Aktivieren dieses Schalters zeigt die folgende Nachricht an:

  Dialogtext

  Ausführliches Protokollieren aktivieren
  Das ausführliche Protokollieren für APIs ermöglicht es dem Benutzer zu entscheiden, ob jedes API-Protokoll Anforderungs- und Antwortdaten enthalten soll. Diese Funktionalität hilft, eingehende/ausgehende Daten zu überwachen und API-Probleme zu debuggen.

  
  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 Dauer der Aktivierung beträgt zwei Wochen. Das Aktivieren dieses Schalters zeigt die folgende Nachricht an:

  Dialogtext

  Debug-Modus aktivieren
  Der Debug-Modus ermöglicht eine vollständige Nachverfolgung aller Anfragen, die über diese URL empfangen werden. Wenn er aktiviert ist, 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 Operationen. Aufgrund des hohen Datenvolumens und der möglichen Auswirkungen auf den Speicher kann der Debug-Modus nur für bis zu zwei Wochen aktiviert werden.

  
  FortfahrenAbbrechen

Dienste

Konfigurieren Sie Dienste für Ihre API.

• Dienstname: Geben Sie einen Namen für den API-Dienst ein. Standardmäßig ist dieses Feld auf den Namen der Operation eingestellt.

• Methode: Wählen Sie eine der ALL, CUSTOM, DELETE, GET, POST oder PUT als die zu verwendende Anfragemethode für die ausgewählte Operation. Die Auswahl von ALL erstellt separate DELETE, GET, POST und PUT Anfragemethoden für die Operation (die CUSTOM Methode ist nicht enthalten).

  Hinweis

  API-Dienste, die eine CUSTOM Methode verwenden, haben aufgrund einer Einschränkung der OpenAPI-Spezifikation keine OpenAPI-Dokumentation, die über die Portal Manager Seite generiert wird.

• Pfad: Der Pfad für die Anfrage.

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

• Auszulösende Operation: (Nur sichtbar für benutzerdefinierte APIs und OData-APIs.) Der Name der aufgerufenen Operation.

• Antworttyp: (Nur sichtbar für benutzerdefinierte APIs und OData-APIs.) Wählen Sie einen der Final Target, System Variable oder No Response:

  • Final Target: Die API-Antwort ist das endgültige Ziel der Operation. Wenn dieser Antworttyp ausgewählt ist, muss die Operation (als das endgültige Ziel der Operationenkette) eine Studio API-Antwortaktivität haben. Wenn ein anderes endgültiges Ziel verwendet wird, bleibt die API-Antwort leer.

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

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

• Aktionen: Bewege den Mauszeiger über die Dienstzeile, um zusätzliche Aktionen anzuzeigen:

  • API-Dienst-URL kopieren: Klicke, um die API-Dienst-URL in die Zwischenablage zu kopieren. (Du siehst eine Bestätigung der Aktion.)

  • Gehe zu API-Dienst: Öffnet die Seite Zusammenfassung & Bestätigung für die API, wo du die Einstellungen der API bearbeiten kannst.

  • Duplizieren: (Nur sichtbar für benutzerdefinierte APIs und OData-APIs.) Erstellt eine Duplikat des API-Dienstes. Du musst entweder die Anfragemethode oder den Pfad ändern, da jeder API-Dienst eine einzigartige Kombination dieser Felder haben muss.

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

Wenn du auf eine benutzerdefinierte API-Dienstzeile klickst, erscheinen diese Registerkarten:

Pfad-Parameter-Registerkarte

Wenn Anforderungsparameter im Pfad enthalten sind, wird diese Registerkarte mit diesen Feldern gefüllt:

• Parameter: Zeigt die im Pfad definierten Anforderungsparameter an.

• Beschreibung: Optional kannst du eine Beschreibung für die Anforderungsparameter eingeben.

Abfrageparameter-Registerkarte

Diese Registerkarte ermöglicht es dir, Abfrageparameter zum API-Dienst hinzuzufügen:

• Parameter hinzufügen: Klicken Sie, um einen Abfrageparameter zum API-Dienst 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öschen-Symbol neben einem Abfrageparameter, um diesen Parameter zu löschen.

Header-Registerkarte

Diese Registerkarte ermöglicht es Ihnen, Anforderungsheader zum API-Dienst hinzuzufügen:

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

  • Parameter: Geben Sie den Namen des Anforderungsheaders ein.

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

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

  • Löschen: Löscht den Anforderungsheader.

Sicherheitsprofile

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

• Suche: Geben Sie einen Teil des Namens des Sicherheitsprofils, des Typs oder des Benutzernamens in das Suchfeld ein, um die Liste der Dienste zu filtern. Verwenden Sie nur alphanumerische Zeichen. Die Suche ist nicht groß-/kleinschreibungsempfindlich.

• Neues Sicherheitsprofil: Öffnet ein Fenster zur Konfiguration eines neuen Sicherheitsprofils (siehe Sicherheitsprofile):

  

Die Liste der vorhandenen Sicherheitsprofile zur Auswahl zeigt diese in einer Tabelle mit den folgenden Spalten:

• Zuweisen: Verwenden Sie den Schalter, um das Sicherheitsprofil der API zuzuweisen oder zu entziehen.

  Regeln zur Zuweisung von Sicherheitsprofilen

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

  • Änderungen veröffentlichen: Wenn Sie ein Sicherheitsprofil von einer API mit dem Schalter entziehen, wird die Änderung als Entwurf gespeichert. Sie müssen die API veröffentlichen, damit die Änderung wirksam wird. Bis die API veröffentlicht ist, wird das Sicherheitsprofil weiterhin als "in Verwendung" betrachtet 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 Basis-Authentifizierung verwenden. Andernfalls wird der Authentifizierungstyp angezeigt.

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

  • Gehe zu Sicherheitsprofil: Ö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 Teil der Benutzerrolle, Berechtigung oder des Status in das Suchfeld ein, um die Liste der Dienste zu filtern. Verwenden Sie nur alphanumerische Zeichen. Die Suche ist nicht groß-/kleinschreibungsempfindlich.

• Neue Benutzerrolle: Öffnet ein Fenster zur Konfiguration einer neuen Benutzerrolle:

  

  • Rollename: 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 zur Rollenverwaltung

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

    • Benutzer mit Admin Berechtigung oder Schreib- Zugriff auf Umgebungen können Rollen für APIs zuweisen oder entfernen.
    • Benutzer mit Admin Berechtigung können neue Rollen erstellen und zuweisen.
    • Benutzer mit Admin Berechtigung können von keinem Benutzer von einer API abgemeldet werden.

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

  • Abbrechen: Schließt das Fenster, ohne Änderungen zu speichern.

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

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

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

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

Fußzeile

Die Fußzeile des Fensters zeigt diese Optionen. Sie können je nach dem, wie viel Sie bereits konfiguriert haben, aktiviert oder deaktiviert werden:

• Abbrechen: Schließt den Dialog, ohne zu speichern.

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

• Weiter: Gehen Sie 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 Entwurf-API zählt nicht als API-URL gegen Ihr Kontingent für die Harmony-Subscription. Sie können auf die Entwurf-API zugreifen und die Konfiguration über die Seite APIs des API-Managers 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 Kontingent für die Harmony-Subscription. Sie können auf die veröffentlichte API über die Seite APIs des API-Managers zugreifen.