为服务创建路由。 ## 请求说明 * 请求方式：POST * 请求地址：https://open.volcengineapi.com?Action=CreateRoute&Version=2022\-11\-12 ## 调试 [去调试](https://api.volcengine.com/api-explorer/debug?action=CreateRoute&serviceCode=apig&version=2022-11-12&groupName=) ## 请求参数 |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |Action |String |是 |CreateRoute |接口名称。当前 API 的名称为 `CreateRoute`。 | |Version |String |是 |2022\-11\-12 |接口版本。当前 API 的版本为 `2022-11-12`。 | |Name |String |是 |example |路由名称。长度限制为 2~255 个字符。 | |ServiceId |String |是 |sd84\*\*\*\* |路由所属服务 ID。您可以通过 [ListGatewayServices](https://www.volcengine.com/docs/6569/1628097?lang=zh) 查询服务 ID。 | |MatchRule |Object of [MatchRule](https://www.volcengine.com/docs/6569/1628100#matchrule) |否 |\- |匹配规则。 | |UpstreamList |Array of [RouteUpstream](https://www.volcengine.com/docs/6569/1628100#routeupstream) |是 |\- |Upstream 流量分发。 | |AdvancedSetting |Object of [RouteAdvancedSetting](https://www.volcengine.com/docs/6569/1628100#routeadvancedsetting) |否 |\- |高级配置。 | |Enable |Boolean |否 |true |是否开启路由上下线功能。取值：

* **true**：开启。

* **false**：（默认值）不开启。

说明

该功能目前处于邀测阶段，如需使用，请联系客户经理。

| |Priority |Long |否 |100 |优先级。整数形式，取值范围为 0～100。数字越小，优先级越高。 | |FallbackSetting |Object of [FallbackSetting](https://www.volcengine.com/docs/6569/1628100#fallbacksetting) |否 |\- |Fallback 配置。 | ### MatchRule |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |Path |Object of [StringMatch](https://www.volcengine.com/docs/6569/1628100#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](https://www.volcengine.com/docs/6569/1628100#stringmatchitem) |否 |\- |请求参数。

* 支持 ASCII 可打印字符，长度限制为 1~256 个字符。

* 不能包含空格。 | |Header |Array of [StringMatchItem](https://www.volcengine.com/docs/6569/1628100#stringmatchitem) |否 |\- |请求头。

* 长度限制为 0~5 个。

* 支持大小写字母、数字、中划线（\-）和下划线（_），长度限制为 1~256 个字符。

* 不能包含空格。 | ### RouteUpstream |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |UpstreamId |String |是 |ud93\*\*\*\* |对接的 Upstream ID。您可以通过 [ListUpstreams](https://www.volcengine.com/docs/6569/1628108?lang=zh) 查询 Upstream ID。 | |Weight |Integer |是 |100 |当前 Upstream 的流量权重。整数形式，取值范围为 1～1000。

说明

系统会根据 Upstream 配置的权重总值和各 Upstream 的权重占比，按比例显示流量划分，百分比数字精确到两位小数。

说明

当 Upstream 类型为 AI 模型代理时，需要配置本参数。

| ### RouteAdvancedSetting |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |TimeoutSetting |Object of [TimeoutSetting](https://www.volcengine.com/docs/6569/1628100#timeoutsetting) |否 |\- |超时配置。 | |CorsPolicySetting |Object of [CorsPolicySetting](https://www.volcengine.com/docs/6569/1628100#corspolicysetting) |否 |\- |跨域配置。 | |URLRewriteSetting |Object of [URLRewriteSetting](https://www.volcengine.com/docs/6569/1628100#urlrewritesetting) |否 |\- |URL 重写配置。

说明

当 Upstream 类型为 AI 模型代理时，URL 重写不生效。

| |HeaderOperations |Array of [HeaderOperation](https://www.volcengine.com/docs/6569/1628100#headeroperation) |否 |\- |修改请求头。长度限制为 0~5 个。 | |MirrorPolicies |Array of [MirrorPolicy](https://www.volcengine.com/docs/6569/1628100#mirrorpolicy) |否 |\- |流量镜像。长度限制为 0~1 个。 | |RetryPolicySetting |Object of [RetryPolicySetting](https://www.volcengine.com/docs/6569/1628100#retrypolicysetting) |否 |\- |重试配置。 | ### FallbackSetting |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |Enable |Boolean |否 |false |是否开启 Fallback。取值

* **true**：开启。

* **false**：不开启。 | |FallbackUpstreams |Array of [RouteUpstream](https://www.volcengine.com/docs/6569/1628100#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](https://www.volcengine.com/docs/6569/1628100#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`。

说明

当精准重写路径和前缀重写路径同时设置时，精准重写路径生效。

说明

当精准重写路径和前缀重写路径同时设置时，精准重写路径生效。

| ### 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](https://www.volcengine.com/docs/6569/1628100#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](https://www.volcengine.com/docs/6569/1628100#mirrorupstream) |是 |\- |后端 Upstream 配置。 | |Percent |Object of [PercentSetting](https://www.volcengine.com/docs/6569/1628100#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](https://www.volcengine.com/docs/6569/1628108?lang=zh) 查询 Upstream ID。 | |Version |String |否 |\- |灰度版本。 | ### PercentSetting |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |Value |Double |是 |50 |复制到镜像后端服务的流量比例值。取值范围为 0~100，取值为 0 时，表示不复制流量到镜像服务。 | ## 请求示例 ```json POST https://open.volcengineapi.com?Action=CreateRoute&Version=2022-11-12 Content-Type: application/json { "Name": "example", "ServiceId": "sd84****", "MatchRule": { "Path": { "MatchType": "Exact", "MatchContent": "example-value" }, "Header": [ { "Key": "example-key", "Value": { "MatchType": "Exact", "MatchContent": "example-value" } } ], "Method": [ "GET", "POST", "PUT", "DELETE", "HEAD", "OPTIONS", "CONNECT", "PATCH" ], "QueryString": [] }, "UpstreamList": [ { "Weight": 100, "Version": "", "UpstreamId": "ud93****", "AIProviderSettings": { "Model": "doubao-seed-2-0-pro-260215", "PrefixPath": "/ep", "TargetPath": "/chat/completions" } } ], "AdvancedSetting": { "MirrorPolicies": [ { "Percent": { "Value": 50 }, "Upstream": { "Type": "", "Version": "", "UpstreamId": "ud93****" } } ], "TimeoutSetting": { "Enable": true, "Timeout": 10 }, "HeaderOperations": [ { "Key": "example-key", "Value": "example-value", "Operation": "set" } ], "CorsPolicySetting": { "Enable": true, "MaxAge": 86400, "AllowHeaders": [ "example-header" ], "AllowMethods": [ "GET", "POST", "PUT", "DELETE", "HEAD", "OPTIONS", "CONNECT", "PATCH" ], "AllowOrigins": [ { "Value": "true", "MatchType": "exact" } ], "ExposeHeaders": [ "example-header" ], "AllowCredentials": true }, "URLRewriteSetting": { "Enable": true, "URLRewrite": "/v2/" }, "RetryPolicySetting": { "Enable": true, "RetryOn": [ "5xx", "reset", "connect-failure" ], "Attempts": 2, "HttpCodes": [ "500" ] } }, "Enable": true, "Priority": 100, "FallbackSetting": { "Enable": true, "Conditions": [ "4xx" ], "FallbackUpstreams": [] } } ``` ## 返回参数 |**参数** |**类型** |**示例值** |**描述** | |---|---|---|---| |Id |String |rd93\*\*\*\* |路由 ID。 | ## 返回示例 ```json Content-Type: application/json { "ResponseMetadata": { "RequestId": "20230604110420****100232280022D31", "Action": "CreateRoute", "Version": "2022-11-12", "Service": "apig", "Region": "cn-beijing" }, "Result": { "Id": "rd93****" } } ``` ## 错误码本接口错误码如下表所示，公共错误码请参见 [公共错误码](https://www.volcengine.com/docs/6569/1337089)。 |**HTTP 状态码** |**错误码** |**错误信息** |**说明** | |---|---|---|---| |400 |DomainPending |A custom domain is creating or deleting. |自定义域名正在创建或删除。请稍后重试。 |

API 网关