更新路由配置信息。

请求说明

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

请求方式：POST

请求地址：https://apig.cn-beijing.volcengineapi.com?Action=UpdateRoute&Version=2022-11-12

调试

API Explorer

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

去调试

请求参数

参数	类型	是否必选	示例值	描述
Action	String	是	UpdateRoute	接口名称。当前 API 的名称为 UpdateRoute。
Version	String	是	2022-11-12	接口版本。当前 API 的版本为 2022-11-12。
Name	String	是	example	路由名称。长度限制为 2~255 个字符。
Id	String	是	rd93****	路由 ID。您可以通过 ListRoutes 查询路由 ID。
MatchRule	Object of MatchRule	否	-	匹配规则。
UpstreamList	Array of RouteUpstream	是	-	Upstream 流量分发。
AdvancedSetting	Object of RouteAdvancedSetting	否	-	高级配置。
Enable	Boolean	否	true	是否开启路由上下线功能。取值： true：开启。 false：不开启。说明该功能目前处于邀测阶段，如需使用，请联系客户经理。
Priority	Long	否	100	优先级。整数形式，取值范围为 0～100。数字越小，优先级越高。当取值为 0 时，表示最高优先级，全局最先匹配强制优先路由。
FallbackSetting	Object of FallbackSetting	否	-	Fallback 配置。

MatchRule

参数	类型	是否必选	示例值	描述
Path	Object of StringMatch	是	-	允许访问的请求路径。必须以（/）开头，（/）不能超过 30 个。支持 ASCII 可打印字符，长度限制为 1~256 个字符。不能包含空格。
Method	Array of String	否	["GET","POST","PUT","DELETE","HEAD","OPTIONS","CONNECT","PATCH"]	请求方法，取值： GET POST PUT DELETE HEAD OPTIONS CONNECT PATCH
QueryString	Array of StringMatchItem	否	-	请求参数。支持 ASCII 可打印字符，长度限制为 1~256 个字符。不能包含空格。
Header	Array of StringMatchItem	否	-	请求头。长度限制为 0~5 个。支持大小写字母、数字、中划线（-）和下划线（_），长度限制为 1~256 个字符。不能包含空格。

RouteUpstream

参数	类型	是否必选	示例值	描述
UpstreamId	String	是	ud93****	对接的 Upstream ID。您可以通过 ListUpstreams 查询 Upstream ID。
Weight	Integer	是	100	当前 Upstream 的流量权重。整数形式，取值范围为 1～1000。说明系统会根据 Upstream 配置的权重总值和各 Upstream 的权重占比，按比例显示流量划分，百分比数字精确到两位小数。
Version	String	否	test	灰度版本。请输入 2~63 个字符。字符中只能包含大小写字母、数字、和中划线（-）。不能以中划线（-）开头。
AIProviderSettings	Object of AIProviderSettings	否	-	AI 模型配置。说明当 Upstream 类型为 AI 模型代理时，需要配置本参数。

RouteAdvancedSetting

参数	类型	是否必选	示例值	描述
TimeoutSetting	Object of TimeoutSetting	否	-	超时配置。
CorsPolicySetting	Object of CorsPolicySetting	否	-	跨域配置。
URLRewriteSetting	Object of URLRewriteSetting	否	-	URL 重写配置。说明当 Upstream 类型为 AI 模型代理时，URL 重写不生效。
HeaderOperations	Array of HeaderOperation	否	-	修改请求头。长度限制为 0~5 个。
MirrorPolicies	Array of MirrorPolicy	否	-	流量镜像。长度限制为 0~1 个。
RetryPolicySetting	Object of RetryPolicySetting	否	-	重试配置。

FallbackSetting

参数	类型	是否必选	示例值	描述
Enable	Boolean	否	false	是否开启 Fallback。取值 true：开启。 false：不开启。
FallbackUpstreams	Array of RouteUpstream	否	-	Fallback Upstream 列表。长度限制为 1 个。
Conditions	Array of String	否	["4xx"]	Fallback 条件，取值： 4xx：后端服务器返回 4xx 状态码。 5xx：后端服务器返回 5xx 状态码，或发生连接断开、重置、读取超时事件。

StringMatch

参数	类型	是否必选	示例值	描述
MatchType	String	是	Exact	请求匹配类型，取值： Exact：精准匹配。 Prefix：前缀匹配。 Regex：正则匹配。
MatchContent	String	是	example-value	请求匹配值。支持 ASCII 可打印字符，长度限制为 1~256 个字符。不能包含空格。

StringMatchItem

参数	类型	是否必选	示例值	描述
Key	String	是	example-key	请求匹配键。
Value	Object of StringMatch	是	-	请求匹配值。

AIProviderSettings

参数	类型	是否必选	示例值	描述
Model	String	是	doubao-seed-2-0-pro-260215	目标模型。
TargetPath	String	是	/chat/completions	精准重写路径。请求路径会由 Base URL 和精准重写路径拼接而成。例如当 Base URL 为/api/v3，精准重写路径为/chat/completions时，请求路径为/api/v3/chat/completions。说明当精准重写路径和前缀重写路径同时设置时，精准重写路径生效。
PrefixPath	String	否	/ep	前缀重写路径。请求路径的前缀重写路径部分将改写为 Base URL。例如当 Base URL 为/api/v3，前缀重写路径为/ep时，请求路径/ep/chat/completions将被改写为/api/v3/chat/completions。说明当精准重写路径和前缀重写路径同时设置时，精准重写路径生效。

TimeoutSetting

参数	类型	是否必选	示例值	描述
Enable	Boolean	否	true	是否开启超时配置。取值： true：开启。 false：不开启。
Timeout	Long	否	10	超时时间，单位为秒。

CorsPolicySetting

参数	类型	是否必选	示例值	描述
Enable	Boolean	否	true	是否开启跨域配置。取值： true：开启。 false：不开启。
AllowCredentials	Boolean	否	false	是否携带凭证。取值： true：携带。 false：不携带。
AllowMethods	Array of String	否	["GET","POST","PUT","DELETE","HEAD","OPTIONS","CONNECT","PATCH"]	允许的 HTTP 方法，取值： GET。 POST。 PUT。 DELETE。 HEAD。 OPTIONS。 CONNECT。 PATCH。
AllowOrigins	Array of OriginEntry	否	-	允许的访问来源列表。
AllowHeaders	Array of String	否	["example-header"]	允许的非简单请求头。
ExposeHeaders	Array of String	否	["example-header"]	允许客户端获取的非简单响应头。
MaxAge	Long	否	86400	缓存时间。预检请求结果的有效缓存时间，单位为秒。

URLRewriteSetting

参数	类型	是否必选	示例值	描述
Enable	Boolean	否	true	是否开启 URL 重写。取值： true：开启。 false：不开启。
URLRewrite	String	否	/v2/	重写路径。必须以（/）开头，以（/）结尾，（/）不能超过 30 个。支持 ASCII 可打印字符，长度限制为 1~256 个字符。

HeaderOperation

参数	类型	是否必选	示例值	描述
Operation	String	是	set	请求头修改模式，取值： set：覆写。 add：追加。 remove：移除。
Key	String	是	example-key	请求头的键。支持大小写字母、数字、中划线（-）和下划线（_），长度限制为 1~256 个字符。
Value	String	否	example-value	请求头的值。支持大小写字母、数字、中划线（-）和下划线（_），长度限制为 1~256 个字符。

MirrorPolicy

参数	类型	是否必选	示例值	描述
Upstream	Object of MirrorUpstream	是	-	后端 Upstream 配置。
Percent	Object of PercentSetting	否	-	镜像比例配置。

RetryPolicySetting

参数	类型	是否必选	示例值	描述
Enable	Boolean	否	true	是否开启重试配置。取值： true：开启。 false：不开启。
Attempts	Long	否	2	重试次数。
RetryOn	Array of String	否	["5xx","reset","connect-failure"]	重试条件，取值： 5xx：后端服务器返回 5xx 状态码，或发生连接断开、重置、读取超时事件。 reset：发生连接断开、重置、读取超时事件。 connect-failure：与后端服务器连接失败，请求出错。 refused-stream：后端服务使用REFUSED_STREAM错误码来重置流。 cancelled：后端服务响应头中的 gRPC 状态码为cancelled。 deadline-exceeded：后端服务响应头中的 gRPC 状态码为deadline-exceeded。 internal：后端服务响应头中的 gRPC 状态码为internal。 resource-exhausted：后端服务响应头中的 gRPC 状态码为resource-exhausted。 unavailable：后端服务响应头中的 gRPC 状态码为unavailable。
HttpCodes	Array of String	否	["500"]	需要进行重试的 HTTP 状态码。

OriginEntry

参数	类型	是否必选	示例值	描述
Value	String	是	true	跨域列表。
MatchType	String	是	exact	匹配类型，取值： exact：精准匹配。 regex：正则匹配。

MirrorUpstream

参数	类型	是否必选	示例值	描述
Type	String	是	-	镜像后端 Upstream 类型。说明当Upstream 类型为函数服务或 AI 模型代理时，流量镜像不生效。
UpstreamId	String	是	ud93****	后端 Upstream 的 ID。您可以通过 ListUpstreams 查询 Upstream ID。
Version	String	否	-	灰度版本。

PercentSetting

参数	类型	是否必选	示例值	描述
Value	Double	是	50	复制到镜像后端服务的流量比例值。取值范围为 0~100，取值为 0 时，表示不复制流量到镜像服务。

请求示例

返回参数

参数	类型	示例值	描述
Id	String	rd93****	路由ID。

返回示例

错误码

本接口错误码如下表所示，公共错误码请参见公共错误码。

HTTP 状态码	错误码	错误信息	说明
400	DomainPending	A custom domain is creating or deleting.	自定义域名正在创建或删除。请稍后重试。