Richiamo di un servizio REST utilizzando JavaScript

Richiama un servizio REST da una attività script in un flusso di servizio. Ciò consente di richiamare le operazioni di servizio che non possono essere selezionate come un'implementazione di un'attività di servizio in un flusso di servizio.

Informazioni su questa attività

Utilizzando JavaScript per richiamare un servizio REST, si hanno più funzionalità e controllo sull'impostazione dei parametri di input, delle intestazioni delle richieste, delle informazioni di autenticazione, dell'elaborazione dei parametri di output e della gestione degli errori.

Procedura

  1. Assicurarsi di disporre dell' URL o di una copia locale del file di specifica OpenAPI (precedentemente noto come Swagger) per il servizio REST e delle credenziali di invocazione necessarie per poter chiamare il servizio REST.
  2. Creare un servizio esterno e rilevare quali operazioni sono supportate:
    1. Aprire il designer e selezionare Servizi > + > Servizio esterno > Scopri un servizio esistente, quindi selezionare il file di specifica OpenAPI come input. Per ulteriori informazioni sul rilevamento di un servizio REST esterno, consultare Richiamo di un servizio REST.
    2. Se una qualsiasi delle operazioni rilevate non può essere richiamata da un'attività di servizio, è possibile fare clic su Visualizza spiegazione per ulteriori informazioni. Se l'operazione di servizio rilevata che si desidera richiamare può essere selezionata come implementazione di un'attività di servizio in un flusso di servizio, ciò è più semplice. Se si desidera utilizzare tipi diversi da application/json (o application/x-www-form-urlencoded con valori primitivi o array con valori primitivi o text/plain con stringa del tipo di schema), è necessario utilizzare l'API JavaScript per richiamare il servizio.
    3. Per individuare le informazioni necessarie sul servizio REST che si desidera richiamare, ad esempio il nome dell'operazione, i parametri (incluse le intestazioni), i requisiti di sicurezza e la struttura oggetto di risposta, fare clic sulla scheda Origine per il servizio esterno per visualizzare l'origine della specifica OpenAPI .
      Per ulteriori informazioni sul servizio, consultare la configurazione del server REST per il servizio esterno.
  3. Controllare il certificato del server per il servizio REST che si desidera richiamare.
    Utilizzando JavaScript , è possibile sovrascrivere qualsiasi configurazione SSL specificata come parte del server REST.
    1. Se il certificato del server è firmato da un'autorità di certificazione pubblica, è possibile utilizzare la configurazione SSL preconfigurata denominata PublicInternetSSLSettings.
    2. Se il certificato server non è firmato da una delle autorità di certificazione pubbliche incluse nella configurazione SSL preconfigurata, un amministratore deve creare una nuova configurazione SSL per questo servizio e importare il certificato server in un nuovo truststore. Consultare Ambienti cloud operativi.
  4. Se si dispone già di un flusso di servizi definito, selezionarlo. Altrimenti, create un flusso di servizi facendo clic su Servizi > + > Flusso di servizi. Per ulteriori informazioni sulla creazione di un flusso di servizi, consultare Creazione di un flusso di servizi.
  5. Aggiungere un'attività script al flusso di servizio.
  6. Aggiungere JavaScript all'attività script per eseguire le seguenti azioni.
    1. Creare una nuova istanza dell'oggetto richiesta. Ad esempio:
      var request = new BPMRESTRequest();
    2. Impostare gli attributi dell'oggetto request come necessario, come il nome del servizio esterno obbligatorio, il nome dell'operazione, le intestazioni HTTP e i parametri dell'operazione e gli attributi opzionali come le credenziali e il nome della configurazione SSL.
      Gli attributi specificati nell'oggetto richiesta sovrascrivono i valori corrispondenti specificati come parte del server REST e il bind per il servizio esterno nel designer.
      L'oggetto richiesta ha i seguenti attributi:
      externalServiceName
      Il nome del servizio REST. Ad esempio:
      request.externalServiceName = "language-translator-v2";
      operationName
      Se il file di specifica OpenAPI specifica un operationId per l'operazione che si desidera richiamare, è necessario specificarlo come operationName, altrimenti è necessario specificare httpMethod e path. Ad esempio:
      request.operationName="checkout";
      httpMethod e path
      Se il file di specifica OpenAPI non specifica un operationId per l'operazione, per identificare l'operazione da invocare è necessario specificare il metodo HTTP e il percorso invece della proprietà operationName. Ad esempio:
      request.httpMethod = "GET";
request.path = "/v1/orders";
      endpointAddress
      Facoltativamente, sovrascrive lo schema, il nome host, la porta e il percorso di base specificati nel file di specifica OpenAPI . Ad esempio:
      request.endpointAddress = "https://localhost:9080/restBasePath";
      httpHeaders
      Un oggetto JSON che specifica le intestazioni HTTP. Ad esempio:
      request.httpHeaders = {"Content-Type": "application/json", 
                       "Accept": "text/plain"};
      Importante : se l'operazione che si desidera richiamare ha un parametro del corpo, è necessario specificare l'intestazione Content-Type in modo che corrisponda al tipo di contenuto fornito, altrimenti si potrebbero ottenere risultati imprevedibili. I valori e i nomi dei campi di intestazione della richiesta non vengono convalidati.
      Per formData:
      • Se include un file, specificare il tipo di contenuto multipart/form-data.
      • Se non include un file, specificare il tipo di contenuto multipart/form - data o application / x - www - form - urlencoded.
      Importante: se si specifica una chiave API in un'intestazione HTTP, questa sovrascrive qualsiasi chiave API dinamica specificata nella scheda di mappatura dei dati dell'attività di servizio, che sovrascrive qualsiasi chiave API specificata nella scheda di binding del servizio REST esterno.
      parameters
      Un oggetto JSON che contiene tutti i parametri necessari per l'operazione. Ad esempio:
      request.parameters = {"priority": "high",
                      "customer": "Max", 
                      "age" : 23};
      I parametri possono essere anche tipi complessi. In questo caso, specificarli in uno dei seguenti modi:
      request.parameters = {"priority": "high",
                      "customerInfo": { "customerFirstName" : "Max",
                                        "customerLastName" : "Smith",
                                        "amount" : 100.56,
                                        "isActive" : true }};
      oppure
      request.parameters = {"priority": "high",
                      "customerInfo": tw.local.customerInfo};
      dove la variabile customerInfo è di tipo complesso CustomerInfo, con le proprietà customerLastName (String), customerFirstName (String), amount (Decimal) e isActive (Boolean).
      Importante: per assicurarsi che una proprietà di tipo integer all'interno di un tipo complesso venga interpretata correttamente come un numero intero, deve essere specificata come una variabile di tipo Integer.
      requestTimeout
      Il tempo in millesimi di secondo di attesa fino al timeout della richiesta. Ad esempio:
      request.requestTimeout = 2000;
      responseTimeout
      Il tempo di attesa, in millisecondi, fino al timeout della risposta. Ad esempio:
      request.responseTimeout = 7200;
      username e password
      Il nome utente e la password, quando si utilizza l'autenticazione di base. Ad esempio:
      request.username = "user";
request.password = "password";
      invocationCredential
      Fornire le credenziali di richiamo invece di username e password per l'autenticazione di base. Ad esempio:
      request.invocationCredential = "MyAuthenticationAlias";
      sslConfiguration
      Il nome della configurazione SSL da utilizzare. Ad esempio:
      request.sslConfiguration = "MySSLConfiguration";
      Importante: assicurati di passare i valori corretti richiesti per una corretta chiamata REST. I valori vengono passati al servizio REST senza convalida.
    3. Richiamare la funzione tw.system.invokeREST() sull'oggetto richiesta, assegnando il risultato ad un nuovo oggetto risposta di tipo BPMRESTResponse().
      Ad esempio:
      var response = tw.system.invokeREST(request);
      Suggerimento : se si riceve il seguente errore:
      javax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.h:
PKIX path building failed ...
      È necessario richiedere all'amministratore di creare una configurazione SSL e importare il certificato server, come descritto nel passo 3.b.
      Suggerimento : se si riceve il seguente errore:
      javax.net.ssl.SSLHandshakeException: Remote host closed connection during handshake

      Il protocollo SSL/TLS specificato nella configurazione SSL e l'intervallo di protocolli SSL / TLS supportati dal server non corrispondono. È necessario richiedere all'amministratore del server di modificare il protocollo SSL/TLS, nella sezione Impostazioni QoP (Quality of protection) della configurazione SSL.

    4. Elaborare la risposta come necessario.
      In genere si controlla il codice di stato HTTP per vedere se la richiesta è andata a buon fine. Se si è verificato un errore, è possibile gestirlo nell'attività di script stessa oppure assegnare valori alle variabili per consentire la gestione di errori differenti nel proprio flusso di servizio. Si noti che è anche possibile rilevare le eccezioni nel codice script Java utilizzando un blocco try / catch, altrimenti l'eccezione terminerà lo script. Il seguente esempio mostra come accedere al codice di stato HTTP, al messaggio di stato HTTP, alle intestazioni HTTP della risposta e al contenuto della risposta nel task di script.
      // Evaluate the response and process as necessary
var httpStatusCode = response.httpStatusCode;
var httpStatusMessage = response.httpStatusMessage;
var httpHeaders = response.httpHeaders;
var content = response.content;
      Nota: non è possibile memorizzare direttamente la risposta in una variabile del flusso di servizio; ciò produrrebbe l'errore Java Class com.lombardisoftware.core.script.js.BPMRESTResponseScriptable is not registered as supported class for the SymbolTable. È invece possibile estrarre le proprietà di questo oggetto e memorizzarle in variabili di flusso del servizio singolarmente o come parte di un oggetto di business.
      Suggerimento: per un esempio di codice di gestione errori, consultare Gestione degli errori del servizio REST.
    Per ulteriori informazioni sull'oggetto di richiesta BPMRESTRequest() e sull'oggetto di risposta BPMRESTResponse , vedi APIJavaScript.
  7. Fare clic su Salva o Termina modifica.