预览API变更
更新时间：2026-09-22
该接口用于校验 API 编辑参数并预览本次变更的当前值、目标值、流量变化类型及是否需要下发数据面。
该接口为只读操作，不修改控制面数据，也不刷新数据面配置。
请求结构
Plain Text
1POST /?action=PreviewUpdateApi HTTP/1.1
2Host: apigw-control.bj.baidubce.com
3Authorization: authorization string
4
5{
6 "apiId": apiId,
7 "name": name,
8 "description": description,
9 "methods" : [method],
10 "path": path,
11 "urlRewrite": urlRewrite,
12 "urlRewritePath": urlRewritePath,
13 "urlRewriteHost": urlRewriteHost,
14 "urlRewriteType": urlRewriteType,
15 "urlRewriteRegexMatch": urlRewriteRegexMatch,
16 "urlRewriteRegexRewrite": urlRewriteRegexRewrite,
17 "matchType": matchType,
18 "apiType": apiType,
19 "modelBackendStrategy": modelBackendStrategy,
20 "headerList" : [headerList],
21 "queryList" : [queryList],
22 "backendList" : [backendList],
23 "deletedRuleIds" : [deletedRuleId],
24 "retries": retries,
25 "attempts": attempts,
26 "perTryTimeout": perTryTimeout,
27 "retryOn" : [retryOn],
28 "httpCodes" : [httpCode],
29 "timeout": timeout,
30 "timeoutTime": timeoutTime,
31 "priorityNumber": priorityNumber,
32 "fallbackEnabled": fallbackEnabled,
33 "fallbackFirstTokenTimeoutMs": fallbackFirstTokenTimeoutMs,
34 "fallbackTriggerScope": fallbackTriggerScope,
35 "consumerAuthEnabled": consumerAuthEnabled,
36 "authorizationType": authorizationType,
37 "consumerIds" : [consumerId],
38 "consumerAuthorizations" : [consumerAuthorization]
39}请求头域
除公共头域外，无其它特殊头域。
请求参数
| 参数名称 | 类型 | 是否必需 | 参数位置 | 描述 |
|---|---|---|---|---|
| apiId | String | 是 | RequestBody参数 | API ID |
| name | String | 是 | RequestBody参数 | API 名称 |
| description | String | 否 | RequestBody参数 | 路由描述 |
| methods | List<String> | 否 | RequestBody参数 | 请求方法 |
| path | String | 否 | RequestBody参数 | 路径 |
| urlRewrite | Boolean | 否 | RequestBody参数 | 路径重写 |
| urlRewritePath | String | 否 | RequestBody参数 | 路径重写：重写后的路径 |
| urlRewriteHost | String | 否 | RequestBody参数 | 路径重写：重写后的 Host |
| urlRewriteType | String | 否 | RequestBody参数 | 路径重写匹配类型：Exact / Prefix / Regex；开启路径重写时必填 |
| urlRewriteRegexMatch | String | 否 | RequestBody参数 | 正则重写模式，如 ^/user/(/+)(/.*)$；重写类型为 Regex 时必填 |
| urlRewriteRegexRewrite | String | 否 | RequestBody参数 | 正则重写替换表达式，如 /instance/\1；重写类型为 Regex 时必填 |
| matchType | String | 否 | RequestBody参数 | 匹配类型 |
| apiType | String | 否 | RequestBody参数 | API 类型，仅用于一致性校验；不传时保留原值 |
| modelBackendStrategy | String | 否 | RequestBody参数 | 后端策略：基础 API 显式传 SINGLE / WEIGHT 时使用 weight 新协议；不传时按旧版 matchContent 百分比协议校验，并保留或推导落库策略；Model 路由支持 SINGLE / MODEL_NAME / WEIGHT；Agent 路由不传 |
| headerList | List<AiGwApiHeader> | 否 | RequestBody参数 | 请求头 |
| queryList | List<AiGwApiQuery> | 否 | RequestBody参数 | 请求参数 |
| backendList | List<AiGwApiBackendBind> | 否 | RequestBody参数 | 后端配置 |
| deletedRuleIds | List<String> | 否 | RequestBody参数 | 本次编辑删除的 MODEL_NAME 规则 ID |
| retries | Boolean | 否 | RequestBody参数 | 重试 |
| attempts | int | 否 | RequestBody参数 | 重试次数 |
| perTryTimeout | int | 否 | RequestBody参数 | 单次重试超时时间（毫秒） |
| retryOn | List<String> | 否 | RequestBody参数 | 重试条件 |
| httpCodes | List<int> | 否 | RequestBody参数 | 触发重试的响应状态码 |
| timeout | Boolean | 否 | RequestBody参数 | 超时时间 |
| timeoutTime | int | 否 | RequestBody参数 | 超时时间（毫秒） |
| priorityNumber | long | 否 | RequestBody参数 | 优先级（0-9999），0 为最高优先级，默认 9999 |
| fallbackEnabled | Boolean | 否 | RequestBody参数 | Model 路由 Fallback 开关 |
| fallbackFirstTokenTimeoutMs | int | 否 | RequestBody参数 | Model 路由 Fallback 首次响应超时时间（毫秒），0 表示不启用 |
| fallbackTriggerScope | String | 否 | RequestBody参数 | Model 路由 Fallback 触发范围，仅支持 BACKEND_ERROR_ONLY |
| consumerAuthEnabled | Boolean | 否 | RequestBody参数 | 是否开启消费者认证 |
| authorizationType | String | 否 | RequestBody参数 | 消费者认证方式：API_KEY / AK_SK；开启认证时必填 |
| consumerIds | List<String> | 否 | RequestBody参数 | 绑定消费者 ID 列表，可为空（开启但空 = 全部拒绝） |
| consumerAuthorizations | List<ConsumerAuthorization> | 否 | RequestBody参数 | 消费者认证项列表；同一消费者可同时以 API_KEY 和 AK_SK 授权 |
返回头域
除公共头域，无其它特殊头域。
返回参数
| 参数名称 | 类型 | 描述 |
|---|---|---|
| preview | AiGwRouteChangePreviewUO |
错误码
| 错误码 | 错误描述 | HTTP状态码 | 中文解释 |
|---|---|---|---|
| MethodArgumentNotValidException | MethodArgumentNotValidException: apiId must not be blank | 400 | 必填参数缺失或格式不合法，apiId 不能为空 |
| HttpMessageNotReadable | Http Message Not Readable: JSON parse error | 400 | 请求体不是合法 JSON，无法解析，请检查 JSON 语法和字段类型 |
| ResourcePermissionDeny | Resource permission deny. | 401 | 无权限访问指定资源，请确认实例属于当前账号并使用有权限的账号凭证 |
| ApiNotExist | Api not exist. | 404 | apiId 对应的 API 不存在、不属于当前账号或已删除 |
| HttpMediaTypeException | HttpMediaTypeException: Content-Type 'text/plain' is not supported | 415 | 请求的 Content-Type 不受支持，请使用 application/json |
请求示例
Plain Text
1POST /?action=PreviewUpdateApi HTTP/1.1
2Host: apigw-control.bj.baidubce.com
3Authorization: bce-auth-v1/f81d3b34e48048fbb2634dc7882d7e21/2015-08-11T04:17:29Z/3600/host/74c506f68c65e26c633bfa104c863fffac5190fdec1ec24b7c03eb5d67d2e1de
4
5{
6 "apiId": "api-a1b2c3d4",
7 "name": "对话API",
8 "methods": [
9 "POST"
10 ],
11 "path": "/v1/chat/v2",
12 "matchType": "Prefix",
13 "backendList": [
14 {
15 "backendId": "bd-a1b2c3d4",
16 "backendRole": "PRIMARY"
17 }
18 ],
19 "priorityNumber": 0
20}返回示例
Plain Text
1HTTP/1.1 200 OK
2x-bce-request-id: 1214cca7-4ad5-451d-9215-71cb844c0a50
3Date: Wed, 03 Dec 2014 06:42:19 GMT
4Content-Type: application/json;charset=UTF-8
5Server: BWS
6
7{
8 "preview": {
9 "apiId": "api-a1b2c3d4",
10 "serviceId": "sg-a1b2c3d4",
11 "routeName": "对话API",
12 "routeSource": "CUSTOM",
13 "publishStatus": "PUBLISHED",
14 "currentPath": "/v1/chat",
15 "targetPath": "/v1/chat/v2",
16 "currentUrlRewrite": false,
17 "targetUrlRewrite": false,
18 "trafficChangeType": "MODIFY",
19 "willPublish": true
20 }
21}评价此篇文章