将本地环境变量用于 REST 节点

REST 请求节点支持许多本地环境消息树变量，可以使用这些变量动态变更该节点的属性中设置的值。

下表显示了 LocalEnvironment.Destination.REST.Request 消息树中的元素，这些元素可用于覆盖 RESTRequest 和 RESTAsyncRequest 节点中的属性。 局部环境变量设置的任何属性都将应用于 RESTRequest 和 RESTAsyncRequest 节点。

该表包含如何使用 ESQL 设置值的示例; 但是，您还可以使用变换节点 (例如， Mapping 节点) 来设置这些值。 要从 映射 节点访问 LocalEnvironment ，请参阅 定制消息映射以包含消息组合件组件。
表 1. 输入本地环境属性
元素名 类型 描述
操作 字符串 值为要在 REST API 中调用的操作的名称。 此环境变量将覆盖节点上的 Operation 属性。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.Operation = 'updateCustomerByID';
参数。parameter_name 字符串 指定要用于操作参数的值。 在 LocalEnvironment 中指定的值将覆盖节点上 Parameters 表中指定的任何字面值或 XPath/ESQL 表达式。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.Parameters.max = 10;
SET OutputLocalEnvironment.Destination.REST.Request.Parameters.filter = 'Fred Bloggs';
注: 如果值是 XPath/ESQL 表达式，那么值将作为字符串字面值 (而不是作为 XPath/ESQL 表达式进行求值) 传递到远程 REST API。

要定义 REST 参数并在消息映射中设置其值，请使用 Add User Defined 函数来添加 parameter_name 元素，然后提供映射以设置其值。 有关更多信息，请参阅 使用 "添加用户定义的函数" 配置局部环境树 Variables 文件夹。
ContentType 字符串 值为要在 REST API 请求中发送的 Content-Type 头的值。 此环境变量将覆盖节点上的 Content-Type 属性。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.ContentType = 'application/vnd.ibm-demo+json';
Accept 字符串 值为要在 REST API 请求中发送的 Accept 头的值。 此环境变量将覆盖节点上的 Accept 属性。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.Accept = 'application/json';
SecurityIdentity 字符串 该值必须是使用 mqsisetdbparms 命令定义的安全身份的名称。 请勿包含“rest::”前缀。 此环境变量将覆盖节点上的 Security identity 属性。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.SecurityIdentity = 'myApiKey';
UserID 字符串 如果指定了此环境变量，那么它将覆盖由节点上的 LocalEnvironment.Destination.REST.Request.SecurityIdentity 覆盖和 Security identity 属性指定的所有值。

如果指定了 LocalEnvironment.Destination.REST.Request.UserID 环境变量，那么还需要指定 LocalEnvironment.Destination.REST.Request.Password 环境变量。
密码 字符串 如果指定了此环境变量，那么它将覆盖由节点上的 LocalEnvironment.Destination.REST.Request.SecurityIdentity 覆盖和 Security identity 属性指定的所有值。

如果指定了 LocalEnvironment.Destination.REST.Request.Password 环境变量，那么还需要指定 LocalEnvironment.Destination.REST.Request.UserID 环境变量。
APIKey 字符串 如果指定了此环境变量，那么它将覆盖由节点上的 LocalEnvironment.Destination.REST.Request.SecurityIdentity 覆盖和 Security identity 属性指定的所有值。

可以单独指定也可以与 LocalEnvironment.Destination.REST.Request.UserID 和 LocalEnvironment.Destination.REST.Request.Password 环境变量一起指定 LocalEnvironment.Destination.REST.Request.APIKey 环境变量。
Timeout 整数 节点等待 REST API 处理操作的时间（以秒计）。 此环境变量将覆盖节点上的 Request timeout (sec) 属性。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.Timeout = 300;
BaseURL 字符串 此环境变量将覆盖节点上的 Base URL override 属性，以及包含 REST API 定义的 Swagger 文档中指定的基本 URL。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.BaseURL = 'https://my-prod-server.ibm.com/customerdb/v1';
ProxyURL 字符串 此环境变量将覆盖节点上的 HTTP(S) proxy location 属性。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.ProxyURL = 'http://my-proxy-server.ibm.com';
FollowRedirection boolean 此环境变量将覆盖节点上的 Follow HTTP(S) redirection 属性。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.FollowRedirection = TRUE;
KeepAlive boolean 此环境变量将覆盖节点上的 Enable HTTP 1/1 keep-alive 属性。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.KeepAlive = FALSE;
Compression 字符串 此环境变量将覆盖节点上的 Compression 属性。 有效值为：
  • gzip
  • zlib-deflate
  • 原始-deflate
例如：
SET OutputLocalEnvironment.Destination.REST.Request.Compression = 'zlib-deflate';
协议 字符串 此环境变量将覆盖节点上的 Protocol 属性。 有效值为：
  • TLS
  • TLSv1
  • TLSv1.2
  • SSL_TLS
  • SSL_TLSv2
例如：
SET OutputLocalEnvironment.Destination.REST.Request.Protocol = 'TLSv1.2';
AllowedCiphers 字符串 此环境变量将覆盖节点上的 Allowed SSL Ciphers 属性。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.AllowedCiphers = 'SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA';
HostnameChecking boolean 此环境变量将覆盖节点上的 Enable SSL certificate hostname checking 属性。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.HostnameChecking = FALSE;
KeyAlias 字符串 此环境变量将覆盖节点上的 SSL client authentication key alias 属性。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.KeyAlias = 'myClientCertificate';
EnableCRLCheck boolean 此环境变量将覆盖节点上的 Enable certificate revocation list checking 属性。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.EnableCRLCheck = TRUE;
AcceptCompressedResponses 字符串 此环境变量将覆盖节点上的 Accept compressed responses by default 属性。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.AcceptCompressedResponses = TRUE;
ServicePrincipalName 字符串 指定集成节点协商 Kerberos 安全协议时使用的服务主体名称 (SPN)。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.ServicePrincipalName = 'HTTP/iib.iibservice2.com:7800';
安全方案。安全方案.安全身份 字符串 指定用于所指定安全方案的安全身份的名称。 指定的安全身份仅用于指定的安全方案。

如果指定了此环境变量，那么它将覆盖节点上的 LocalEnvironment.Destination.REST.Request.SecurityIdentity 覆盖和 Security identity 属性。

安全方案的名称与包含 REST API 定义的 Swagger 文档中安全定义对象内安全方案对象的名称相对应。

该值必须是使用 mqsisetdbparms 命令定义的安全身份的名称。 请勿包含“rest::”前缀。 例如：

SET OutputLocalEnvironment.Destination.REST.Request.SecuritySchemes.petstore_auth.SecurityIdentity = 'myIdentity3'
安全方案。安全方案。用户身份 字符串 指定要在使用 HTTP 基本认证时用于所指定安全方案的用户标识。 指定的用户标识仅用于指定的安全方案。

如果指定了此环境变量，那么它将通过 LocalEnvironment.Destination.REST.Request.SecuritySchemes.security_scheme.SecurityIdentity 或 LocalEnvironment.Destination.REST.Request.SecurityIdentity 覆盖来覆盖在安全身份中指定的用户标识，同时还会覆盖节点上的 Security identity 属性。

安全方案的名称与包含 REST API 定义的 Swagger 文档中安全定义对象内安全方案对象的名称相对应。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.SecuritySchemes.security_scheme.UserID='bob'
SecuritySchemes。security_scheme。密码 字符串 指定要在使用 HTTP 基本认证时用于所指定安全方案的密码。 指定的密码仅用于指定的安全方案。

如果指定了此环境变量，那么它将通过 LocalEnvironment.Destination.REST.Request.SecuritySchemes.security_scheme.SecurityIdentity 或 LocalEnvironment.Destination.REST.Request.SecurityIdentity 覆盖来覆盖在安全身份中指定的密码，同时还会覆盖节点上的 Security identity 属性。

安全方案的名称与包含 REST API 定义的 Swagger 文档中安全定义对象内安全方案对象的名称相对应。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.SecuritySchemes.petstore_auth.Password='myPassword'
SecuritySchemes。security_scheme。APIKey 字符串 指定要在使用 HTTP 基本认证时用于所指定安全方案的 API 密钥。 指定的 API 密钥仅用于指定的安全方案。

如果指定了此环境变量，那么它将通过 LocalEnvironment.Destination.REST.Request.SecuritySchemes.security_scheme.SecurityIdentity 或 LocalEnvironment.Destination.REST.Request.SecurityIdentity 覆盖来覆盖在安全身份中指定的 API 密钥，同时还会覆盖节点上的 Security identity 属性。

安全方案的名称与包含 REST API 定义的 Swagger 文档中安全定义对象内安全方案对象的名称相对应。 例如：
SET OutputLocalEnvironment.Destination.REST.Request.SecuritySchemes.petstore_auth.APIKey='438438920909329039032'
UserContext 混合内容 指定要由 RESTAsyncRequest 节点存储的上下文数据。 稍后可由 RESTAsyncResponse 节点针对匹配请求访问数据。

您可以使用用户上下文来指定将从 RESTAsyncRequest 节点传递到 RESTAsyncResponse 节点的数据。 要存储用户上下文数据，请在 RESTAsyncRequest 节点之前，在 OutputLocalEnvironment.Destination.REST.Request.UserContext 环境变量中设置值，或者在其下创建并填充子节点。

例如，要使用 ESQL 表达式来设置值：
SET OutputLocalEnvironment.Destination.REST.Request.UserContext = 'Some important information';
SET OutputLocalEnvironment.Destination.REST.Request.UserContext.Name.FirstName = 'Fred';
SET OutputLocalEnvironment.Destination.REST.Request.UserContext.Name.Surname = 'Bloggs';
SET OutputLocalEnvironment.Destination.REST.Request.UserContext.MyData.Binary = CAST('A piece of data' AS BLOB CCSID 1208);

您可以使用 映射 节点通过映射到混合子元素 OutputLocalEnvironment.Destination.REST.Request.UserContext.mixed来设置值。 要使用 映射 节点来创建子元素，请使用用户定义的元素或强制类型转换 xsd:any 并映射到这些元素。 有关更多信息，请参阅 RESTAsyncRequest 节点。

要在 RESTAsyncResponse 节点之后访问用户上下文数据，请读取 LocalEnvironment.REST.Response.UserContext 环境变量的值或子代。
QueryStringDoNotPercentEncodeCharacters 字符串 在查询字符串中指定在构建 URI 时不对其进行百分比编码的字符。
例如，要指定不对逗号和大于号进行百分比编码：
SET OutputLocalEnvironment.Destination.REST.Request.QueryStringDoNotPercentEncodeCharacters = ',>';

不进行百分比编码的缺省字符集是星号 (*)、减号 (-)、句点 (.) 和下划线 (_)。
下表显示了 RESTRequest 节点在传播输出消息时写入 LocalEnvironment 的数据:
表 2. RESTRequest 节点生成的输出局部环境属性
元素 类型 描述
LocalEnvironment.WrittenDestination.REST.Method 字符串 在 REST API 中调用操作时使用的 HTTP 方法。
LocalEnvironment.WrittenDestination.REST.URL 字符串 在 REST API 中调用操作时使用的 URL。
LocalEnvironment.WrittenDestination.REST.RequestHeadersSize 整数 发送至 REST API 的请求头的大小。
LocalEnvironment.WrittenDestination.REST.RequestBodySize 整数 发送至 REST API 的请求主体的大小。
LocalEnvironment.WrittenDestination.REST.StatusCode 整数 REST API 响应中的 HTTP 状态码。
LocalEnvironment.WrittenDestination.REST.ResponseHeadersSize 整数 从 REST API 接收的响应头的大小。
LocalEnvironment.WrittenDestination.REST.ResponseBodySize 整数 从 REST API 接收的响应主体的大小。
LocalEnvironment.WrittenDestination.REST.TotalRequestTime 整数 在 REST API 中调用操作时的总耗用时间。
下表显示了 RESTAsyncRequest 节点在传播输出消息时写入的数据:
表 3. RESTAsyncRequest 节点生成的输出本地环境属性:
元素 类型 描述
LocalEnvironment.WrittenDestination.REST.Method 字符串 在 REST API 中调用操作时使用的 HTTP 方法。
LocalEnvironment.WrittenDestination.REST.URL 字符串 在 REST API 中调用操作时使用的 URL。
LocalEnvironment.WrittenDestination.REST.RequestHeadersSize 整数 发送至 REST API 的请求头的大小。
LocalEnvironment.WrittenDestination.REST.RequestBodySize 整数 发送至 REST API 的请求主体的大小。
LocalEnvironment.WrittenDestination.REST.CorrelationID blob 用于在 RESTAsyncRequest 和 RESTAsyncResponse 节点之间关联请求和响应的相关标识。
下表显示了 RESTAsyncResponse 节点在传播输出消息时写入的数据:
表 4. RESTAsyncResponse 节点生成的输出局部环境属性:
元素 类型 描述
LocalEnvironment.REST.Response.CorrelationID blob 用于关联 RESTAsyncRequest 和 RESTAsyncResponse 节点之间请求和响应的相关标识。
LocalEnvironment.REST.Response.StatusCode 整数 REST API 响应中的 HTTP 状态码。
LocalEnvironment.REST.Response.ResponseHeadersSize 整数 从 REST API 接收的响应头的大小。
LocalEnvironment.REST.Response.ResponseBodySize 整数 从 REST API 接收的响应主体的大小。
LocalEnvironment.REST.Response.UserContext 混合内容 响应线程可检索 OutputLocalEnvironment.Destination.REST.Request.UserContext 中存储的信息。