更新路由
更新时间:2026-08-15
更新指定 AI 网关实例下的路由配置;该接口执行完整替换,不支持修改路由名称或只提交部分配置。
OpenAPI Explorer
去调试
您可以在 OpenAPI Explorer 中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer 可以自动生成 SDK 代码示例。
请求结构
Http
1PUT /v1/aigw/{instanceId}/{routeName}/route/detail HTTP/1.1
2Host: aigw.bj.baidubce.com
3X-Region: bj
4Authorization: authorization string
5Content-Type: application/json
6
7{
8 "accessMode": "API",
9 "matchRules": {
10 "pathRule": {
11 "matchType": "prefix",
12 "value": "/v1/models/",
13 "caseSensitive": true
14 },
15 "methods": ["GET", "POST"]
16 },
17 "multiService": false,
18 "targetService": {
19 "serviceSource": "CCE",
20 "serviceName": "mnist-inference-v2",
21 "namespace": "default",
22 "servicePort": 8080,
23 "loadBalanceAlgorithm": "round-robin"
24 },
25 "authEnabled": false,
26 "tokenRateLimit": {
27 "enabled": false
28 },
29 "requestRateLimit": {
30 "enabled": false
31 }
32}
请求头域
除公共头域外,还需传入以下头域:
| 参数名称 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| X-Region | string | 是 | 地域代码,如 bj |
请求参数
| 参数名称 | 类型 | 是否必需 | 参数位置 | 描述 |
|---|---|---|---|---|
| instanceId | string | 是 | URL参数 | AI 网关实例 ID |
| routeName | string | 是 | URL参数 | 待更新的路由名称,必须已存在且不可修改 |
| srcProduct | string | 否 | RequestBody参数 | 来源产品标识 |
| accessMode | string | 否 | RequestBody参数 | 访问模式,取值为 API 或 Web,默认为 API |
| webSubdomain | string | 否 | RequestBody参数 | Web 模式的独立子域名,accessMode 为 Web 时必需 |
| servicePath | string | 否 | RequestBody参数 | Web 模式的后端服务路径,accessMode 为 Web 时必需,必须以 / 开头 |
| domains | List |
否 | RequestBody参数 | API 模式绑定的自定义域名列表;为空时使用实例默认域名 |
| matchRules | MatchRule | 是 | RequestBody参数 | 路由匹配规则;Web 模式必须使用 prefix 匹配 / |
| multiService | boolean | 否 | RequestBody参数 | 是否启用多服务,默认为 false;Web 模式不支持多服务 |
| trafficDistributionStrategy | string | 否 | RequestBody参数 | 多服务流量分发策略,取值为 ratio 或 model_name,multiService 为 true 时必需 |
| enableWeightAdjust | boolean | 否 | RequestBody参数 | 是否启用动态权重调节,仅多服务 ratio 策略生效,默认为 false |
| targetService | TargetService | 是 | RequestBody参数 | 目标服务;单服务传对象,多服务传 List<TargetService> |
| rewrite | Rewrite | 否 | RequestBody参数 | 普通路径重写配置;enabled 为 true 时 path 必需 |
| regexRewrite | RegexRewrite | 否 | RequestBody参数 | 正则路径重写配置,优先级高于普通路径重写 |
| customHeaders | List<[CustomHeader]> | 否 | RequestBody参数 | 自定义请求头列表;更新时完全替换原配置 |
| skipSetHostHeader | boolean | 否 | RequestBody参数 | FIXED_IP 或 DNS_DOMAIN 服务是否跳过自动设置 Host 请求头 |
| authEnabled | boolean | 否 | RequestBody参数 | 是否启用消费者认证,默认为 false |
| allowedConsumers | List |
否 | RequestBody参数 | 允许访问的消费者 ID 列表,authEnabled 为 true 时至少传一项 |
| tokenRateLimit | TokenRateLimit | 否 | RequestBody参数 | Token 限流配置;更新时完整替换,enabled 为 true 时 rule_items 至少传一项 |
| requestRateLimit | RequestRateLimit | 否 | RequestBody参数 | 请求次数限流配置;更新时完整替换,enabled 为 true 时 rule_items 至少传一项 |
| timeoutPolicy | TimeoutPolicy | 否 | RequestBody参数 | 超时策略 |
| retryPolicy | RetryPolicy | 否 | RequestBody参数 | 重试策略 |
| corsPolicy | CorsPolicy | 否 | RequestBody参数 | 跨域策略 |
| responseHeaders | ResponseHeaders | 否 | RequestBody参数 | 自定义响应头配置 |
| fallbackConfig | FallbackConfig | 否 | RequestBody参数 | AI Fallback 配置 |
多服务 ratio 策略下,所有 requestRatio 之和必须为 100;启用动态权重后,实际权重为跨集群就绪实例数之和乘以 weightFactor。动态 Token 预扣开启且未指定 pre_reserve_admission_mode 时使用 smooth;省略 pre_reserve_remaining_ratio 或传 0 会关闭动态预扣。
返回头域
除公共头域外,无其他特殊头域。
返回参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| result | RouteResult | 更新后的路由信息 |
| message | string | 错误信息,仅失败时返回 |
请求示例
Http
1PUT /v1/aigw/i-a1b2c3d4/inference-api/route/detail HTTP/1.1
2Host: aigw.bj.baidubce.com
3X-Region: bj
4Authorization: authorization string
5Content-Type: application/json
6
7{
8 "accessMode": "API",
9 "matchRules": {
10 "pathRule": {
11 "matchType": "prefix",
12 "value": "/v1/models/",
13 "caseSensitive": true
14 },
15 "methods": ["GET","POST"]
16 },
17 "targetService": {
18 "serviceSource": "CCE",
19 "serviceName": "flask-service-v2",
20 "namespace": "default",
21 "loadBalanceAlgorithm": "round-robin",
22 "servicePort": 80
23 },
24 "corsPolicy": {
25 "enabled": true,
26 "allowCredentials": true,
27 "allowOrigins": [
28 {
29 "matchType": "exact",
30 "value": "http://aigw.example.com"
31 }
32 ],
33 "allowMethods": ["GET"],
34 "allowHeaders": ["*"],
35 "exposeHeaders": ["*"],
36 "maxAge": 3600
37 },
38 "responseHeaders": {
39 "enabled": true,
40 "headers": [
41 {
42 "key": "X-Custom-Header",
43 "value": "AIGW"
44 }
45 ]
46 },
47 "customHeaders": [
48 {
49 "key": "X-Request-Header",
50 "value": "123"
51 }
52 ]
53}
响应示例
Http
1HTTP/1.1 200 OK
2Content-Type: application/json;charset=UTF-8
3x-bce-request-id: d8752367-38e8-45e4-b4c7-e53be3137ce5
4
5Status: 200 Time: 344.371ms
6{
7 "accessMode": "API",
8 "routeName": "api-route-test",
9 "updateTime": "2026-08-13 16:08:00"
10}
错误响应示例:
JSON
1{
2 "success": false,
3 "status": 404,
4 "message": "路由不存在"
5}
评价此篇文章
