创建 Upstream。

请求说明

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

请求方式：POST

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

调试

API Explorer

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

去调试

请求参数

参数	类型	是否必选	示例值	描述
Action	String	是	CreateUpstream	接口名称。当前 API 的名称为 CreateUpstream。
Version	String	是	2021-03-03	接口版本。当前 API 的版本为 2021-03-03。
Name	String	是	example	Upstream 名称。支持大小写字母、数字和中划线（-），长度限制为 2~63 个字符。不能以中划线（-）开头。
GatewayId	String	是	gd8****	网关实例 ID。您可以通过 ListGateways 查询网关实例 ID。
Comments	String	否	example	Upstream 的备注信息。字符串形式，长度限制为 0~253 个字符。不填默认为空。
SourceType	String	是	VeFaas	Upstream 来源类型，取值： VeFaas：函数服务。 ECS：云服务器。 K8S：容器服务。 Nacos：注册中心。 Domain：固定域名。 FixedIP：固定 IP。 AIProvider：AI 模型代理。
UpstreamSpec	Object of UpstreamSpec	是	-	Upstream 配置。
LoadBalancerSettings	Object of LoadBalancerSettings	否	-	负载均衡配置。
CircuitBreakingSettings	Object of CircuitBreakingSettings	否	-	服务熔断配置。
ConnectionPoolSettings	Object of ConnectionPoolSettings	否	-	连接池配置。
Protocol	String	否	HTTP	协议类型，取值： HTTP HTTP2 GRPC
TlsSettings	Object of TlsSettings	否	-	TLS 配置。

UpstreamSpec

参数	类型	是否必选	示例值	描述
VeFaas	Object of VeFaas	否	-	函数服务。说明当SourceType取值为VeFaas时，需要配置本参数。
K8SService	Object of K8SService	否	-	容器服务。说明当SourceType取值为K8S时，需要配置本参数。
EcsList	Array of Ecs	否	-	云服务器。说明当SourceType取值为ECS时，需要配置本参数。
FixedIPList	Array of FixedIP	否	-	固定 IP。说明当SourceType取值为FixedIP时，需要配置本参数。
Domain	Object of Domain	否	-	固定域名。说明当SourceType取值为Domain时，需要配置本参数。
NacosService	Object of NacosService	否	-	注册中心。说明当SourceType取值为Nacos时，需要配置本参数。
AIProvider	Object of AIProvider	否	-	AI 模型代理。说明当SourceType取值为AIProvider时，需要配置本参数。

LoadBalancerSettings

参数	类型	是否必选	示例值	描述
LbPolicy	String	是	SimpleLB	负载均衡策略，取值： SimpleLB：简单负载均衡。 ConsistentHashLB：一致性哈希负载均衡。
SimpleLB	String	否	ROUND_ROBIN	简单负载均衡，取值： ROUND_ROBIN：轮询。 LEAST_CONN：最小连接数。 RANDOM：随机。
ConsistentHashLB	Object of ConsistentHashLB	否	-	一致性哈希负载均衡。说明当LoadBalancerSettings.LbPolicy取值为ConsistentHashLB时，需要配置本参数。
WarmupDuration	Long	否	5	预热时间，单位为秒。说明当LoadBalancerSettings.SimpleLB取值为ROUND_ROBIN和LEAST_CONN时，需要配置本参数。

CircuitBreakingSettings

参数	类型	是否必选	示例值	描述
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。

ConnectionPoolSettings

参数	类型	是否必选	示例值	描述
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

参数	类型	是否必选	示例值	描述
TlsMode	String	是	DISABLE	TLS 模式，取值： DISABLE：关闭 TLS。 SIMPLE：单向 TLS。
Sni	String	否	example.com	服务器名称指示用于描述请求的目标域名。取值为空时会将访问网关的域名透传到 Upstream。

VeFaas

参数	类型	是否必选	示例值	描述
FunctionId	String	是	35v****	函数 ID。您可以通过 ListFunctions 查询函数 ID。

K8SService

参数	类型	是否必选	示例值	描述
Namespace	String	是	default	Kubernetes Service 所在的命名空间。长度限制为 2~63 个字符。
Name	String	是	example	Kubernetes Service 名称。长度限制为 2~63 个字符。
Port	Integer	是	80	Kubernetes Service 开放的端口。

Ecs

参数	类型	是否必选	示例值	描述
EcsId	String	是	i-3tig******	云服务器 ID。您可以通过 DescribeInstances 查询云服务器 ID。
IP	String	是	10.0.0.1	云服务器 IP 地址。
Port	Integer	是	80	为 ECS 实例配置访问端口。API 网关只能通过配置的端口访问对应的 ECS。

FixedIP

参数	类型	是否必选	示例值	描述
IP	String	是	10.0.0.1	后端 IP 地址。
Port	Integer	是	80	后端 IP 的端口号。

Domain

参数	类型	是否必选	示例值	描述
DomainList	Array of DomainEndpoint	是	-	域名列表。长度限制为 1 个。

NacosService

参数	类型	是否必选	示例值	描述
UpstreamSourceId	String	是	ncn24****	MSE Nacos 实例 ID。
Namespace	String	是	default	MSE 已有的命名空间名称。
Group	String	是	default	MSE 已有的配置分组。
Service	String	是	example	MSE 已有的服务名称。
NamespaceId	String	否	b04b9767-70****	MSE 已有的命名空间 ID。

AIProvider

参数	类型	是否必选	示例值	描述
Name	String	是	OpenAI	模型服务商名称。
Token	String	否	ark-6bb****	模型 API key。详情请参见创建 API Key。
BaseUrl	String	是	https://api.openai.com/v1	模型地址。
CustomModelService	Object of K8SService	否	-	火山引擎自部署模型服务。
CustomHeaderParams	JSON Map	否	{"example-key":"example-value"}	请求头。如果请求头已存在，将覆写已存在的请求头。长度限制为 0~10 个。
CustomBodyParams	JSON Map	否	{"example-key":"example-value"}	请求体字段。仅支持 JSON 请求体的第 1 层字段。如果请求体字段已存在，将覆写已存在的请求体字段。长度限制为 0~10 个。

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 of HTTPCookie	否	-	Cookie 配置。说明当ConsistentHashLB.HashKey取值为HTTPCookie时，需要配置本参数。
HashBalanceFactor	Integer	否	120	过载保护。取值范围为 100~200。【示例】当取值为 120 时，Upstream 节点当前活跃请求数超过平均活跃请求数的 120% 时，将触发过载保护。当触发过载保护时，即使请求的 Hash 命中某一 Upstream 节点，负载均衡器也会随机选择 Upstream 节点。

DomainEndpoint

参数	类型	是否必选	示例值	描述
Domain	String	是	example.com	对接后端的固定域名地址。
Port	Integer	否	80	对接后端域名的端口号。协议类型为 HTTP 时，默认值为 80。协议类型为 HTTPS 时，默认值为 443。

CustomHeaderParams

参数	类型	是否必选	示例值	描述
key	String	是	example-key	请求头的键。长度限制 1 ~ 256 个字符。相同类型的 key 不能出现重复。
value	String	是	example-value	请求头的值。长度限制 1 ~ 256 个字符。

CustomBodyParams

参数	类型	是否必选	示例值	描述
key	String	是	example-key	请求体的键。长度限制 1 ~ 256 个字符。相同类型的 key 不能出现重复。
value	String	是	example-value	请求体的值。长度限制 1 ~ 256 个字符。

HTTPCookie

参数	类型	是否必选	示例值	描述
Name	String	是	example	Cookie 名称。支持 ASCII 可打印字符，长度限制为 0~256 个字符。
Path	String	否	/	Cookie 路径。支持 ASCII 可打印字符，长度限制为 1~256 个字符。
Ttl	Long	是	360	Cookie 有效期，单位为秒。

请求示例

返回参数

参数	类型	示例值	描述
Id	String	ud8t****	Upstream ID。

返回示例

错误码

本接口无特有的错误码。更多信息请参见公共错误码。