通过使用 JavaScript 调用 REST 服务

在线编辑

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

关于本任务

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

过程

确保您针对 REST 服务拥有 OpenAPI（以前称为“Swagger”）规范文件的 URL 或本地副本以及所有必需的调用凭证，以便能够调用 REST 服务。
创建外部服务并发现受支持的操作:
1. 打开设计器，然后选择服务 > + > 外部服务 > 发现现有服务，然后选择 OpenAPI 规范文件作为输入。有关发现外部 REST 服务的更多信息，请参阅调用 REST 服务。
2. 如果无法从服务任务调用任何发现的操作，那么可以单击查看说明以获取更多信息。如果您要调用的已发现服务操作可以选择为服务流中服务任务的实现，那么这将更简单。如果要使用 application/json 以外的类型 (或者 application/x-www-form-urlencoded 具有基本值或数组具有基本值，或者 text/plain 具有模式类型字符串) ，那么必须使用 JavaScript API 来调用服务。
3. 要查找有关要调用的 REST 服务 (例如操作名称，参数 (包括头) ，安全性需求和响应对象结构) 的信息，请单击外部服务的源选项卡以查看 OpenAPI 规范源。
  有关服务的其他信息，请参阅外部服务的 REST 服务器配置。
检查要调用的 REST 服务的服务器证书。
使用 JavaScript，可覆盖指定为 REST 服务器的一部分的任何 SSL 配置。
1. 如果服务器证书由公共认证中心签署，那么可以使用名为 PublicInternetSSLSettings的预配置 SSL 配置。
2. 如果服务器证书不是由预配置 SSL 配置中包含的某家公共认证中心签署，那么管理员应该为此服务创建新的 SSL 配置，并将服务器证书导入到新的信任库。有关管理 SSL 配置的信息，请参阅创建安全套接字层配置和从远程 SSL 端口检索签署者。
如果已定义服务流，请选择。否则，通过单击服务 > + > 服务流来创建服务流。有关创建服务流的更多信息，请参阅创建服务流。
向服务流添加脚本任务。
将 JavaScript 添加到脚本任务中以执行如下操作。
1. 创建请求对象的新实例。例如：
```
var request = new BPMRESTRequest();
```
2. 根据需要设置请求对象属性（如操作的必需外部服务名称、操作名称、HTTP 头和参数），以及诸如凭证和 SSL 配置名称等可选属性。
  在请求对象中指定的任何属性都将覆盖在设计器中作为外部服务的 REST 服务器和绑定的一部分指定的任何相应值。
  请求对象具有以下属性：
  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"};
  
  重要信息: 如果要调用的操作具有主体参数，那么必须指定 Content-Type 头以匹配您提供的内容类型，否则可能会产生不可预测的结果。未验证请求头字段名称和值。
  
  对于 formData：
  
  如果它包含文件，请指定内容类型 multipart/form-data。
  
  如果它不包含文件，请指定内容类型 multipart/form-data 或 application/x-www-form-urlencoded。
  
  重要提示：如果您HTTP指定了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 调用所需的正确值。值将传递到 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。
单击保存或完成编辑。