Wywoływanie usługi REST przy użyciu skryptu JavaScript

Edycja w trybie z połączeniem

Usługę REST można wywołać z zadania skryptowego w przepływie usługi. Pozwala to na wywoływanie operacji usług, których nie można wybrać jako implementacji zadania usługi w przepływie usługi.

O tym zadaniu

Jeśli do wywoływania usługi REST używany jest skrypt JavaScript, użytkownik ma większe możliwości i większą kontrolę nad ustawianiem parametrów wejściowych, nagłówków żądania, informacji uwierzytelniania, a także nad przetwarzaniem parametrów wyjściowych i obsługą błędów.

Procedura

Zadbaj o to, aby mieć adres URL lub lokalną kopię specyfikacji OpenAPI (uprzednio zwanej również specyfikacją Swagger) dla usługi REST, a także wszelkie referencje wywołania, które są wymagane do wywołania usługi REST.
Utwórz usługę zewnętrzną i wykryj, które operacje są obsługiwane:
1. Otwórz projektanta i wybierz opcję Usługi > + > Usługa zewnętrzna > Wykryj istniejącą usługę, a następnie wybierz plik specyfikacji OpenAPI jako dane wejściowe. Więcej informacji o wykrywaniu zewnętrznej usługi REST zawiera sekcja Wywoływanie usługi REST.
2. Jeśli dowolna z wykrytych operacji nie może zostać wywołana z poziomu zadania usługi, można kliknąć opcję Wyświetl wyjaśnienie , aby uzyskać więcej informacji. Jeśli wykryta operacja usługi, która ma zostać wywołana, może zostać wybrana jako implementacja zadania usługi w przepływie usługi, to będzie to prostsze. Aby użyć typów innych niż application/json (lub application/x-www-form-urlencoded z wartościami podstawowymi lub tablicami z wartościami podstawowymi lub text/plain z łańcuchem typu schematu), należy użyć interfejsu API JavaScript w celu wywołania usługi.
3. Aby znaleźć potrzebne informacje na temat usługi REST, która ma zostać wywołana, na przykład nazwę operacji, parametry (w tym nagłówki), wymagania zabezpieczeń i strukturę obiektu odpowiedzi, kliknij kartę Źródło dla usługi Usługa zewnętrzna , aby wyświetlić źródło specyfikacji OpenAPI .
  Inne informacje na temat usługi zawiera konfiguracja serwera REST dla usługi zewnętrznej.
Sprawdź certyfikat serwera dla usługi REST, która ma zostać wywołana.
Za pomocą języka JavaScript można nadpisać dowolną konfigurację protokołu SSL, która jest określona jako część serwera REST.
1. Jeśli certyfikat serwera jest podpisany przez publiczny ośrodek certyfikacji, można użyć wstępnie skonfigurowanej konfiguracji SSL o nazwie PublicInternetSSLSettings.
2. Jeśli certyfikat serwera nie jest podpisany przez jeden z publicznych ośrodków certyfikacji, które są uwzględnione we wstępnej konfiguracji protokołu SSL, administrator powinien utworzyć nową konfigurację protokołu SSL dla tej usługi i zaimportować certyfikat serwera do nowego magazynu zaufanych certyfikatów. Patrz Operating cloud environments.
Jeśli zdefiniowany jest już przepływ usługi, wybierz go. W przeciwnym razie należy utworzyć przepływ usługi, klikając opcję Usługi > + > Przepływ usługi. Więcej informacji na temat tworzenia przepływu usługi można znaleźć w sekcji Tworzenie przepływu usługi.
Dodaj zadanie skryptu do przepływu usługi.
Dodaj kod JavaScript do zadania skryptowego, aby wykonać następujące zadania.
1. Utwórz nową instancję obiektu żądania. Na przykład:
```
var request = new BPMRESTRequest();
```
2. Ustaw atrybuty obiektu żądania zgodnie z potrzebami, na przykład obowiązkową nazwę usługi zewnętrznej, nazwę operacji, nagłówki HTTP i parametry dla operacji, a także atrybuty opcjonalne takie jak referencje i nazwę konfiguracji protokołu SSL.
  Wszystkie atrybuty określone w obiekcie żądania przesłaniają wszystkie odpowiadające im wartości określone jako część serwera REST i powiązanie dla usługi zewnętrznej w projektancie.
  Obiekt żądania ma następujące atrybuty:
  externalServiceName
  
  Nazwa usługi REST. Na przykład:
  request.externalServiceName = "language-translator-v2";
  
  operationName
  
  Jeśli w pliku specyfikacji OpenAPI podano operationId dla operacji, która ma zostać wywołana, należy podać ją jako operationName, w przeciwnym razie należy podać httpMethod i path. Na przykład:
  request.operationName="checkout";
  
  httpMethod i path
  
  Jeśli plik specyfikacji OpenAPI nie określa operationId dla operacji, w celu zidentyfikowania operacji, która ma zostać wywołana, należy podać metodę i ścieżkę HTTP zamiast właściwości operationName. Na przykład:
  request.httpMethod = "GET"; request.path = "/v1/orders";
  
  endpointAddress
  
  Opcjonalnie zastępuje schemat, nazwę hosta, port i ścieżkę podstawową określone w pliku specyfikacji OpenAPI. Na przykład:
  request.endpointAddress = "https://localhost:9080/restBasePath";
  
  httpHeaders
  
  Obiekt JSON, który określa nagłówki HTTP. Na przykład:
  request.httpHeaders = {"Content-Type": "application/json", "Accept": "text/plain"};
  
  Ważne: Jeśli operacja, która ma zostać wywołana, ma parametr body, należy określić nagłówek Content-Type , aby był zgodny z typem treści dostarczonym przez użytkownika. W przeciwnym razie mogą być nieprzewidywalne wyniki. Poprawność nazw i wartości pól nagłówka żądania nie jest sprawdzana.
  
  W przypadku wartości formData:
  
  Jeśli zawiera plik, należy podać typ treści multipart/form-data.
  
  Jeśli nie zawiera pliku, należy podać typ treści multipart/form-data lub application/x-www-form-urlencoded.
  
  Ważne: Jeśli w nagłówku HTTP zostanie określony klucz interfejsu API, przesłania on dowolny dynamiczny klucz interfejsu API, który jest określony na karcie odwzorowania danych zadania usługi, co spowoduje przesłonięcie dowolnego klucza API określonego na karcie powiązania zewnętrznej usługi REST.
  
  parameters
  
  Obiekt JSON, który zawiera wszystkie parametry wymagane dla operacji. Na przykład:
  request.parameters = {"priority": "high", "customer": "Max", "age" : 23};
  
  Parametry mogą być również typami złożonymi. W takim przypadku należy podać je w jeden z następujących sposobów:
  request.parameters = {"priority": "high", "customerInfo": { "customerFirstName" : "Max", "customerLastName" : "Smith", "amount" : 100.56, "isActive" : true }};
  LUB
  request.parameters = {"priority": "high", "customerInfo": tw.local.customerInfo};
  Gdzie zmienna customerInfo ma typ złożony CustomerInfo z właściwościami customerLastName (String), customerFirstName (String), amount (Decimal) i isActive (Boolean).
  Ważne: Aby upewnić się, że właściwość typu integer w typie złożonym jest poprawnie interpretowana jako liczba całkowita, musi ona być określona jako zmienna typu Integer.
  
  requestTimeout
  
  Czas oczekiwania na przekroczenie limitu czasu żądania (w milisekundach). Na przykład:
  request.requestTimeout = 2000;
  
  responseTimeout
  
  Czas oczekiwania na przekroczenie limitu czasu odpowiedzi (w milisekundach). Na przykład:
  request.responseTimeout = 7200;
  
  username i password
  
  Nazwa użytkownika i hasło, jeśli używane jest podstawowe uwierzytelnianie. Na przykład:
  request.username = "user"; request.password = "password";
  
  invocationCredential
  
  Podaj dane uwierzytelniające wywołania zamiast username i password na potrzeby podstawowego uwierzytelniania. Na przykład:
  request.invocationCredential = "MyAuthenticationAlias";
  
  sslConfiguration
  
  Nazwa konfiguracji protokołu SSL, która ma być używana. Na przykład:
  request.sslConfiguration = "MySSLConfiguration";
  Ważne: Należy się upewnić, że zostały przekazane poprawne wartości, które są wymagane do pomyślnego wywołania usługi REST. Wartości są przekazywane do usługi REST bez sprawdzania poprawności.
3. Wywołaj funkcję tw.system.invokeREST() w obiekcie żądania, przypisując wynik do nowego obiektu odpowiedzi typu BPMRESTResponse().
  Na przykład:
```
var response = tw.system.invokeREST(request);
```
  Wskazówka: Jeśli zostanie wyświetlony następujący błąd:
```
javax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.h:
PKIX path building failed ...
```
  Należy skontaktować się z administratorem, aby utworzyć konfigurację SSL i zaimportować certyfikat serwera, zgodnie z opisem w kroku 3.b.
  Wskazówka: Jeśli zostanie wyświetlony następujący błąd:
```
javax.net.ssl.SSLHandshakeException: Remote host closed connection during handshake
```
  Protokół SSL/TLS podany w konfiguracji protokołu SSL i zakres protokołów SSL/TLS obsługiwanych przez serwer nie są zgodne. Należy poprosić administratora o zmianę protokołu SSL/TLS w sekcji Ustawienia jakość ochrony (QoP) konfiguracji protokołu SSL.
4. Przetwórz odpowiedź zgodnie z potrzebami.
  Zwykle należy sprawdzić kod statusu HTTP, aby upewnić się, że żądanie powiodło się. Jeśli wystąpił błąd, można go obsłużyć w samym zadaniu skryptowym lub można przypisać wartości do zmiennych, aby umożliwić obsługę różnych błędów w przepływie usługi. Warto zauważyć, że w kodzie skryptu Java można także przechwytywać wyjątki, używając w tym celu bloku try/catch. W przeciwnym razie wyjątek zakończy wykonywanie skryptu. Poniższy przykładowy fragment kodu pokazuje, jak można uzyskać dostęp do kodu statusu HTTP, komunikatu o statusie HTTP, nagłówków HTTP odpowiedzi oraz treści odpowiedzi w zadaniu skryptowym.
```
// Evaluate the response and process as necessary
var httpStatusCode = response.httpStatusCode;
var httpStatusMessage = response.httpStatusMessage;
var httpHeaders = response.httpHeaders;
var content = response.content;
```
  Pamiętaj: odpowiedź nie może być bezpośrednio zapisana w zmiennej przepływu usługi. W ten sposób zostanie zgłoszony błąd Java Class com.lombardisoftware.core.script.js.BPMRESTResponseScriptable is not registered as supported class for the SymbolTable. Zamiast tego można wyodrębnić właściwości tego obiektu i zapisać je w zmiennych przepływu usługi indywidualnie lub jako część obiektu biznesowego.
  
  Wskazówka: Przykład kodu obsługi błędów znajduje się w sekcji Obsługa błędów usługi REST.
Więcej informacji na temat obiektu żądania BPMRESTRequest() i obiektu odpowiedzi BPMRESTResponse zawiera sekcja Interfejs API językaJavaScript.
Kliknij Zapisz lub Zakończ edycję.