websocket-upgrade

在线编辑

使用 websocket-upgrade 策略通过 WebSocket 连接处理 API 请求和响应。

网关支持

表 1. 显示哪些网关支持此策略以及对应策略版本的表格
网关 策略版本
DataPower® API Gateway 2.0.0

本主题介绍了如何在 OpenAPI 源中配置策略；有关如何在Assembly用户界面中配置策略的详细信息，请参阅 “WebSocket升级 ”。

websocket-upgrade 策略具有以下格式:
- websocket-upgrade:
  version: version
  title: title
  description: description
  target-url: URL_of_target_API
  tls-profile: TLS_profile_to_be_used
  timeout: timeout_value_in_seconds
  follow-redirects: redirect_behavior_on_301_error
  username: username_if_authentication_required
  password: password_if_authentication_required
  inject-proxy-headers: are_proxy_headers_sent_to_target_url
  decode-request-params: are_request_parameters_decoded
  encode-plus-char: are_plus_characters_encoded
  header-control:
        .
        .
        .
    headers_to_copy_to_target_url
        .
        .
        .
  parameter-control:
        .
        .
        .
    parameters_to_copy_to_target_url
        .
        .
        .

属性

表 2. websocket-upgrade 策略属性
属性 必需 描述 数据类型
version 是 策略版本号。 字符串
title False 策略的标题。 字符串
description False 对策略的描述。 字符串
target-url 是 指定要调用的 URL。 字符串
tls-profile False 指定用于数据的安全传输的 TLS 概要文件。 字符串
timeout False 在端点回复前的等待时间（秒）。

缺省值为 60。

 整数
follow-redirects False 指定后端服务器返回 HTTP 状态代码 301 Moved Permanently 时的行为。 如果该属性设置为 true，那么 invoke 策略会通过进一步调用响应的 Location 头中指定的 URL 来跟随 URL 重定向。 如果该属性设置为 false，那么 invoke 会保存 301 状态码，并且此 API 调用将被视为已完成。
注: follow-redirect 属性仅受 DataPower API Gateway支持。 如果您使用的是 DataPower Gateway (v5 compatible)，则 始终 invoke 会遵循 URL 的重定向；而 proxy 策略（不被 支持 DataPower API Gateway）会保存 状态 301 码，并在不遵循 URL 重定向的情况下完成 API 调用。
 布尔型
username False 用于 HTTP 基本认证的用户名。 字符串
password False 用于 HTTP 基本认证的密码。 字符串
inject-proxy-headers False 设置为 true 时，invoke 策略会将 X-Forwarded-For、X-Forwarded-To、X-Forwarded-Host 和 X-Forwarded-Proto 头插入发送至 target-url 的请求。

缺省值为 false。

 布尔型
decode-request-params False 设置为 true 时，那么会针对 invoke 策略的 target-url 上的变量定义引用的任何请求参数进行 URL 解码。

缺省值为 false。

 布尔型
encode-plus-char False 设置为 true 时，target-url 的查询参数值中的所有“+”字符都将编码为 %2F。

缺省值为 false。

 布尔型 
header-control:
  type
  values
 False 在 message.headers 中指定要复制到目标 URL 的头。

如果 type 属性设置为 blocklist，那么 values 属性会列示您不想要复制的头。 如果 values 属性为空，那么将复制所有头。

如果 type 属性设置为 allowlist，那么 values 属性会列示您想要复制的头。

values 属性中列示的项采用正则表达式格式。 这些值不区分大小写。 header-control 属性的缺省值为
header-control:
  type: blocklist
  values: []

请参阅 标头控制示例

 对象 
parameter-control:
  type
  values
 False 在入局请求中指定要复制到目标 URL 的参数。

如果 type 属性设置为 blocklist，那么 values 属性会列示您不想要复制的参数。

如果 type 属性设置为 allowlist，那么 values 属性会列示您想要复制的参数。 如果 values 属性为空，那么将不复制任何参数。

values 属性中列示的项采用正则表达式格式。 这些值不区分大小写。 parameter-control 属性的缺省值为
parameter-control:
  type: allowlist
  values: []

请参阅 参数控制示例

 对象 
request-assembly:
  execute
     .
     .
     .
    policy assembly
     .
     .
     .
 False 请求处理组合件。 有关在 execute 部分中配置组合件的详细信息，请参阅 execute。 对象 
response-assembly:
  execute
     .
     .
     .
    policy assembly
     .
     .
     .
 False 响应处理组合件。 有关在 execute 部分中配置组合件的详细信息，请参阅 execute。 对象

示例

- websocket-upgrade:
  version: 2.0.0
  title: websocket-upgrade
  timeout: 60
  target-url: 'https://my.websocket.upgrade.com'
  secure-gateway: false
  follow-redirects: true
  inject-proxy-headers: true
  decode-request-params: false
  encode-plus-char: true
  response-assembly:
    execute:
      - parse:
          version: 2.0.0
          title: parse
          parse-settings-reference:
            default: apic-default-parsesettings
          description: Parse the response from the backend server

header-control 示例

# copy all headers to the target URL

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: blocklist
      values: []
# copy all headers except X-Client-ID and Content-Type

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: allowlist
      values:
        - ^X-Client-ID$
        - ^Content-Type$
# copy no headers

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: allowlist
      values: []
# copy only the Content-Type header

- invoke:
    target-url: http://myhost/mypath
    header-control:
      type: allowlist
      values:
        - ^Content-Type$

parameter-control 示例

# copy no request parameters to the target URL

- invoke:
    target-url: http://myhost/path?storeid=3
    parameter-control:
      type: allowlist
      values: []
# append the petid parameter to the target URL
# if the incoming request is http://apigw/org/sandbox/petstore/base?petid=100&display=detailed, 
# the target URL at runtime will be http://myhost/mypath?storeid=3&petid=100

- invoke:
    target-url: http://myhost/path?storeid=3
    parameter-control:
      type: allowlist
      values:
        - ^petid$