文档首页/ 云专线 DC/ API参考 (联盟区域) / API/ 虚拟接口/ 查询虚拟接口列表
更新时间：2026-01-08 GMT+08:00
在线调试
CLI示例
查看PDF
分享

查询虚拟接口列表

功能介绍

查询租户所有的虚拟接口列表

调用方法

请参见如何调用API。

URI

GET /v3/{project_id}/dcaas/virtual-interfaces

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

租户项目ID
表2 Query参数

参数

是否必选

参数类型

描述

limit

否

Integer

每页返回的个数。 取值范围：1~2000。

最小值：1

最大值：2000

缺省值：2000

marker

否

String

上一页最后一条资源记录的ID，为空时为查询第一页。 使用说明：必须与limit一起使用。

最小长度：0

最大长度：36

fields

否

Array

显示字段列表

数组长度：1 - 5

sort_dir

否

Array

返回结果按照升序(asc)或降序(desc)排列，默认为asc

sort_key

否

String

排序字段。

缺省值：id

最小长度：0

最大长度：36

enterprise_project_id

否

Array

根据企业项目ID过滤资源实例

数组长度：1 - 10

id

否

Array

根据资源ID过滤实例

数组长度：1 - 5

status

否

Array

根椐资源状态过滤实例

数组长度：1 - 5

direct_connect_id

否

Array

根椐物理专线ID过滤查询实例信息

数组长度：1 - 5

vgw_id

否

Array

根椐虚拟网关ID过滤查询实例信息

数组长度：1 - 5

请求参数

表3 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

是

String

用户Token。 获取Token，请参考《统一身份认证服务API参考》的“获取用户Token”章节。请求响应成功后在响应消息头中包含的“X-Subject-Token”的值即为Token值。

最小长度：0

最大长度：10240

响应参数

状态码： 200

表4 响应Body参数

参数

参数类型

描述

request_id

String

操作请求ID

virtual_interfaces

Array of VirtualInterface objects

虚拟接口对象

page_info

PageInfo object

分页查询页的信息
表5 VirtualInterface

参数

参数类型

描述

id

String

虚拟接口的ID

最大长度：36

name

String

虚拟接口的名字

最大长度：64

admin_state_up

Boolean

管理状态：true或false

bandwidth

Integer

虚拟接口接入带宽

最小值：2

最大值：2147483647

create_time

String

虚拟接口创建时间。采用UTC时间格式，格式为：yyyy-MM-ddTHH:mm:ss.SSSZ

最大长度：255

update_time

String

虚拟接口修改时间。采用UTC时间格式，格式为：yyyy-MM-ddTHH:mm:ss.SSSZ

最大长度：255

description

String

虚拟接口的描述

最大长度：128

direct_connect_id

String

物理专线的ID

最大长度：36

service_type

String

接入网关的类型：VGW、GDGW

status

String

操作状态，合法值是：ACTIVE，DOWN，BUILD，ERROR，PENDING_CREATE，PENDING_UPDATE，PENDING_DELETE，DELETED，AUTHORIZATION，REJECTED

tenant_id

String

租户ID

最小长度：32

最大长度：32

type

String

表示接口类型：private

缺省值：private

最大长度：255

枚举值：private

vgw_id

String

虚拟网关的ID

最小长度：36

最大长度：36

vlan

Integer

同用户网关对接的vlan, 配置范围0-3999

最小值：0

最大值：3999

route_limit

Integer

VIF远端子网路由配置规格

最小值：1

最大值：200

缺省值：50

enable_nqa

Boolean

是否使能nqa（Network Quality Analysis）功能：true或false

enable_bfd

Boolean

是否使能bfd（Bidirectional Forwarding Detection）功能：true或false

lag_id

String

VIF关联的链路聚合组ID

最小长度：36

最大长度：36

device_id

String

归属的设备ID

enterprise_project_id

String

实例所属企业项目ID

最小长度：36

最大长度：36

tags

Array of Tag objects

标签信息

数组长度：0 - 10

local_gateway_v4_ip

String

云侧网关IPv4接口地址，该字段现已经移到vifpeer参数列表中，未来将会废弃。

remote_gateway_v4_ip

String

客户侧网关IPv4接口地址，该字段现已经移到vifpeer参数列表中，未来将会废弃。

ies_id

String

归属的IES站点的ID

reason

String

如果资源的状态是Error的情况下，该参数会显示相关错误信息。

rate_limit

Boolean

标识虚拟接口是否开启限速

address_family

String

接口的地址簇类型，ipv4，ipv6。该字段现已迁移到vifpeer参数列表中，未来将会废弃。

local_gateway_v6_ip

String

云侧网关IPv6接口地址，该字段现已迁移到vifpeer参数列表中，未来将会废弃。

remote_gateway_v6_ip

String

客户侧网关IPv6接口地址，该字段现已迁移到vifpeer参数列表中，未来将会废弃。

lgw_id

String

本地网关的ID，用于IES场景。

gateway_id

String

虚拟接口关联的网关的ID。

remote_ep_group

Array of strings

远端子网列表，记录租户侧的cidrs。该字段现已迁移到vifpeer参数列表中，未来将会废弃。

service_ep_group

Array of strings

该字段用于公网专线接口，表示租户可以访问云上公网服务地址列表。该字段现已迁移到vifpeer参数列表中，未来将会废弃。

bgp_route_limit

Integer

BGP的路由配置规格

priority

String

虚拟接口的优先级，支持两种优先级状态normal和low。 接口优先级相同时表示负载关系，接口优先级不同时表示主备关系，出云流量优先转到优先级更高的normal接口。 目前仅BGP模式接口支持。

缺省值：normal

枚举值：

  • normal
  • low

vif_peers

Array of VifPeer objects

vif的Peer的相关信息

extend_attribute

VifExtendAttribute object

扩展参数信息
表6 Tag

参数

参数类型

描述

key

String
标签键。
  • 不能为空。
  • 对于同一资源标签键的取值唯一。
  • 最大长度36个unicode字符。
  • 仅允许使用数字、字母、中划线“-”、下划线“_”、符号“@”、点“.”。

value

String
标签值。
  • 可以为空。
  • 最大长度43个unicode字符。
  • 仅允许使用数字、字母、中划线“-”、下划线“_”、符号“@”、点“.”。
表7 VifPeer

参数

参数类型

描述

id

String

资源ID

最小长度：36

最大长度：36

tenant_id

String

归属租户ID

最小长度：36

最大长度：36

name

String

VIF对等体名字

最小长度：0

最大长度：64

description

String

VIF对等体名字描述信息

最小长度：0

最大长度：128

address_family

String

接口的地址簇类型，ipv4，ipv6

local_gateway_ip

String

VIF对等体云侧接口地址

remote_gateway_ip

String

VIF对等体客户侧接口地址

route_mode

String

路由模式：static/bgp

最大长度：255

枚举值：

  • bgp
  • static

bgp_asn

Integer

BGP邻居的AS号

最小值：1

最大值：4294967295

bgp_md5

String

BGP邻居的MD5密码

remote_ep_group

Array of strings

远端子网列表，记录租户侧的cidrs

service_ep_group

Array of strings

该字段用于公网专线接口,表示租户可以访问云上公网服务地址列表

device_id

String

归属的设备ID

bgp_route_limit

Integer

BGP的路由配置规格

bgp_status

String

接口BGP协议状态,如果是静态路由接口则状态为 null

最大长度：10

status

String

VIF对等体状态

vif_id

String

vif对等体对应的虚拟接口ID

最小长度：36

最大长度：36

receive_route_num

Integer

路由模式为bgp：receive_route_num值为接收搭配BGP的路由数目； 路由模式为static：该字段无意义，值为-1； 注：若早期接入云上的部分用户无法获取该字段信息，如需要请联系客服迁移专线端口。

enable_nqa

Boolean

是否使能nqa（Network Quality Analysis）功能：true或false

enable_bfd

Boolean

是否使能bfd（Bidirectional Forwarding Detection）功能：true或false
表8 VifExtendAttribute

参数

参数类型

描述

ha_type

String

虚拟接口的可用性检测类型

枚举值：

  • nqa
  • bfd

ha_mode

String

检测的具体的配置模式

枚举值：

  • auto_single
  • auto_multi
  • static_single
  • static_multi
  • enhance_nqa

detect_multiplier

Integer

检测的重试次数

缺省值：5

min_rx_interval

Integer

检测的接收时长间隔

缺省值：1000

min_tx_interval

Integer

检测的发送时长间隔

缺省值：1000

remote_disclaim

Integer

检测的远端的标识，用于静态BFD

local_disclaim

Integer

检测的本端的标识，用于静态BFD
表9 PageInfo

参数

参数类型

描述

previous_marker

String

上一页的marker，值为资源的uuid

最小长度：0

最大长度：36

current_count

Integer

当前列表中资源数量

最小值：0

最大值：2000

next_marker

String

下一页的marker，值为资源的uuid，为空时表示最后一页

最小长度：0

最大长度：36

请求示例

查询虚拟接口列表

GET https://{dc_endpoint}/v3/0605768a3300d5762f82c01180692873/dcaas/virtual-interfaces

响应示例

状态码： 200

OK

{
  "virtual_interfaces" : [ {
    "id" : "0d0fdf63-f2c4-491c-8866-d504796189be",
    "name" : "vif-0819",
    "description" : "mytest",
    "tenant_id" : "0605768a3300d5762f82c01180692873",
    "direct_connect_id" : "4673e339-8412-4ee1-b73e-2ba9cdfa54c1",
    "vgw_id" : "8a47064a-f34c-4f94-b7fe-cac456c9b37b",
    "type" : "private",
    "service_type" : "VGW",
    "vlan" : 332,
    "bandwidth" : 2,
    "status" : "ACTIVE",
    "create_time" : "2022-08-19T11:28:06.000Z",
    "update_time" : "2022-08-19T11:28:06.000Z",
    "admin_state_up" : true,
    "enable_bfd" : false,
    "route_limit" : 50,
    "enable_nqa" : false,
    "local_gateway_v4_ip" : "1.1.1.1/30",
    "remote_gateway_v4_ip" : "1.1.1.2/30",
    "ies_id" : null,
    "reason" : null,
    "rate_limit" : false,
    "address_family" : "ipv4",
    "local_gateway_v6_ip" : null,
    "remote_gateway_v6_ip" : null,
    "lgw_id" : null,
    "gateway_id" : null,
    "remote_ep_group" : [ "1.1.2.0/30" ],
    "service_ep_group" : [ ],
    "bgp_route_limit" : 100,
    "priority" : "normal",
    "tags": [],
    "vif_peers" : [ {
      "id" : "c768eb52-12a8-4859-9b43-81194643040c",
      "tenant_id" : "0605768a3300d5762f82c01180692873",
      "name" : "vif-0819",
      "description" : "",
      "address_family" : "ipv4",
      "local_gateway_ip" : "1.1.1.1/30",
      "remote_gateway_ip" : "1.1.1.2/30",
      "route_mode" : "static",
      "bgp_asn" : null,
      "bgp_md5" : null,
      "device_id" : "18.9.215.131",
      "bgp_route_limit" : 100,
      "bgp_status" : null,
      "status" : "ACTIVE",
      "vif_id" : "0d0fdf63-f2c4-491c-8866-d504796189be",
      "receive_route_num" : -1,
      "remote_ep_group" : [ "1.1.2.0/30" ],
      "service_ep_group" : null,
      "enable_bfd" : false,
      "enable_nqa" : false
    } ],
    "enterprise_project_id" : "0"
  } ],
  "request_id" : "5633df7af874576d819a481c76673236"
}

状态码

状态码

描述

200

OK

错误码

请参见错误码。

父主题： 虚拟接口