You need to enable JavaScript to run this app.
导航
边缘计算节点
  • 文档首页
    • /边缘计算节点/边缘计算节点/API 参考/七层负载均衡/添加转发规则
添加转发规则
最近更新时间：2024.07.18 11:03:32首次发布时间：2024.07.02 10:22:48
我的收藏

本接口用于添加转发规则。转发规则指定如何将来自客户端的请求转发到后端服务器。

使用说明

前提条件：

  • 后端服务器类型为边缘实例时，负载均衡实例所属的节点下须存在边缘实例。如需创建边缘实例，请参考创建边缘服务或新增边缘实例。
  • 后端服务器类型为边缘容器时，负载均衡实例所绑定的边缘应用下须存在工作负载，且该工作负载已配置了容器端口用于与外部通信。相关操作，请参考创建边缘应用。

说明

边缘容器目前处于公测阶段。如需使用边缘容器，请提交公测申请。

请求说明

  • 请求方式：POST
  • 请求地址：https://veenedge.volcengineapi.com/?Action=AddRule&Version=2021-04-30

请求参数

下表列出了接口特定的请求参数以及公共请求参数 Action 和 Version。 其他公共参数，请参见公共参数。

Query

参数类型是否必选示例值描述
ActionString是AddRule接口名称。当前 API 的名称为 AddRule。
VersionString是2021-04-30接口版本。当前 API 的版本为 2021-04-30。

Body

参数类型是否必选示例值描述
lb_identityString是veew-lb79442102222490330****负载均衡实例的 ID。您可以调用 ListLB7Instances 接口查询负载均衡实例的 ID。
listener_identityString是res-0094030018300329****监听器的 ID。您可以调用 ListLB7Listener 接口查询监听器的 ID。

name

String

是

rule_01

转发规则的名称。同一火山引擎账号下的转发规则的名称必须唯一。
命名规则如下：

  • 允许 5~20 个字符。
  • 支持汉字、英文大小写字母、数字。
  • 支持特殊字符 ()`~!@#$%^&*-+=_|{}[]:;'<>,.?/。 |
  • 不能包含双引号（"）、反斜线（ \）和空格，且不能以正斜线（/）开头。
domainString是www.example.com域名。该域名需已添加到边缘计算节点服务中。添加域名的具体操作，请参见添加域名。

ssl_type

Integer

否

1

SSL 解析方式。取值范围：

  • 1：单向认证。仅验证服务器身份。该认证方式下，您还需指定 server_cert_ref_list。
  • 2：双向认证。验证服务器身份和客户端身份。该认证方式下，您还需指定 server_cert_ref_list 和 client_cert_ref。

说明

该参数仅适用于 HTTPS 监听器。使用 HTTPS 监听器时，必须指定该参数。

client_cert_ref

String

否

cert-f8791e48c42e4f199b7d70be4****

客户端 CA 证书的 ID。证书必须是“已签发”状态且在有效期内。
如果 ssl_type 被设置为 2，则必须指定 client_cert_ref。您可以调用 CertificateGetInstance 接口获取证书 ID。

说明

该参数仅适用于 HTTPS 监听器。

server_cert_ref_list

[]String

是

[cert-a8f0ebf5c21e4c439e9d7341684c****]

  • 对于 HTTPS 监听器：
    服务器证书的 ID。证书必须是“已签发”状态且在有效期内。
    如果您指定了 ssl_type，则必须指定 server_cert_ref_list。您可以调用 CertificateGetInstance 接口获取证书 ID。
  • 对于 HTTP 监听器：
    参数值须指定为 null。
path_list[]PathList是见下文说明转发路径列表。

custom_param

CustomParam

否

见下文说明

自定义参数。

说明

该参数仅适用于以下场景：后端服务器为边缘容器。

custom_retry_list

[]CustomRetryList

否

见下文说明

自定义重试规则。

说明

该参数仅适用于以下场景：后端服务器为边缘容器。

PathList

参数类型是否必选示例值描述

path

String

是

/test

转发路径。取值须符合以下要求：

  • 必须以正斜线（/）开头。
  • 只能包含英文字母、数字和特殊字符-./%?#&。
  • 允许 1~128 个字符。
rs_groupRsGroup是见下文说明后端服务器组的信息。

RsGroup

参数类型是否必选示例值描述

loadbalance_strategy

String

是

sph

负载均衡策略。取值范围：

  • wrr：轮询。
  • wlc：最小连接数。
  • sh：源 IP 一致性哈希。
  • sph：源 IP +端口一致性哈希。
health_checkHealthCheck否见下文说明健康检查配置。如果不配置 health_check，代表不开启健康检查。
sticky_sessionStickySession否见下文说明会话保持配置。如果不配置 sticky_session，代表不开启会话保持。
rs_list[]RsList是见下文说明后端服务器的列表。

HealthCheck

参数类型是否必选示例值描述

protocol

String

是

HTTP

健康检查协议。取值范围：

  • TCP
  • HTTP

port

Integer

否

80

健康检查端口。取值范围：1~65535。
如果不指定该参数，将使用后端服务器端口作为健康检查端口。

interval

Integer

是

2

健康检查间隔。
取值范围：1~50。单位：秒。

response_timeout

Integer

是

5

响应超时时间。在指定时间内，如果监听器没有收到后端服务器的响应，则判定为响应超时。
取值范围：1~300。单位：秒。

unhealth_threshold

Integer

是

3

不健康阈值，即连续健康检查失败的次数上限。超过这个阈值，后端服务器将被认定为异常，然后会被从服务器池中移除。
取值范围：2~5。单位：次。

health_threshold

Integer

是

3

健康阈值，即连续健康检查成功的次数上限。超过这个阈值，后端服务器将被认定为正常，然后会被重新添加到服务器池。
取值范围：2~5。单位：次。

http_host

String

否

www.example.com

健康检查域名。取值须符合以下要求：

  • 允许 4~63 个字符。
  • 允许英文大小写字母、数字和句点（.）。
  • 至少须包含一个句点（.）。但是句点（.）不能位于开头和结尾。

说明

该参数仅适用于 HTTP 健康检查。健康检查协议为 HTTP 时，必须指定该参数。

http_path

String

否

/test

检查路径。检查路径是用于健康检查的页面的 URL。建议配置静态页面的 URL。
取值须符合以下要求：

  • 检查路径必须以正斜线（/）开头。
  • 长度不能超过 80 个字符。
  • 允许使用英文字母、数字、以及以下特殊字符：-/.%?#&_;~!()*[]@$^:',+。

说明

该参数仅适用于 HTTP 健康检查。健康检查协议为 HTTP 时，必须指定该参数。

http_success_codes

String

否

Code2xx

表示健康检查成功的状态码。多个状态码之间使用半角逗号（,）分隔。取值范围：

  • Code2xx
  • Code3xx
  • Code4xx
  • Code5xx
    当实际响应状态码在您配置的状态码区间内时，表示健康检查成功、服务器状态正常。
    当实际响应状态码不在您配置的状态码区间内时，表示健康检查失败、服务器状态异常。

说明

该参数仅适用于 HTTP 健康检查。健康检查协议为 HTTP 时，必须指定该参数。

http_method_type

String

否

GET

健康检查方法。取值范围：

  • GET
  • HEAD

说明

该参数仅适用于 HTTP 健康检查。健康检查协议为 HTTP 时，必须指定该参数。

http_version

String

否

1.1

HTTP 协议版本。取值范围：

  • 1.1

说明

该参数仅适用于 HTTP 健康检查。健康检查协议为 HTTP 时，必须指定该参数。

StickySession

参数类型是否必选示例值描述

cookie_deal_type

Integer

是

1

Cookie 处理方式。取值范围：

  • 1：植入Cookie。负载均衡实例收到来自客户端的首次请求时，会根据调度算法选择一个后端服务器，并在响应中植入Cookie（即在HTTP或HTTPS响应报文中插入SERVERID）。当后续的客户端请求携带此Cookie时，负载均衡实例会将请求转发给对应的后端服务器。
  • 2：重写Cookie。用户可以自定义Cookie。当负载均衡实例发现用户自定义了Cookie时，会对原来的Cookie进行改写。当后续的客户端请求携带改写后的Cookie时，负载均衡实例会将请求转发给对应的后端服务器。

cookie_timeout

Integer

否

120

会话保持超时时间。
取值范围：1~200。单位：秒。

说明

当 cookie_deal_type 值为 1 时，必须指定 cookie_timeout。

cookie_name

String

否

custom

Cookie 名称。取值需满足以下要求：

  • 允许 1~200 个字符。
  • 允许英文大写字母、英文小写字母、数字。

说明

当 cookie_deal_type 值为 2 时，必须指定 cookie_name。

RsList

参数类型是否必选示例值描述

identity

String

是

veen1283900037022992****

后端服务器的 ID。
后端服务器为边缘实例时，须指定边缘实例的 ID。后端服务器为边缘容器时，须指定工作负载的 ID。

portInteger是80后端服务器的端口。

weight

Integer

是

50

后端服务器的权重。单位：%。

说明

该参数仅适用于以下场景：后端服务器为边缘实例。

CustomParam

参数类型是否必选示例值描述
proxy_body_sizeString否1024k代理服务器接收的请求体大小。取值范围：1~1024。取值需要包含单位：k/K，m/M 或 g/G。

ssl_buffer_size

String

否

16k

缓冲区大小。取值范围：

  • 1~32（带单位 k/K 时）
  • 1~1024（不带单位 k/K 时）

说明

该参数仅适用于 HTTPS 监听器。

CustomRetryList

参数类型是否必选示例值描述

status_code

String

是

500

状态码。多个状态码之间使用半角逗号（,）分隔。最多允许 5 个状态码。
取值范围：300~599。

application_identityString是veecc-255622122036230****边缘应用 ID。您可以调用 ListApplications 获取边缘应用的列表。
workload_identityString是res-4201065452244652****工作负载 ID。您可以调用 ListWorkloads 获取工作负载的列表。
portInteger是80Service 端口。

返回参数

参数类型示例值描述
rule_identityStringres-1004006130411632****转发规则的 ID。

请求示例

POST https://veenedge.volcengineapi.com/?Action=AddRule&Version=2021-04-30
{
    "lb_identity": "veew-lb70204100444012074****",
    "listener_identity": "res-4044414421464414****",
    "name": "rule_01",
    "domain": "www.example.com",
    "server_cert_ref_list": [
        null
    ],
    "path_list": [
        {
            "path": "/test",
            "rs_group": {
                "loadbalance_strategy": "wrr",
                "health_check": {
                    "protocol": "HTTP",
                    "port": 80,
                    "interval": 2,
                    "response_timeout": 5,
                    "unhealth_threshold": 3,
                    "health_threshold": 3,
                    "http_host": "www.example.com",
                    "http_path": "/test",
                    "http_success_codes": "Code2xx",
                    "http_method_type": "GET",
                    "http_version": "1.1"
                },
                "sticky_session": {
                    "cookie_deal_type": 1,
                    "cookie_timeout": 120
                },
                "rs_list": [
                    {
                        "identity": "veen0642211172016766****",
                        "port": 80,
                        "weight": 50
                    }
                ]
            }
        }
    ]
}

返回示例

{
    "ResponseMetadata": {
        "RequestId": "20240619140928829F950358C1DD26****",
        "Action": "AddRule",
        "Version": "2021-04-30",
        "Service": "veenedge",
        "Region": "cn-north-1"
    },
    "Result": {
        "rule_identity": "res-0444414400190294****"
    }
}

错误码

如果响应正文中包含 Error 字段，则表示 API 请求失败。关于错误码的更多信息，参见错误码。