Custom API -Konfiguration im Jitterbit API-Manager

Einführung

Auf dieser Seite wird beschrieben, wie Sie aus den APIs eine benutzerdefinierte API erstellen und konfigurieren Seite von Jitterbit API-Manager. Benutzerdefinierte APIs sind eine der drei APIs Arten über den API-Manager konfiguriert. Informationen zu den beiden anderen Typen - OData-Dienst und Proxy-API - finden Sie unter OData-Dienstkonfiguration und Proxy-API Konfiguration.

Alternativ können benutzerdefinierte APIs im Integration Studio mithilfe der Funktion Als API veröffentlichen erstellt werden Option, auf die über das Aktionsmenü einer Operation zugegriffen werden kann.

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

• Die APIs Seite des API-Manager.
• Die Tab Ressourcen des Projektbereichs für das Integration Studio-Projekt, das mit der benutzerdefinierten API verknüpft ist.

Voraussetzungen

Da eine benutzerdefinierte API eine Harmony Operation zur Nutzung bereitstellt, muss diese zunächst in Harmony erstellt und bereitgestellt werden. Die vorhandene Operation wird dann bei der Konfiguration der benutzerdefinierten API referenziert. Die Operation, die eine benutzerdefinierte API auslöst, kann entweder ein Integration Studio oder Design Studio Operation.

Anweisungen zum Erstellen und Bereitstellen einer Operation finden Sie in den folgenden Ressourcen:

• Integration Studio
  • Operationserstellung und -konfiguration
  • Operationsbereitstellung und -ausführung
• Design Studio
  • Erstellen einer Operation

Erstellen einer neuen benutzerdefinierten API

Wenn Sie auf den API-ManagerAPIs zugreifen-Seite: Wenn in der ausgewählten Organisation keine benutzerdefinierten APIs, OData-Dienste oder Proxy-APIs vorhanden sind, ist dieser Bildschirm leer.

Um eine neue benutzerdefinierte API zu erstellen, klicken Sie auf Neu > Custom API:

Wenn Sie auf Neue API klicken, wird der Konfigurationsbildschirm für die benutzerdefinierte API geöffnet. Details zur Konfiguration einer neuen benutzerdefinierten API finden Sie unter Benutzerdefinierte API konfigurieren unten.

Konfigurieren einer benutzerdefinierten API

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

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

Die Service-URL einer API ist die URL, die zur Nutzung der API mithilfe einer konfigurierten Authentifizierungsmethode verwendet wird. Die Bestandteile der Service-URL einer API werden unter API-Manager - Erste Schritte beschrieben. in API -Dienst URL.

Die Service URL wird nach Abschluss von Schritt 1 oben in jedem Schritt angezeigt:

Schritt 1: Einstellungen

• API -Name: Geben Sie einen Namen für die API ein, der zur internen Identifikation verwendet werden soll. Folgende Sonderzeichen sind zulässig:

  ( ) - _

• Umgebung: Wählen Sie über das Menü die Umfeld aus, in der die API gespeichert werden soll. Sie können einen beliebigen Teil des Umfeld in das Menü eingeben, um die Liste der Umgebungen zu filtern. Die Menüergebnisse werden mit jedem Tastendruck in Echtzeit gefiltert.

  Notiz

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

• 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 API -Namen in Camel Case ausgefüllt. Dieses Feld erlaubt keine Leerzeichen oder bestimmte Sonderzeichen. Die Verwendung anderer Sonderzeichen als Unterstriche (_) wird nicht empfohlen. Folgende Sonderzeichen sind zulässig:

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

• Version: Geben Sie eine optionale Version ein, die als Teil der Service-URL der API verwendet werden soll. Dieses Feld ist auf maximal 48 Zeichen begrenzt und erlaubt keine Leerzeichen oder bestimmte Sonderzeichen. Die Verwendung anderer Sonderzeichen als Punkte (.) oder ein Bindestrich (-) wird nicht empfohlen. Gängige Namenskonventionen umfassen inkrementelle Versionen, wie z. B. v1.0, v1.1, v1.2oder mithilfe eines Datums, an dem die API veröffentlicht wurde, wie etwa 2021-08-28.

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

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

  Notiz

  Diese Einstellung ist unabhängig von der Timeout-Einstellung für den Operation in Integration Studio oder Design Studio. Die Timeout-Einstellungen für Vorgänge werden nur verwendet, wenn ein privater Agent verwendet wird und die EnableAPITimeout Einstellung in der privaten Agent-Konfigurationsdatei ist aktiviert.

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

  Wenn diese Option nicht aktiviert ist, werden die über API Anfragen und-Antworten übermittelten Daten nicht verschlüsselt und können von anderen abgefangen und eingesehen werden. Dies könnte möglicherweise vertrauliche Informationen offenlegen.

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

  Warnung

  Die Aktivierung von CORS führt dazu, dass Operationen mit dem OPTIONS Methode zur Ausführung ohne Authentifizierung.

• Ausführliche Protokollierung aktivieren: Aktivieren Sie diese Option, um die ausführliche Protokollierung zu aktivieren. Die ausführliche Protokollierung für APIs umfasst Anforderungs- und Antwortdaten in jedem API Protokoll, um die Überwachung eingehender und ausgehender Daten zu unterstützen und die Fehlerbehebung zu erleichtern. Da hierbei große Protokolldateien entstehen können, ist die ausführliche Protokollierung standardmäßig deaktiviert.

• Debug-Modus aktivieren bis: Wählen Sie diese Option, um den debuggen-Modus zu aktivieren und ein entsprechendes Datum und eine Uhrzeit einzugeben, an denen der debuggen Modus deaktiviert wird. Die Aktivierungsdauer beträgt maximal zwei Wochen. Der Debug-Modus ermöglicht die vollständige Ablaufverfolgung aller über die Service-URL der API empfangenen Anfragen. Wenn aktiviert, speichert das System den vollständigen Inhalt jeder API Anfrage und-Antwort bis zu 24 Stunden ab dem Zeitpunkt des API -Aufrufs und gilt für alle von der API ausgelösten Vorgänge.

  Notiz

  Das Durchsuchen der Ereignisdaten kann bei großen Datenmengen (Lasttests, Vorproduktionstests usw.) schwierig werden. Die Zunahme der gespeicherten Daten kann zu Speicherplatz- und Sicherheitsproblemen führen. Wir empfehlen, den debuggen Modus in einer Umfeld nicht zu verwenden.

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

• Änderungen speichern: Klicken Sie hier, 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

• Diensttyp: Wählen Sie Custom API.

• API Dienst hinzufügen: Klicken Sie hier, um einen API Dienst hinzuzufügen und einen Harmony Operation zur Nutzung freizugeben. Nach dem Klicken wird die individuelle API Dienstkonfiguration geöffnet (siehe unten). Einer benutzerdefinierten API können mehrere API Dienste hinzugefügt werden.

Nach dem Klick auf API Dienst hinzufügen wird die Konfiguration für einen API -Dienst geöffnet:

• Anforderungsmethode: Wählen Sie im Menü die Anforderungsmethode für den API Dienst aus: GET, POST, PUT, DELETE, ALL oder CUSTOM. Die Auswahl von ALL erzeugt separate GET, PUT, POST, Und DELETE Methoden für die ausgewählte Operation (die CUSTOM Die Methode ist nicht enthalten. Standardmäßig ist die Anforderungsmethode auf GET eingestellt.

  Notiz

  API -Dienste mit einem CUSTOM Für die Methode wird keine OpenAPI-Dokumentation über den Portal Manager generiert aufgrund einer Einschränkung der OpenAPI-Spezifikation.

• Dienstname: Geben Sie einen Namen für den API Dienst ein.

• Pfad: Geben Sie optional einen Pfad für die Anfrage ein. Der Pfad muss mit einem Schrägstrich beginnen. / und alle Anforderungsparameter müssen in geschweiften Klammern stehen { }. Andere Sonderzeichen sind nicht zulässig.

  Notiz

  Die Kombination aus Anforderungsmethode und Pfad muss für jeden API Dienst in der benutzerdefinierten API eindeutig sein.

• Name der benutzerdefinierten Methode: Sichtbar, wenn CUSTOM als Anforderungsmethode ausgewählt ist. Geben Sie den Namen der zu verwendenden Methode ein, z. B. PATCH. (Alpha-Zeichen, Bindestriche - und Unterstriche _ nur.)

• Operation: Auf der Tab Operation wählen Sie ein Projekt und eine Operation aus, die dem API Dienst zugewiesen werden sollen (erforderlich, um die Schaltfläche Speichern zu aktivieren):

  • Projekt zuweisen: Verwenden Sie das Menü, um ein bereitgestelltes Projekt aus der Umfeld auszuwählen, in der die API konfiguriert wird (angegeben in Schritt 1: Einstellungen). Sie können einen beliebigen Teil des Projektnamens in das Menü eingeben, um die Projektliste zu filtern. Die Menüergebnisse werden mit jedem Tastendruck in Echtzeit gefiltert.

  • Projekt bearbeiten: Wenn ein Integration Studio-Projekt ausgewählt ist, ist diese Schaltfläche aktiviert. Durch Klicken auf Projekt bearbeiten wird das Projekt in Integration Studio in einem neuen Tab geöffnet.

    Notiz

    Sie müssen alle am Projekt vorgenommenen Änderungen einsetzen, damit sie wirksam werden.

  • Operation(en) zuweisen: Verwenden Sie die Menüs, um eine Operation und einen Antworttyp für den API Dienst auszuwählen:

    • Operation: Wählen Sie aus den im ausgewählten Projekt bereitgestellten Operationen. Sie können einen beliebigen Teil des Operation in das Menü eingeben, um die Liste der bereitgestellten Operationen zu filtern. Die Menüergebnisse werden mit jedem Tastendruck in Echtzeit gefiltert.

      Wichtig

      Standardmäßig werden erfolgreiche Vorgänge, die für eine benutzerdefinierte API konfiguriert wurden, nicht in die Operation aufgenommen, sofern nicht eine dieser Einstellungen aktiviert ist:

      • Cloud-Agenten: Für API Operationen auf einem Cloud-Agenten Operation debuggen Protokollierung muss für die Operation aktiviert sein.
      • Private Agenten: Für API Operationen auf einem privaten Agenten muss entweder Operation debuggen Protokollierung muss für den Operation aktiviert sein oder Sie müssen EnableLogging=true im [APIOperation] Abschnitt der privaten Agentenkonfigurationsdatei.

      Nicht erfolgreiche Vorgänge werden in die Operation aufgenommen, ob die oben genannten Einstellungen aktiviert sind oder nicht.

    • Antworttyp: Wählen Sie zwischen Endziel, Systemvariable oder Keine Antwort:

      • Endziel: Die API Antwort ist das Endziel der Operation. Wenn dieser Antworttyp ausgewählt ist, muss die ausgewählte Operation als Endziel der Operation eine Integration Studio API Antwortaktivität haben oder Variablenschreibaktivität, oder ein Design Studio API -Antwortziel oder Globales Variablenziel. Wenn ein anderes endgültiges Ziel verwendet wird, ist 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 ausgewählte Operation als Teil der Operation ein Script enthalten, das die Jitterbit-Variable setzt. jitterbit.api.response entspricht der Antwort, 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 Anforderung zum Ausführen der ausgewählten Operation akzeptiert wird, gibt die API sofort eine leere Antwort mit dem HTTP-Code 202 zurück.

• Pfadparameter: Wenn Anforderungsparameter im Pfad enthalten sind, wird diese Tab mit den folgenden Feldern gefüllt:

  

  • Parameter: Zeigt die im Pfad definierten Anforderungsparameter an.

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

• Abfrageparameter: Auf dieser Tab können Sie dem API Dienst beliebige Abfrage hinzufügen:

  

  • Parameter hinzufügen Klicken Sie hier, um dem API Dienst einen Abfrage hinzuzufügen. Nach dem Klicken werden folgende Felder verfügbar:

    • Parameter: Geben Sie den Namen des Abfrage ein.

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

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

• Header: Auf dieser Tab können Sie dem API Dienst beliebige Anforderungsheader hinzufügen:

  

  • Parameter hinzufügen: Klicken Sie hier, um dem API Dienst einen Header hinzuzufügen. Nach dem Klicken werden folgende Felder verfügbar:

    • Parameter: Geben Sie den Namen des Header ein.

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

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

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

• Duplizieren: Klicken Sie auf das Duplikatssymbol, um ein Duplikat des API Dienstes zu erstellen.

  Notiz

  Sobald der API Dienst dupliziert ist, müssen Sie entweder die Anforderungsmethode oder den Pfad ändern, da jeder API Dienst eine eindeutige Kombination dieser Felder haben muss.

• Löschen: Klicken Sie auf das Löschen-Symbol neben einem API -Dienst, um ihn aus der benutzerdefinierten API zu löschen.

• Speichern: Klicken Sie hier, um den API Dienst zu speichern. Wenn die Konfiguration aller API Dienste abgeschlossen ist, werden die Schaltflächen Weiter und Änderungen speichern aktiviert. Eine unvollständige API Dienstkonfiguration wird mit einem Fehlersymbol neben dem Namen des API Dienstes:

  

  Um das Problem zu beheben und die Schaltflächen Weiter und Änderungen speichern zu aktivieren, schließen Sie die Konfiguration ab oder löschen Sie den API Dienst.

• Abbrechen: Klicken Sie hier, um die API Dienstkonfiguration abzubrechen.

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

• Änderungen speichern: Klicken Sie hier, 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 auf den unten aufgeführten API-Manager Seiten Zugriff auf die API haben sollen. Zur Auswahl stehen die Rollen, die auf der Tab Rollen der Benutzerverwaltung definiert sind..

  Dies bestimmt den Zugriff auf diese spezielle API von diesen Seiten aus:

  • APIs
  • Portalmanager, einschließlich der Erstellung von API Dokumentation
  • Portal
  • API Protokolle
  • Analyse

  Zugriff auf die Sicherheitsprofile und der Zugriff auf die API bleiben von dieser Auswahl unberührt. (Der Zugriff auf die API wird durch Sicherheitsprofile gesteuert.)

  Definierte Benutzerrollen mit der Berechtigung Admin haben immer vollen Zugriff auf alle APIs und können daher nicht aus der Auswahl gelöscht werden. (Im oben gezeigten Beispiel Screenshot kann die Rolle Administrator daher nicht gelöscht werden.)

  Notiz

  Bei APIs, die vor Harmony 10.22 erstellt wurden, sind standardmäßig alle Benutzerrollen ausgewählt, um allen Benutzern fortlaufenden Zugriff zu gewährleisten.

• Sicherheitsprofil(e) zuweisen: Wählen Sie aus der Dropdown-Liste ein vorhandenes Sicherheitsprofil aus, das den Zugriff auf die API einschränkt. Sie können einen beliebigen Teil des Sicherheitsprofilnamens in das Menü eingeben, um die Liste der Sicherheitsprofile zu filtern. Die Ergebnisse werden mit jedem Tastendruck in Echtzeit gefiltert. Je nach den Richtlinien der Harmony Organisation kann die Zuweisung eines Sicherheitsprofils erforderlich sein, um die API zu speichern.

  • Profil zuweisen: Klicken Sie hier, um der API ein ausgewähltes Sicherheitsprofil zuzuweisen. Zugewiesene Sicherheitsprofile werden in der Tabelle mit dem Profilnamen und Typ aufgeführt, die für das Sicherheitsprofil in der Sicherheitsprofilkonfiguration konfiguriert wurden. Wenn der Typ Basic ist, wird in der Spalte Benutzername der während der Konfiguration angegebene Benutzername angezeigt. Wenn der Typ ein anderer Typ ist, wird in der Spalte Benutzername derselbe Wert wie der Typ angezeigt. Um ein zugewiesenes Profil zu entfernen, klicken Sie auf das Symbol entfernen.
  • Neues Profil erstellen Klicken Sie hier, um ein neues Sicherheitsprofil zu erstellen. Anweisungen finden Sie unter Sicherheitsprofilkonfiguration.

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

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

• Diesen Schritt überspringen: Klicken Sie, falls vorhanden, um mit dem 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 Umfeld in Klammern, wie in Schritt 1: Einstellungen konfiguriert.

  • Beschreibung, Timeout, Nur SSL, CORS aktiviert und Ausführliche Protokollierung aktiviert: Die API Beschreibung und andere aktivierte Einstellungen () oder deaktiviert (). Um Änderungen an diesen Einstellungen vorzunehmen, klicken Sie auf das Bearbeiten-Symbol, um zu Schritt 1: Einstellungen zurückzukehren.
  • Debug-Modus aktivieren bis: Diese Option entspricht der in Schritt 1: Einstellungen beschriebenen. Sie können diese Einstellung direkt in diesem Schritt ändern, ohne zum ersten Schritt zurückkehren zu müssen.

• Operationen: Die in Schritt 2: Servicetyp auswählen und Operationen zuweisen zugewiesenen Operationen mit den entsprechenden Informationen zum ausgewählten Servicetyp. Um Änderungen vorzunehmen, klicken Sie auf das Bearbeiten-Symbol, um zu Schritt 2: Servicetyp auswählen und Vorgänge zuweisen zurückzukehren.

• Benutzerrollen und Sicherheitsprofile: Die in Schritt 3: Benutzerrollen und Sicherheitsprofile zuweisen zugewiesenen Rollen und Sicherheitsprofile. Um Änderungen vorzunehmen, klicken Sie auf das Bearbeiten-Symbol, um zu Schritt 3: Benutzerrollen und Sicherheitsprofile zuweisen zurückzukehren.

• Export: Generiert und startet 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 dem API -Namen die Zeichenfolge Kopie von, dem Dienststamm die Zeichenfolge Kopie von und der Version die Zeichenfolge -2 vorangestellt. Die API Kopie wird sofort in einem eigenen Fenster geöffnet Schritt 4: Zusammenfassung und Bestätigung.

• Löschen: Löscht die API dauerhaft und schließt die Konfiguration. Sie werden in einem Dialogfeld aufgefordert, das Löschen der API zu bestätigen.

  Notiz

  Wenn die API zum Zeitpunkt der Löschung den Status Veröffentlicht oder Veröffentlicht mit Entwurf hatte, wird sie auch von der Anzahl der auf Ihr Abonnementlimit angerechneten API-URLs abgezogen. Wenn die API zum Zeitpunkt der Löschung den Status Entwurf hatte, ändert sich die Anzahl der auf Ihr Abonnementlimit angerechneten API-URLs nicht, da die API im Status Entwurf nicht zugänglich war.

• Als Entwurf speichern: Speichert die API im Status Entwurf oder Mit Entwurf veröffentlicht:

• Entwurf: Eine neue API oder eine API, die zum Zeitpunkt der Verwendung von Als Entwurf speichern den Status Entwurf hatte. Entwürfe werden nicht auf Ihr API-URL-Abonnementlimit angerechnet.

• Veröffentlicht als Entwurf: Eine API, deren Status zum Zeitpunkt von Als Entwurf speichern Veröffentlicht war, wird verwendet. Eine als Entwurf veröffentlichte API wird auf Ihr API-URL-Abonnementlimit angerechnet, da die API zugänglich ist, der Entwurf jedoch nicht.

• Speichern und Veröffentlichen: Speichert die API im Status Veröffentlicht. Die API ist innerhalb von fünf Minuten verfügbar. Eine veröffentlichte API wird auf Ihr API-URL-Abonnementlimit angerechnet, da die API verfügbar ist. Ein Dialog zeigt an, dass die API verfügbar ist:

  

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

• OpenAPI-Dokument generieren: Öffnet den Portal Manager Seite, auf der Sie API Dokumentation für das Portal generieren können Seite.
• Ablehnen: Schließt den Dialog.