批量查询路由详情。 ## 请求说明 * 请求方式：POST * 请求地址：https://open.volcengineapi.com?Action=ListRoutes&Version=2022\-11\-12 ## 调试 [去调试](https://api.volcengine.com/api-explorer/debug?action=ListRoutes&serviceCode=apig&version=2022-11-12&groupName=) ## 请求参数 |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |Action |String |是 |ListRoutes |接口名称。当前 API 的名称为 `ListRoutes`。 | |Version |String |是 |2022\-11\-12 |接口版本。当前 API 的版本为 `2022-11-12`。 | |PageNumber |Long |否 |1 |分页查询的页号。取值最小限制为 1，默认值为 1。 | |PageSize |Long |否 |10 |每页个数。取值范围为 0~100，默认值为 10。 | |GatewayId |String |否 |gd8\*\*\*\* |网关实例 ID。您可以通过 [ListGateways](https://www.volcengine.com/docs/6569/1337084?lang=zh) 查询网关实例 ID。 | |ServiceId |String |否 |sd84\*\*\*\* |服务 ID。您可以通过 [ListGatewayServices](https://www.volcengine.com/docs/6569/1628097?lang=zh) 查询服务 ID。 | |UpstreamId |String |否 |ud93\*\*\*\* |后端服务 Upstream ID。您可以通过 [ListUpstreams](https://www.volcengine.com/docs/6569/1628108?lang=zh) 查询 Upstream ID。 | |UpstreamVersion |String |否 |test |后端服务 Upstream 版本。 | |Filter |Object of [RouteFilter](https://www.volcengine.com/docs/6569/1628103#routefilter) |否 |\- |过滤条件。 | ### RouteFilter |**参数** |**类型** |**是否必选** |**示例值** |**描述** | |---|---|---|---|---| |Name |String |否 |example |路由名称。 | |UpstreamIds |Array of String |否 |["ud93\*\*\*\*"] |后端服务 Upstream ID。您可以通过 [ListUpstreams](https://www.volcengine.com/docs/6569/1628108?lang=zh) 查询 Upstream ID。 | |Path |String |否 |/ |允许访问的请求路径。

* 必须以（/）开头，（/）不能超过 30 个。

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

* 不能包含空格。请求路径。 | ## 请求示例 ```json POST https://open.volcengineapi.com?Action=ListRoutes&Version=2022-11-12 Content-Type: application/json { "PageNumber": 1, "PageSize": 10, "GatewayId": "gd8****", "ServiceId": "sd84****", "UpstreamId": "ud93****", "UpstreamVersion": "", "Filter": { "Name": "example", "Path": "/", "UpstreamIds": [ "ud93****" ] } } ``` ## 返回参数 |**参数** |**类型** |**示例值** |**描述** | |---|---|---|---| |Total |Long |10 |过滤后的路由总个数。 | |Items |Array of [RouteResponse](https://www.volcengine.com/docs/6569/1628103#routeresponse) |\- |路由列表。 | ### RouteResponse |**参数** |**类型** |**示例值** |**描述** | |---|---|---|---| |Id |String |rd93\*\*\*\* |路由 ID。 | |Name |String |example |路由名称。 | |ServiceId |String |sd84\*\*\*\* |路由所属服务的 ID。 | |ServiceName |String |example |路由所属服务的名称。 | |CreateTime |String |2025\-01\-01T00:00:00+08:00 |路由创建时间。

标准 [RFC3339](https://tools.ietf.org/html/rfc3339) 格式的 UTC+8 时间。 | |UpdateTime |String |2025\-01\-01T00:00:00+08:00 |路由更新时间。

标准 [RFC3339](https://tools.ietf.org/html/rfc3339) 格式的 UTC+8 时间。 | |MatchRule |Object of [MatchRule](https://www.volcengine.com/docs/6569/1628103#matchrule) |\- |匹配规则。 | |UpstreamList |Array of [RouteUpstream](https://www.volcengine.com/docs/6569/1628103#routeupstream) |\- |Upstream 流量分发。 | |AdvancedSetting |Object of [RouteAdvancedSetting](https://www.volcengine.com/docs/6569/1628103#routeadvancedsetting) |\- |高级配置。 | |Domains |Array of [Server](https://www.volcengine.com/docs/6569/1628103#server) |\- |默认域名。 | |Enable |Boolean |true |是否开启路由上下线功能。取值：

* **true**：开启。

* **false**：不开启。

说明

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

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

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

* 不能包含空格。 | |Header |Array of [StringMatchItem](https://www.volcengine.com/docs/6569/1628103#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/1628103#timeoutsetting) |\- |超时配置。 | |CorsPolicySetting |Object of [CorsPolicySetting](https://www.volcengine.com/docs/6569/1628103#corspolicysetting) |\- |跨域配置。 | |URLRewriteSetting |Object of [URLRewriteSetting](https://www.volcengine.com/docs/6569/1628103#urlrewritesetting) |\- |URL 重写配置。

说明

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

| |HeaderOperations |Array of [HeaderOperation](https://www.volcengine.com/docs/6569/1628103#headeroperation) |\- |修改请求头。长度限制为 0~5 个。 | |MirrorPolicies |Array of [MirrorPolicy](https://www.volcengine.com/docs/6569/1628103#mirrorpolicy) |\- |流量镜像。长度限制为 0~1 个。 | |RetryPolicySetting |Object of [RetryPolicySetting](https://www.volcengine.com/docs/6569/1628103#retrypolicysetting) |\- |重试配置。 | ### Server |**参数** |**类型** |**示例值** |**描述** | |---|---|---|---| |Domain |String |http://example.apigateway\-cn\-beijing.volceapi.com |默认域名地址。 | |Type |String |public |默认域名类型，取值：

* **public**：公网。

* **private**：私网。 | ### CustomDomain |**参数** |**类型** |**示例值** |**描述** | |---|---|---|---| |Id |String |d\*\*\*\* |自定义域名 ID。 | |Domain |String |example.com |自定义域名。 | ### FallbackSetting |**参数** |**类型** |**示例值** |**描述** | |---|---|---|---| |Enable |Boolean |false |是否开启 Fallback。取值

* **true**：开启。

* **false**：不开启。 | |FallbackUpstreams |Array of [RouteUpstream](https://www.volcengine.com/docs/6569/1628103#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/1628103#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/1628103#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/1628103#mirrorupstream) |\- |后端 Upstream 配置。 | |Percent |Object of [PercentSetting](https://www.volcengine.com/docs/6569/1628103#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。 | ## 返回示例 ```json Content-Type: application/json { "ResponseMetadata": { "RequestId": "20230604110420****100232280022D31", "Action": "ListRoutes", "Version": "2022-11-12", "Service": "apig", "Region": "cn-beijing" }, "Result": { "Total": 10, "Items": [ { "Id": "rd93****", "Name": "example", "Enable": true, "Domains": [ { "Type": "public", "Domain": "http://example.apigateway-cn-beijing.volceapi.com" } ], "Priority": 100, "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": [] }, "ServiceId": "sd84****", "CreateTime": "2025-01-01T00:00:00+08:00", "UpdateTime": "2025-01-01T00:00:00+08:00", "ServiceName": "example", "UpstreamList": [ { "Weight": 100, "Version": "", "UpstreamId": "ud93****", "AIProviderSettings": { "Model": "doubao-seed-2-0-pro-260215", "PrefixPath": "/ep", "TargetPath": "/chat/completions" } } ], "CustomDomains": [ { "Id": "d****", "Domain": "example.com" } ], "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": false }, "URLRewriteSetting": { "Enable": true, "URLRewrite": "/v2/" }, "RetryPolicySetting": { "Enable": true, "RetryOn": [ "5xx", "reset", "connect-failure" ], "Attempts": 2, "HttpCodes": [ "500" ] } }, "FallbackSetting": { "Enable": true, "Conditions": [ "4xx" ], "FallbackUpstreams": [] } } ] } } ``` ## 错误码本接口无特有的错误码。更多信息请参见 [公共错误码](https://www.volcengine.com/docs/6569/1337089)。

API 网关