通过使用 JavaScript 调用 REST 服务

在服务流中从脚本任务调用 REST 服务。 这允许您在 Web Process Designer 中的服务流中调用无法选择为服务任务的实施的服务操作。

关于此任务

通过使用 JavaScript 来调用 REST 服务，您将对设置输入参数、请求头和认证信息以及处理输出参数和错误具有更强的功能和控制能力。

过程

  1. 确保您针对 REST 服务拥有 OpenAPI（以前称为“Swagger”）规范文件的 URL 或本地副本以及所有必需的调用凭证，以便能够调用 REST 服务。
  2. 使用 Web Process Designer 创建外部服务。 并发现支持哪些操作：
    1. 在 Process App 中，选择服务 > + > 外部服务 > 发现现有服务，然后选择 OpenAPI 规范文件作为输入。 有关发现外部 REST 服务的更多信息，请参阅调用 REST 服务。
    2. 如果无法从服务任务调用任何已发现操作，那么可以单击查看解释以获取更多信息。 如果您要调用的已发现服务操作可以选择为服务流中服务任务的实现，那么这将更简单。 如果要使用除 application/json 以外的类型（具有基本值的  V21.0.2  或 application/x-www-form-urlencoded、具有基本值的数组或具有模式类型字符串的 text/plain），那么必须使用 JavaScript API 来调用该服务。
    3. 要查找有关要调用的 REST 服务的所需信息（如操作名称、参数（包含头）、安全需求以及响应对象结构），请单击外部服务的源选项卡来查看 OpenAPI 规范源。
      有关服务的其他信息，请参阅外部服务的 REST 服务器配置。
  3. 检查要调用的 REST 服务的服务器证书。
    使用 JavaScript，可覆盖指定为 REST 服务器的一部分的任何 SSL 配置。
    1. 如果服务器证书由公共认证中心签署，那么您可以使用名为 PublicInternetSSLSettings 的预先配置的 SSL 配置。
    2. 如果服务器证书不是由预配置 SSL 配置中包含的某家公共认证中心签署，那么管理员应该为此服务创建新的 SSL 配置，并将服务器证书导入到新的信任库。 有关管理 SSL 配置的信息，请参阅创建安全套接字层配置和从远程 SSL 端口检索签署者。
  4. 如果已定义服务流，请选择。 否则，请单击服务 > + > 服务流来创建服务流。 有关创建服务流的更多信息，请参阅创建服务流。
  5. 在 Web Process Designer 中，向服务流添加脚本任务。
  6. 将 JavaScript 添加到脚本任务中以执行如下操作。
    1. 创建请求对象的新实例。 例如： 
      var request = new BPMRESTRequest();
    2. 根据需要设置请求对象属性（如操作的必需外部服务名称、操作名称、HTTP 头和参数），以及诸如凭证和 SSL 配置名称等可选属性。
      在请求对象中指定的任何属性将覆盖作为 REST 服务器的一部分指定的任何对应值以及 Process Designer 中外部服务的绑定。
      请求对象具有以下属性：
      externalServiceName
      REST 服务的名称。 例如：
      request.externalServiceName = "language-translator-v2";
      operationName
      如果 OpenAPI 规范文件为要调用的操作指定 operationId，那么必须将其指定为 operationName，否则，必须指定 httpMethod 和 path。 例如：
      request.operationName="checkout";
      httpMethod 和 path
      如果 OpenAPI 规范文件未对该操作指定 operationId，那么为了识别要调用的操作，您必须指定 HTTP 方法和路径，而不是 operationName 属性。 例如：
      request.httpMethod = "GET";
request.path = "/v1/orders";
      endpointAddress
      （可选）覆盖 OpenAPI 规范文件中指定的方案、主机名、端口和基本路径。 例如：
      request.endpointAddress = "https://localhost:9080/restBasePath";
      httpHeaders
      指定 HTTP 头的 JSON 对象。 例如：
      request.httpHeaders = {"Content-Type": "application/json", 
                       "Accept": "text/plain"};
      要点： 如果要调用的操作具有 body 参数，那么必须指定 Content-Type 头以与您提供的内容类型匹配，否则，您可能会获得不可预测的结果。 请求头字段名称和值未由 IBM® Business Automation Workflow 验证。
      对于 formData：
      • 如果它包含文件，请指定内容类型 multipart/form-data。
      • 如果它不包含文件，请指定内容类型 multipart/form-data 或 application/x-www-form-urlencoded。
      要点： 如果在 HTTP 头中指定 API 密钥，那么它会覆盖服务任务的数据映射选项卡上指定的任意动态 API 密钥，而此动态 API 密钥会覆盖外部 REST 服务绑定选项卡上指定的任意 API 密钥。
      parameters
      包含操作的所有必需参数的 JSON 对象。 例如：
      request.parameters = {"priority": "high",
                      "customer": "Max", 
                      "age" : 23};
      这些参数也可以是复杂类型。 在此案例中，使用下列一种方法来指定：
      request.parameters = {"priority": "high",
                      "customerInfo": { "customerFirstName" : "Max",
                                        "customerLastName" : "Smith",
                                        "amount" : 100.56,
                                        "isActive" : true }};
      或
      request.parameters = {"priority": "high",
                      "customerInfo": tw.local.customerInfo};
      其中变量 customerInfo 为复杂类型 CustomerInfo，它具有属性 customerLastName (String)、customerFirstName (String)、amount (Decimal) 和 isActive (Boolean)。
      要点： 要确保将复杂类型中类型为 integer 的属性正确解释为整数，必须将该属性指定为类型为 Integer 的变量。
      requestTimeout
      请求超时前的等待时间（毫秒）。 例如：
      request.requestTimeout = 2000;
      responseTimeout
      响应超时前的等待时间（毫秒）。 例如：
      request.responseTimeout = 7200;
      username 和 password
      使用基本认证时的用户名和密码。 例如：
      request.username = "user";
request.password = "password";
      invocationCredential
      提供用于基本认证的调用凭证，而不是 username 和 password。 例如：
      request.invocationCredential = "MyAuthenticationAlias";
      sslConfiguration
      要使用的 SSL 配置的名称。 例如：
      request.sslConfiguration = "MySSLConfiguration";
      要点： 确保传递成功调用 REST 时所需的正确值。 Business Automation Workflow 会将值传递至 REST 服务而不对其进行验证。
    3. 对请求对象调用 tw.system.invokeREST() 函数，并将结果分配给类型为 BPMRESTResponse() 的新响应对象。
      例如：
      var response = tw.system.invokeREST(request);
      提示： 如果发生了以下错误：
      javax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.h:
PKIX path building failed ...
      那么必须让管理员创建 SSL 配置并导入服务器证书，如步骤 3.b 中所述。
      提示： 如果发生了以下错误：
      javax.net.ssl.SSLHandshakeException: Remote host closed connection during handshake

      在 SSL 配置中指定的 SSL/TLS 协议与服务器支持的 SSL/TLS 协议范围不匹配。 必须让服务器管理员在 SSL 配置的保护质量 (QoP) 设置部分中更改 SSL/TLS 协议。

    4. 根据需要处理响应。
      通常，检查 HTTP 状态码以了解请求是否成功。 如果有错误，您可以在脚本任务本身中处理它，也可以将值分配给变量以允许 处理服务流中的不同错误。 请注意，您也可以使用 try/catch 块捕获 Java 脚本代码中的异常，否则异常将结束脚本。 以下示例片段显示了如何访问 HTTP 状态码、HTTP 状态消息、响应的 HTTP 头以及脚本任务中的响应内容。
      // Evaluate the response and process as necessary
var httpStatusCode = response.httpStatusCode;
var httpStatusMessage = response.httpStatusMessage;
var httpHeaders = response.httpHeaders;
var content = response.content;
      切记： 您无法直接将响应存储在服务流变量中；这将产生错误 Java Class com.lombardisoftware.core.script.js.BPMRESTResponseScriptable is not registered as supported class for the SymbolTable。 可以改为抽取此对象的属性，并将它们单独或者作为业务对象的一部分存储在服务流变量中。
      提示： 有关错误处理代码示例，请参阅处理 REST 服务错误。
    有关 BPMRESTRequest() 请求对象和 BPMRESTResponse 响应对象的更多信息，请参阅 JavaScript API。
  7. 单击保存或完成编辑。