Custom API Konfiguration im Jitterbit API-Manager

Einführung

Auf dieser Seite wird beschrieben, wie Sie über Meine APIs eine benutzerdefinierte API erstellen und konfigurieren. Seite von Jitterbit API-Manager. Benutzerdefinierte APIs sind eine der drei APIs-Arten über 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 erstellt werden in Integration Studio mithilfe der Funktion Als API veröffentlichen Option, auf die über das Aktionsmenü einer Operation zugegriffen werden kann.

Benutzerdefinierte APIs (veröffentlicht und im Entwurfsstadium) werden an diesen Speicherorten angezeigt:

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

Voraussetzungen

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

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

• Integration Studio
  • Erstellen und Konfigurieren von Vorgängen
  • Bereitstellung und Ausführung von Operationen
• Design Studio
  • Erstellen einer Operation

Erstellen einer neuen benutzerdefinierten API

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

Um eine neue benutzerdefinierte API zu erstellen, klicken Sie auf Neue API:

Wenn Sie auf Neue API klicken, wird der Konfigurationsbildschirm für die benutzerdefinierte API geöffnet. Einzelheiten zum Konfigurieren einer neuen benutzerdefinierten API finden Sie unter Konfigurieren einer benutzerdefinierten API 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 zum Verwenden der API mithilfe einer konfigurierten Authentifizierungsmethode verwendet wird. Die Teile 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 für interne Identifikationszwecke verwendet werden soll. Folgende Sonderzeichen sind zulässig:

  ( ) - _

• Umgebung: Verwenden Sie das Menü, um die Umfeld auszuwählen, in der die API gespeichert wird. 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. Diese Sonderzeichen sind erlaubt:

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

• Version: Geben Sie eine optionale Version ein, die als Teil der Service URL der API verwendet werden soll. Dieses Feld erlaubt maximal 48 Zeichen und keine Leerzeichen oder bestimmte Sonderzeichen. Die Verwendung anderer Sonderzeichen als eines Punktes (.) oder ein Bindestrich (-) wird nicht empfohlen. Gängige Namenskonventionen umfassen inkrementelle Versionen, wie z. B. v1.0, v1.1, v1.2 oder 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, bevor die API abläuft. Der Standardwert beträgt 30 Sekunden. Das Maximum beträgt 180 Sekunden.

  Notiz

  Diese Einstellung ist unabhängig von der Einstellung für das Operation Timeout in Integration Studio oder Design Studio. Einstellungen für das Timeout von Vorgängen werden nur dann 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 die Daten über SSL verschlüsselt und HTTPS für alle API Anfragen und-Antworten erzwungen (empfohlen).

  Wenn diese Option nicht ausgewählt ist, werden die über API -Anfragen und-Antworten übermittelten Daten nicht verschlüsselt und können von anderen abgefangen und eingesehen werden. Dadurch könnten möglicherweise vertrauliche Informationen preisgegeben werden.

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

  Warnung

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

• Ausführliches Protokollieren aktivieren: Wählen Sie diese Option aus, um das ausführliche Protokollieren zu aktivieren. Das ausführliche Protokollieren für APIs umfasst Anforderungs- und Antwortdaten in jedem API -Protokoll, um eingehende und ausgehende Daten zu überwachen und das Debuggen zu erleichtern. Da dadurch große Protokolldateien erstellt werden 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 maximale Aktivierungsdauer beträgt zwei Wochen. Der Debug-Modus ermöglicht die vollständige Nachverfolgung aller über die Service URL der API empfangenen Anfragen. Wenn diese Option aktiviert ist, behält das System den vollständigen Inhalt jeder API Anfrage und-Antwort bis zu 24 Stunden ab dem Zeitpunkt des Empfangs des API Aufrufs bei und gilt für alle von der API ausgelösten Vorgänge.

  Notiz

  Das Durchsuchen der Ereignisdaten kann bei großen Mengen schwierig werden (Lasttests, Vorproduktionstests usw.). Die Zunahme der gespeicherten Daten kann zu Speicherplatz- und Sicherheitsproblemen führen. Wir empfehlen, den debuggen 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 einem Klick auf API Dienst hinzufügen öffnet sich die Konfiguration für einen API -Dienst:

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

  Notiz

  API Dienste mit einem CUSTOM-Methode verfügt nicht über eine OpenAPI-Dokumentation, die über den Portal Manager generiert wird 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 Anfrageparameter müssen in geschweifte Klammern eingeschlossen sein { }. Alle anderen Sonderzeichen sind nicht erlaubt.

  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, zum Beispiel PATCH. (Alphazeichen, 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 Liste der Projekte zu filtern. Die Menüergebnisse werden mit jedem Tastendruck in Echtzeit gefiltert.

  • Projekt bearbeiten: Wann an Integration Studio Projekt ausgewählt ist, ist diese Schaltfläche aktiviert. Klicken Sie auf Projekt bearbeiten, um das Projekt in Integration Studio in einem neuen Tab.

    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 aus. 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 muss für die Operation aktiviert sein.
      • Private Agenten: Für API Operationen auf einem privaten Agenten muss entweder Operation debuggen muss für die 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 einen der folgenden Typen: 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 Folgendes haben: an Integration Studio API Antwortaktivität oder Aktivität „Variable schreiben“ 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 haben, das die Jitterbit-Variable festlegt 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 diese 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 diese 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 Dienstanforderung 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 für alle 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 die Schaltflächen Weiter und Änderungen speichern aufzulösen und 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 auf den unten aufgeführten API-Manager Seiten die Organisationsrollen aus, deren Mitglieder Zugriff auf die API haben. Zur Auswahl stehen die Rollen, die auf der Tab „Rollen“ der Seite „Benutzerverwaltung“ definiert sind..

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

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

  Zugriff auf die Sicherheitsprofile-Seite und der Zugriff auf die API sind von dieser Auswahl nicht betroffen. (Der Zugriff auf eine API wird durch Sicherheitsprofile gesteuert.)

  Alle definierten 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 aus diesem Grund nicht gelöscht werden.)

  Notiz

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

• Sicherheitsprofil(e) zuweisen: Verwenden Sie das Dropdown-Menü, um ein vorhandenes Sicherheitsprofil auszuwählen, das verwendet wird, um den Zugriff für die Nutzung der API einzuschränken. Sie können einen beliebigen Teil des Sicherheitsprofilnamens in das Menü eingeben, um die Liste der Sicherheitsprofile zu filtern. Die Menüergebnisse werden mit jedem Tastendruck in Echtzeit gefiltert. Je nach Richtlinien der Harmony-Organisation muss möglicherweise ein Sicherheitsprofil zugewiesen werden, 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 aufgelistet, wie sie für das Sicherheitsprofil in Sicherheitsprofilkonfiguration konfiguriert wurden. Wenn der Typ Basic ist, zeigt die Spalte Benutzername den Benutzernamen an, der während der Konfiguration angegeben wurde. Wenn der Typ ein anderer Typ ist, zeigt die Spalte Benutzername denselben Wert wie der Typ an. 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: Wenn aktiviert, klicken Sie, 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 in Klammern eingeschlossenen Umfeld, 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 ist dieselbe wie die in Schritt 1: Einstellungen beschriebene. Sie können diese Einstellung direkt in diesem Schritt ändern, anstatt 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 initiiert einen Download einer APK-Datei (apis-export.apk), das einen Export der API enthält (siehe APIs exportieren und importieren).

• Klon: Erstellt eine Kopie einer vorhandenen API. In der API Kopie wird dem API Namen Kopie von vorangestellt, der Dienststamm wird Kopie von vorangestellt und der Version wird -2 angehängt. Die API Kopie wird sofort in einem eigenen Schritt 4: Zusammenfassung und Bestätigung geöffnet.

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

  Notiz

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

• Als Entwurf speichern: Speichert die API im Status Entwurf oder Veröffentlicht mit Entwurf:

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

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

• Speichern und 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 wird auf Ihr API-URL-Abonnementlimit angerechnet, da die API zugänglich ist. Ein Dialog zeigt an, dass die API live 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.
• Verwerfen: Schließt den Dialog.