REST-Service unter Verwendung von JavaScript aufrufen

Rufen Sie einen REST-Service über eine Script-Task in einem Service-Flow auf. Mit dieser Methode können Sie Serviceoperationen aufrufen, die nicht als Implementierung einer Service-Task in einem Service-Flow im Web-Process Designer ausgewählt werden können.

Informationen zu diesem Vorgang

Durch die Verwendung von JavaScript beim Aufrufen eines REST-Service stehen Ihnen mehr Funktionen und Steuerungsmöglichkeiten zum Festlegen der Eingabeparameter, Anforderungsheader, Authentifizierungsdaten sowie für die Verarbeitung der Ausgabeparameter und für die Fehlerbehandlung zur Verfügung.

Vorgehensweise

  1. Stellen Sie sicher, dass Sie über eine lokale Kopie der OpenAPI-Spezifikation (bisher als 'Swagger' bezeichnet) für den REST-Service und über alle erforderlichen Berechtigungsnachweise zum Aufrufen verfügen, damit der REST-Service aufgerufen werden kann.
  2. Erstellen Sie mithilfe von Web-Process Designer einen externen Service und stellen Sie fest, welche Operationen unterstützt werden:
    1. Wählen Sie in Ihrer Prozessanwendung Services > + > Externer Service > Vorhandenen Service erkennen aus und wählen Sie anschließend die lokale Datei mit der OpenAPI-Spezifikation als Eingabe aus. Weitere Informationen zum Erkennen eines externen REST-Service finden Sie in REST-Service aufrufen.
    2. Wenn Fehler für Operationen gemeldet werden, können die betreffenden Operationen nicht von einer Service-Task aufgerufen werden. Wenn die erkannte Serviceoperation, die Sie aufrufen möchten, als Implementierung einer Service-Task in einem Service-Flow ausgewählt werden kann, dann ist diese Methode einfacher. Wenn Sie jedoch andere Typen als application/json verwenden möchten, müssen Sie die JavaScript-API verwenden, um den Service aufzurufen.
    3. Um die benötigten Informationen zu dem REST-Service zu finden, den Sie aufrufen möchten (z. B. Name der Operation, Parameter (einschließlich Header), Sicherheitsanforderungen und Struktur des Antwortobjekts) klicken Sie auf die Registerkarte Quelle für Externer Service, um die Quelle der OpenAPI-Spezifikation anzuzeigen. Weitere Informationen zu dem Service finden Sie in der REST-Serverkonfiguration für den externen Service.
  3. Überprüfen Sie das Serverzertifikat für den REST-Service, den Sie aufrufen möchten. Durch die Verwendung von JavaScript können Sie die SSL-Konfiguration überschreiben, die als Teil des REST-Servers angegeben ist.
    1. Wenn das Serverzertifikat von einer öffentlichen Zertifizierungsstelle unterzeichnet ist, können Sie die vorkonfigurierte SSL-Konfiguration namens PublicInternetSSLSettings verwenden.
    2. Wenn das Serverzertifikat nicht von einer der öffentlichen Zertifizierungsstellen unterzeichnet ist, die in der vorkonfigurierten SSL-Konfiguration enthalten sind, sollte ein Administrator für diesen Service eine neue SSL-Konfiguration erstellen und das Serverzertifikat in einen neuen Truststore importieren. Informationen zur Verwaltung von SSL-Konfigurationen finden Sie in den Abschnitten SSL-Konfiguration erstellen und Unterzeichner von einem fernen SSL-Port abrufen.
  4. Wenn Sie bereits einen Service-Flow definiert haben, wählen Sie den Service-Flow aus. Andernfalls erstellen Sie einen Service-Flow, indem Sie auf Services > + > Service-Flow klicken. Weitere Informationen zum Erstellen eines Service-Flows finden Sie in Service-Flow erstellen.
  5. Fügen Sie in Web-Process Designer eine Script-Task zu Ihrem Service-Flow hinzu.
  6. Fügen Sie JavaScript zu der Script-Task hinzu, um die folgenden Aktionen auszuführen.
    1. Erstellen Sie eine neue Instanz des Anforderungsobjekts. Beispiel: 
      var request = new BPMRESTRequest();
    2. Legen Sie die Attribute des Anforderungsobjekts nach Bedarf fest (z. B. den erforderlichen Namen des externen Services, den Namen der Operation, HTTP-Header und Parameter für die Operation) sowie optionale Attribute wie Berechtigungsnachweise und den Namen der SSL-Konfiguration. Alle Attribute, die Sie im Anforderungsobjekt angeben, überschreiben die entsprechenden Werte, die als Teil des REST-Servers für den externen Service in Process Designer angegeben sind.
      Das Anforderungsobjekt enthält die folgenden Attribute:
      externalServiceName
      Der Name des REST-Service. Beispiel:
      request.externalServiceName = "language-translator-v2";
      operationName
      Wenn in der OpenAPI-Spezifikationsdatei ein Attribut operationId für die Operation angegeben ist, die Sie aufrufen möchten, müssen Sie diese Angabe als operationName angeben; andernfalls müssen Sie httpMethod und path angeben. Beispiel:
      request.operationName="checkout";
      httpMethod und path
      Wenn in der OpenAPI-Spezifikationsdatei kein Attribut operationId für die Operation angegeben ist, um die aufzurufende Operation zu identifizieren, müssen Sie stattdessen die HTTP-Methode und den Pfad der Eigenschaft operationName angeben. Beispiel:
      request.httpMethod="GET";
request.path="/v1/orders";
      endpointAddress
      Überschreibt optional das Schema, den Hostnamen, den Port und den Basispfad, die in der OpenAPI-Spezifikationsdatei angegeben sind. Beispiel:
      request.endpointAddress = "https://localhost:9080/restBasePath";
      httpHeaders
      Ein JSON-Objekt, das HTTP-Header angibt. Beispiel:
      request.httpHeaders =  {"Content-Type": "application/json",
                        "Accept": "text/plain"};
      Für 'formData' gilt Folgendes:
      • Wenn eine Datei enthalten ist, geben Sie den Inhaltstyp 'multipart/form-data' an.
      • Wenn keine Datei enthalten ist, geben Sie den Inhaltstyp 'multipart/form-data' oder 'application/x-www-form-urlencoded' an.
      parameters
      Ein JSON-Objekt, das alle erforderlichen Parameter für die Operation enthält. Beispiel:
      request.parameters = {"priority": "high",
                      "customer": "Max",
                      "age" : "23"};
      requestTimeout
      Die Wartezeit in Millisekunden, nach der das Zeitlimit für die Anforderung abgelaufen ist. Beispiel:
      request.requestTimeout = 2000;
      responseTimeout
      Die Wartezeit in Millisekunden, nach der das Zeitlimit für die Antwort abgelaufen ist. Beispiel:
      request.responseTimeout = 7200;
      username und password
      Der Benutzername und das Kennwort bei Verwendung der Basisauthentifizierung. Beispiel:
      request.username = "user";
request.password = "password";
      invocationCredential
      Die Aufrufberechtigungsnachweise anstelle von username und password für die Basisauthentifizierung angeben. Beispiel:
      request.invocationCredential = "MyAuthenticationAlias";
      sslConfiguration
      Der Name der SSL-Konfiguration, die verwendet werden soll. Beispiel:
      request.sslConfiguration = "MySSLConfiguration";
      Wichtig: Stellen Sie sicher, dass die korrekten Werte übergeben werden, die für einen erfolgreichen REST-Aufruf erforderlich sind. IBM® BPM übergibt die angegebenen Werte an den REST-Service, ohne sie zu validieren.
    3. Rufen Sie die Funktion tw.system.invokeREST() im Anforderungsobjekt auf und weisen Sie das Ergebnis einem neuen Antwortobjekt des Typs BPMRESTResponse() zu. Beispiel: 
      var response = tw.system.invokeREST(request);
      Tipp: Angenommen, der folgende Fehler wird angezeigt: 
      javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException:
PKIX path building failed ...
      In diesem Fall müssen Sie veranlassen, dass der zuständige Administrator eine SSL-Konfiguration erstellt, und das Serverzertifikat importieren, wie im Schritt 3.b beschrieben.
    4. Verarbeiten Sie die Antwort nach Bedarf.
    Weitere Informationen zum Anforderungsobjekt BPMRESTRequest() und zum Antwortobjekt BPMRESTResponse finden Sie in JavaScript-API.
  7. Klicken Sie auf Speichern oder auf Bearbeitung beenden.
Übergeordnetes Thema: REST-Service aufrufen