创建路由
更新时间：2026-08-15
在指定 AI 网关实例下创建一条路由，配置请求匹配、目标服务、认证、限流、超时、重试和路径重写等转发行为。
OpenAPI Explorer
去调试
您可以在 OpenAPI Explorer 中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer 可以自动生成 SDK 代码示例。
请求结构
Http
1POST /v1/aigw/{instanceId}/{clusterId}/route HTTP/1.1
2Host: aigw.bj.baidubce.com
3X-Region: bj
4Authorization: authorization string
5Content-Type: application/json
6
7{
8 "routeName": "inference-api",
9 "accessMode": "API",
10 "matchRules": {
11 "pathRule": {
12 "matchType": "prefix",
13 "value": "/v1/models/",
14 "caseSensitive": true
15 },
16 "methods": ["GET", "POST"]
17 },
18 "multiService": false,
19 "targetService": {
20 "serviceSource": "CCE",
21 "serviceName": "mnist-inference",
22 "namespace": "default",
23 "servicePort": 8080,
24 "loadBalanceAlgorithm": "round-robin"
25 },
26 "authEnabled": false,
27 "tokenRateLimit": {
28 "enabled": false
29 },
30 "requestRateLimit": {
31 "enabled": false
32 }
33}请求头域
除公共头域外，还需传入以下头域：
| 参数名称 | 类型 | 是否必需 | 描述 |
|---|---|---|---|
| X-Region | string | 是 | 地域代码，如 bj |
请求参数
| 参数名称 | 类型 | 是否必需 | 参数位置 | 描述 |
|---|---|---|---|---|
| instanceId | string | 是 | URL参数 | AI 网关实例 ID |
| clusterId | string | 是 | URL参数 | 集群 ID |
| routeName | string | 是 | RequestBody参数 | 路由名称，长度为 2～64 个字符，在同一实例内唯一 |
| 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 配置 |
返回头域
除公共头域外，无其他特殊头域。
返回参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| result | RouteResult | 创建后的路由信息 |
| message | string | 错误信息，仅失败时返回 |
请求示例
Http
1POST http://aigw.bj.baidubce.com/v1/aigw/aigw-a1b2c3d4/api-route-test/route HTTP/1.1
2Host: aigw.bj.baidubce.com
3X-Region: bj
4Authorization: authorization string
5Content-Type: application/json
6
7{
8 "routeName": "api-route-test",
9 "accessMode": "API",
10 "matchRules": {
11 "pathRule": {
12 "matchType": "prefix",
13 "value": "/v1/models/",
14 "caseSensitive": true
15 },
16 "methods": [
17 "GET",
18 "POST"
19 ]
20 },
21 "targetService": {
22 "serviceSource": "CCE",
23 "serviceName": "flask-service-v2",
24 "namespace": "default",
25 "loadBalanceAlgorithm": "round-robin",
26 "servicePort": 80
27 },
28 "corsPolicy": {
29 "enabled": true,
30 "allowCredentials": true,
31 "allowOrigins": [
32 {
33 "matchType": "exact",
34 "value": "http://aigw.example.com"
35 }
36 ],
37 "allowMethods": [
38 "GET",
39 "POST"
40 ],
41 "allowHeaders": [
42 "*"
43 ],
44 "exposeHeaders": [
45 "*"
46 ],
47 "maxAge": 7200
48 },
49 "responseHeaders": {
50 "enabled": true,
51 "headers": [
52 {
53 "key": "X-Custom-Header",
54 "value": "AIGW"
55 }
56 ]
57 },
58 "customHeaders": [
59 {
60 "key": "X-Request-Header",
61 "value": "test"
62 }
63 ]
64}响应示例
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: 69.349ms
6{
7 "routeName": "api-route-test",
8 "matchRules": {
9 "pathRule": {
10 "matchType": "prefix",
11 "value": "/v1/models/",
12 "caseSensitive": true
13 },
14 "methods": [
15 "GET",
16 "POST"
17 ],
18 "headers": null,
19 "queryParams": null
20 },
21 "serviceName": "flask-service-v2",
22 "createTime": "2026-08-13 15:54:43",
23 "multiService": false,
24 "rewrite": {
25 "enabled": false
26 },
27 "targetService": {
28 "serviceSource": "CCE",
29 "serviceName": "flask-service-v2",
30 "namespace": "default",
31 "servicePort": 80,
32 "loadBalanceAlgorithm": "round-robin"
33 },
34 "authEnabled": false,
35 "tokenRateLimit": {
36 "rule_name": "",
37 "enabled": false
38 },
39 "requestRateLimit": {
40 "rule_name": "",
41 "enabled": false
42 },
43 "accessMode": "API"
44}错误响应示例：
JSON
1{
2 "success": false,
3 "status": 400,
4 "message": "路由名称已存在"
5}评价此篇文章