更新 Upstream 配置信息。

请求说明

API 网关已在全球多个地域部署服务，旨在为您提供更稳定、低延迟的访问体验。您可以通过查阅服务地址文档，根据业务所在地域，选择最合适的接入点。

请求方式：POST

请求地址：https://apig.cn-beijing.volcengineapi.com?Action=UpdateUpstream&Version=2021-03-03

调试

API Explorer

您可以通过 API Explorer 在线发起调用，无需关注签名生成过程，快速获取调用结果。

去调试

请求参数

下方仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Action string 必选示例值：UpdateUpstream

要执行的操作，取值：UpdateUpstream。

Version string 必选示例值：2021-03-03

API的版本，取值：2021-03-03。

Id string 必选示例值：ud8t****

Upstream ID。您可以通过 ListUpstreams 查询 Upstream ID。

Name string 必选示例值：example

Upstream 名称。

支持大小写字母、数字和中划线（-），长度限制为 2~63 个字符。

不能以中划线（-）开头。

Comments string 可选示例值：example

Upstream 的备注信息。长度限制为 0~253 个字符。

SourceType string 必选示例值：VeFaas

Upstream 来源类型，取值：

VeFaas：函数服务。

ECS：云服务器。

K8S：容器服务。

Nacos：注册中心。

Domain：固定域名。

FixedIP：固定 IP。

AIProvider：AI 模型代理。

UpstreamSpec object 必选示例值：-

Upstream 配置。

VeFaas object 可选示例值：-

函数服务。

说明

当SourceType取值为VeFaas时，需要配置本参数。

FunctionId string 必选示例值：35v****

函数 ID。您可以通过 ListFunctions 查询函数 ID。

K8SService object 可选示例值：-

容器服务。

说明

当SourceType取值为K8S时，需要配置本参数。

Namespace string 必选示例值：default

Kubernetes Service 所在的命名空间。长度限制为 2~63 个字符。

Name string 必选示例值：example

Kubernetes Service 名称。长度限制为 2~63 个字符。

Port integer 必选示例值：80

Kubernetes Service 开放的端口。

EcsList object[] 可选示例值：-

云服务器。

说明

当SourceType取值为ECS时，需要配置本参数。

EcsId string 必选示例值：i-3tig******

云服务器 ID。您可以通过 DescribeInstances 查询云服务器 ID。

IP string 必选示例值：10.0.0.1

云服务器 IP 地址。

Port integer 必选示例值：80

为 ECS 实例配置访问端口。API 网关只能通过配置的端口访问对应的 ECS。

FixedIPList object[] 可选示例值：-

固定 IP。

说明

当SourceType取值为FixedIP时，需要配置本参数。

IP string 必选示例值：10.0.0.1

后端 IP 地址。

Port integer 必选示例值：80

后端 IP 的端口号。

Domain object 可选示例值：-

固定域名。

说明

当SourceType取值为Domain时，需要配置本参数。

Protocol string 可选示例值：HTTP

协议，取值：

HTTP

HTTP2

GRPC

DomainList object[] 必选示例值：-

域名列表。长度限制为 1 个。

Domain string 必选示例值：example.com

对接后端的固定域名地址。

Port integer 可选示例值：80

对接后端域名的端口号。

协议类型为 HTTP 时，默认值为 80。

协议类型为 HTTPS 时，默认值为 443。

AIProvider object 可选示例值：-

AI 模型代理。

说明

当SourceType取值为AIProvider时，需要配置本参数。

Name string 必选示例值：example

Cookie 名称。支持 ASCII 可打印字符，长度限制为 0~256 个字符。

Token string 可选示例值：ark-6bb****

模型 API key。详情请参见创建 API Key。

BaseUrl string 必选示例值：https://api.openai.com/v1

模型地址。

CustomModelService object 可选示例值：-

火山引擎自部署模型服务。

Namespace string 必选示例值：default

命名空间。长度限制为 2~63 个字符。

Name string 必选示例值：example

服务名称。长度限制为 2~63 个字符。

Port integer 必选示例值：80

端口。

CustomHeaderParams object 可选示例值：{"example-key":"example-value"}

请求头。

如果请求头已存在，将覆写已存在的请求头。

长度限制为 0~10 个。

CustomBodyParams object 可选示例值：{"example-key":"example-value"}

请求体字段。

仅支持 JSON 请求体的第 1 层字段。

如果请求体字段已存在，将覆写已存在的请求体字段。

长度限制为 0~10 个。

NacosService object 可选示例值：-

注册中心。

说明

当SourceType取值为Nacos时，需要配置本参数。

UpstreamSourceId string 必选示例值：ncn24****

MSE Nacos 实例 ID。

Namespace string 必选示例值：default

命名空间。

Group string 必选示例值：default

MSE 已有的配置分组。

Service string 必选示例值：example

MSE 已有的服务名称。

NamespaceId string 可选示例值：b04b9767-70****

MSE 已有的命名空间 ID。

LoadBalancerSettings object 可选示例值：-

负载均衡配置。

LbPolicy string 必选示例值：SimpleLB

负载均衡策略，取值：

SimpleLB：简单负载均衡。

ConsistentHashLB：一致性哈希负载均衡。

SimpleLB string 可选示例值：ROUND_ROBIN

简单负载均衡，取值：

ROUND_ROBIN：轮询。

LEAST_CONN：最小连接数。

RANDOM：随机。

ConsistentHashLB object 可选示例值：-

一致性哈希负载均衡。

说明

当LoadBalancerSettings.LbPolicy取值为ConsistentHashLB时，需要配置本参数。

HashKey string 必选示例值：UseSourceIp

一致性哈希方式，取值：

UseSourceIp：基于源 IP 地址。

HttpQueryParameterName：基于参数。

HttpHeaderName：基于头。

HTTPCookie：基于 Cookie。

UseSourceIp string 可选示例值：10.0.0.1

源 IP 地址。

当ConsistentHashLB.HashKey取值为UseSourceIp时，需要配置本参数。

HttpQueryParameterName string 可选示例值：example

请求参数。支持 ASCII 可打印字符，长度限制为 1~256 个字符。

说明

当ConsistentHashLB.HashKey取值为HttpQueryParameterName时，需要配置本参数。

HttpHeaderName string 可选示例值：example

请求头。支持 ASCII 可打印字符，长度限制为 1~256 个字符。

说明

当ConsistentHashLB.HashKey取值为HttpHeaderName时，需要配置本参数。

HTTPCookie object 可选示例值：-

Cookie 配置。

说明

当ConsistentHashLB.HashKey取值为HTTPCookie时，需要配置本参数。

Name string 必选示例值：example

Cookie 名称。支持 ASCII 可打印字符，长度限制为 0~256 个字符。

Path string 可选示例值：/

Cookie 路径。支持 ASCII 可打印字符，长度限制为 1~256 个字符。

Ttl long 必选示例值：360

Cookie 有效期，单位为秒。

HashBalanceFactor integer 可选示例值：120

过载保护。取值范围为 100~200。

【示例】当取值为 120 时，Upstream 节点当前活跃请求数超过平均活跃请求数的 120% 时，将触发过载保护。

当触发过载保护时，即使请求的 Hash 命中某一 Upstream 节点，负载均衡器也会随机选择 Upstream 节点。

WarmupDuration long 可选示例值：5

预热时间，单位为秒。

说明

当LoadBalancerSettings.SimpleLB取值为ROUND_ROBIN和LEAST_CONN时，需要配置本参数。

InferenceLB object 可选示例值：-

推理服务负载均衡。

InferenceEngine string 必选示例值：SGLang

推理引擎，取值：

SGLang：SGLang。

vLLM：vLLM。

ServingMode string 必选示例值：Unified

服务模式，取值：

Unified：统一。

PD：PD分离。

CircuitBreakingSettings object 可选示例值：-

服务熔断配置。

Enable boolean 必选示例值：true

是否开启服务熔断。取值：

true：开启。

false：不开启。

ConsecutiveErrors long 可选示例值：5

连续失败次数。取值范围为 1~100，默认值为 5。

Interval long 可选示例值：10000

计算周期。单位为毫秒。取值范围为 1~86400000，默认值为 10。

BaseEjectionTime long 可选示例值：30000

最小弹出时间。单位为毫秒。取值范围为 1~86400000，默认值为 30。

MaxEjectionPercent integer 可选示例值：20

最大熔断比例。取值范围为 1~100，默认值为 20。

MinHealthPercent integer 可选示例值：60

最小可用比例。取值范围为 0~100，默认值为 60。

Protocol string 可选示例值：HTTP

协议，取值：

HTTP

HTTP2

GRPC

ConnectionPoolSettings object 可选示例值：-

连接池配置。

Enable boolean 必选示例值：true

是否开启后端连接池。取值：

true：开启。

false：不开启。

MaxConnections integer 可选示例值：1000

TCP 最大连接数。取值范围为 0~2³¹-1，当取值为 0 时，不限制 TCP 最大连接数。

Http1MaxPendingRequests integer 可选示例值：1000

HTTP/1 最大等待请求数。取值范围为 0~2³¹-1，当取值为 0 时，不限制 HTTP/1 最大等待请求数。

IdleTimeout integer 可选示例值：1000

空闲超时时间，单位为秒。取值范围为 0~2³¹-1，当取值为 0 时，不限制空闲超时时间。

TlsSettings object 可选示例值：-

TLS 配置。

TlsMode string 必选示例值：DISABLE

TLS 模式，取值：

DISABLE：关闭 TLS。

SIMPLE：单向 TLS。

Sni string 可选示例值：example.com

服务器名称指示用于描述请求的目标域名。取值为空时会将访问网关的域名透传到 Upstream。

返回参数

下方仅列出本接口特有的返回参数。更多信息请参见返回结构。

Id string 示例值：ud8t****

Upstream ID。

请求示例

返回示例

错误码

下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见公共错误码文档。

状态码	错误码	错误信息	说明
400	InvalidParameter	The specified parameter %s is invalid.	请求参数值不合法。请确认参数后重试。
400	MissingParameter	The required parameter %s is missing.	缺少必要的请求参数。请确认参数后重试。
403	OperationDenied	Operation is denied because %s.	操作不合法。请修改后重试。
404	ResourceNotFound	The specified resource %s %s cannot be found.	指定资源找不到。请确认参数后重试。
409	DuplicatedResource	Resource %s %s already exists.	资源已重复。请确认参数后重试。
500	InternalError	The request has failed due to an unknown error.	未知错误。请稍后重试。如果多次尝试失败，请提交工单。