DescribePhysicalConnections API Overview - Express Connect - Alibaba Cloud - Express Connect

Queries information about Express Connect circuits in a specified region.

Operation description

By default, the system queries information about all Express Connect circuits in the specified region. You can use the filter options provided by the DescribePhysicalConnections operation to query information about specific Express Connect circuits. For the filter options supported by the system, see the description of Key in the request parameters section of this topic.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

vpc:DescribePhysicalConnections

list

*PhysicalConnection

acs:vpc:{#regionId}:{#accountId}:physicalconnection/*

None

Request parameters

Parameter	Type	Required	Description	Example
RegionId	string	Yes	The region ID of the Express Connect circuit. You can call the DescribeRegions operation to query the region ID.	cn-hangzhou
PageNumber	integer	No	The page number of the list. Default value: 1.	1
PageSize	integer	No	The number of entries per page in a paged query. Default value: 10. Valid values: 1 to 50.	10
IncludeReservationData	boolean	No	Specifies whether to return order data that has not taken effect. Valid values: true: Returns order data that has not taken effect. false (default): Does not return order data that has not taken effect.	false
ClientToken	string	No	The client token that is used to ensure the idempotence of the request. Generate a parameter value from your client to ensure uniqueness across different requests. ClientToken supports only ASCII characters.	02fb3da4-130e-11e9-8e44-001
Filter	array<object>	No	The list of filter conditions.
	object	No	The filter condition.
Key	string	No	The filter condition. Valid values: PhysicalConnectionId: the ID of the Express Connect circuit. AccessPointId: the ID of the access point. Type: the type of the Express Connect circuit. This filter condition supports only the filter value VPC. LineOperator: the carrier of the Express Connect circuit. This filter condition supports the following filter values: CT: China Telecom. CU: China Unicom. CM: China shift. CO: Other carriers in the Chinese mainland. Equinix: Equinix. Other: Other carriers outside the Chinese mainland. Spec: the specification of the Express Connect circuit. This filter condition supports the following filter values: 1G and below. 10G. 40G. 100G. Note The 40G and 100G specifications are not available by default. Only users who have submitted an application to their account manager and received approval can use these filter values. Status: the status of the Express Connect circuit. This filter condition supports the following filter values: Initial: pending application. Approved: approved. Allocating: allocating resources. Allocated: under construction. Confirmed: pending user confirmation. Enabled: enabled. Rejected: application rejected. Canceled: canceled. Allocation Failed: resource allocation failed. Terminating: stopping. Terminated: stopped. Name: the name of the Express Connect circuit. ProductType: the type of the Express Connect circuit. Valid values: VirtualPhysicalConnection: shared Express Connect circuit. PhysicalConnection: dedicated Express Connect circuit. You can specify up to 5 filter conditions at a time. The filter conditions have an AND relationship. Results are returned only when all filter conditions are met.	Name
Value	array	No	The list of filter values.	1
	string	No	The filter value that corresponds to the filter condition. Each filter condition supports up to 5 filter values. Multiple filter values have an OR relationship. A record is considered to match the filter condition if it matches any of the filter values.	nametest
Tags	array<object>	No	The list of tags.
	object	No	The list of tags.
Key	string	No	The tag key of the resource. You can specify up to 20 tag keys. The tag key cannot be an empty string. The tag key can be up to 64 characters in length and can contain digits, periods (.), underscores (_), and hyphens (-). It cannot start with `aliyun` or `acs:`, and cannot contain `http://` or `https://`.	FinanceDept
Value	string	No	The tag value of the resource. You can specify up to 20 tag values. The tag value can be an empty string. The tag value can be up to 128 characters in length and can contain digits, periods (.), underscores (_), and hyphens (-). It cannot start with `aliyun` or `acs:`, and cannot contain `http://` or `https://`.	FinanceJoshua
ResourceGroupId	string	No	The ID of the resource group to which the Express Connect circuit belongs.	rg-aek2yvwibxr****

Response elements

Element	Type	Description	Example
	object	The response parameters.
RequestId	string	The request ID.	0E6D0EC4-7C91-53E2-9F65-64BF713114B0
PageNumber	integer	The page number of the list. Default value: 1.	1
PageSize	integer	The number of entries per page in a paged query. Default value: 10. Valid values: 1 to 50.	10
TotalCount	integer	The total number of entries returned.	1
PhysicalConnectionSet	object
PhysicalConnectionType	array<object>	The list of Express Connect circuits.
	array<object>	The details of the Express Connect circuit.
Type	string	The type of the Express Connect circuit. Valid values: VPC.	VPC
Status	string	The status of the Express Connect circuit. Valid values: Initial: The application is under review. Approved: The application is approved. Allocating: Resources are being allocated. Allocated: Under construction. Confirmed: Waiting for user confirmation. Enabled: Enabled. Rejected: The application is rejected. Canceled: Canceled. Allocation Failed: Resource allocation failed. Terminating: Being terminated. Terminated: Terminated.	Enabled
CreationTime	string	The time when the Express Connect circuit was created. The time is displayed in the ISO 8601 standard in the YYYY-MM-DDThh:mm:ssZ format. The time is displayed in UTC.	2021-08-24T07:30:58Z
AdLocation	string	The location of the access device of the Express Connect circuit at the access point.	Hangzhou City, Zhejiang Province, China
ReservationActiveTime	string	The effective period of the pending order. The time is displayed in the ISO 8601 standard in the YYYY-MM-DDThh:mm:ssZ format. The time is displayed in UTC.	2022-02-25T11:01:04Z
ReservationOrderType	string	The type of the pending order. Valid values: RENEW, which indicates a renewal order.	RENEW
PortNumber	string	The port number of the access device of the Express Connect circuit.	1/1/1
Spec	string	The specification of the Express Connect circuit. Unit: G indicates Gbit/s.	10G
ChargeType	string	The billing method of the Express Connect circuit. Valid values: Prepaid, which indicates subscription.	Prepaid
ReservationInternetChargeType	string	The billing method of the pending order. Valid values: PayByBandwidth, which indicates pay-by-bandwidth.	PayByBandwidth
Description	string	The description of the Express Connect circuit.	desctest
Bandwidth	integer	The bandwidth of the Express Connect circuit. Unit: Mbit/s.	10
EnabledTime	string	The time when the Express Connect circuit was enabled. The time is displayed in the ISO 8601 standard in the YYYY-MM-DDThh:mm:ssZ format. The time is displayed in UTC.	2021-08-24T07:33:18Z
LineOperator	string	The connectivity provider of the Express Connect circuit. Valid values: CT: China Telecom. CU: China Unicom. CM: China Mobile. CO: Other Chinese connectivity providers. Equinix: Equinix. Other: Other connectivity providers outside the Chinese mainland.	CT
PeerLocation	string	The geographic location of the on-premises data center.	Hangzhou City, Zhejiang Province, China
RedundantPhysicalConnectionId	string	The ID of the redundant Express Connect circuit.	pc-119mfjzm****
Name	string	The name of the Express Connect circuit.	nametest
CircuitCode	string	The circuit code provided by the connectivity provider for the Express Connect circuit.	longtel001
EndTime	string	The expiration time of the Express Connect circuit. The time is displayed in the ISO 8601 standard in the YYYY-MM-DDThh:mm:ssZ format. The time is displayed in UTC.	2022-04-24T16:00:00Z
PortType	string	The port type of the Express Connect circuit. Valid values: 100Base-T: 100M Ethernet port. 1000Base-T: 1 GE port. 1000Base-LX: GE single-mode optical port (10 km). 10GBase-T: 10 GE port. 10GBase-LR: 10 GE single-mode optical port (10 km). 40GBase-LR: 40 GE single-mode optical port. 100GBase-LR: 100 GE single-mode optical port. Note To use 40GBase-LR or 100GBase-LR, check the port availability with your account manager.	10GBase-LR
BusinessStatus	string	The business status of the Express Connect circuit. Valid values: Normal: Enabled. FinancialLocked: Locked due to overdue payment. SecurityLocked: Locked for security reasons.	Normal
LoaStatus	string	The status of the Letter of Authorization (LOA). Valid values: Applying: The LOA application is being processed. Accept: The LOA application is approved. Available: The LOA is available. Rejected: The LOA application is rejected. Completing: The circuit is under construction. Complete: The circuit construction is complete. Deleted: The LOA is deleted.	Available
AccessPointId	string	The ID of the access point of the Express Connect circuit.	ap-cn-hangzhou-finance-yh-E
AccessPointType	string	The type of the access point of the Express Connect circuit.	VPC
HasReservationData	string	Indicates whether the Express Connect circuit has pending order data. Valid values: true: The circuit has pending order data. false: The circuit does not have pending order data.	false
PhysicalConnectionId	string	The instance ID of the Express Connect circuit.	pc-bp1ciz7ekd2grn1as****
ProductType	string	The type of the Express Connect circuit. Valid values: VirtualPhysicalConnection: Shared Express Connect circuits. PhysicalConnection: Dedicated Express Connect circuit.	PhysicalConnection
VirtualPhysicalConnectionCount	integer	The number of shared Express Connect circuits created on the current Express Connect circuit.	0
ParentPhysicalConnectionId	string	The instance ID of the Express Connect circuit associated with the shared Express Connect circuits.	pc-bp1ciz7ekd2grn1as****
ParentPhysicalConnectionAliUid	integer	The Alibaba Cloud account ID of the owner of the Express Connect circuit associated with the shared Express Connect circuits.	132193271328****
VlanId	string	The VLAN ID of the shared Express Connect circuits.	10
OrderMode	string	The payer of the shared Express Connect circuits. Valid values: PayByPhysicalConnectionOwner: The partner is the payer. PayByVirtualPhysicalConnectionOwner: The tenant is the payer.	PayByPhysicalConnectionOwner
VpconnStatus	string	The business status of the shared Express Connect circuits. Valid values: Confirmed: The shared Express Connect circuits are accepted. UnConfirmed: The shared Express Connect circuits are not accepted. Deleted: The shared Express Connect circuits are deleted.	Confirmed
ExpectSpec	string	The expected bandwidth of the shared Express Connect circuits. The expected bandwidth takes effect after payment is completed. Unit: M indicates Mbit/s, G indicates Gbit/s.	50M
ResourceGroupId	string	The resource group ID.	rg-acfmwu3k52p****
AdDetailLocation	string	The information about the data center and rack.	Hangzhou City, Zhejiang Province, XX Data Center, Room ET135ET135-XX-2, Rack JXX, Position 30
Tags	object
tags	array<object>	The list of tags.
	object	The list of tags.
Key	string	The tag key of the resource. You can specify up to 20 tag keys. The tag key cannot be an empty string. The tag key can be up to 64 characters in length and can contain digits, periods (.), underscores (_), and hyphens (-). It cannot start with `aliyun` or `acs:`, and cannot contain `http://` or `https://`.	FinanceDept
Value	string	The tag value of the resource. You can specify up to 20 tag values. The tag value can be an empty string. The tag value can be up to 128 characters in length and can contain digits, periods (.), underscores (_), and hyphens (-). It cannot start with `aliyun` or `acs:`, and cannot contain `http://` or `https://`.	FinanceJoshua
QosId	string	The instance ID of the QoS policy.	qos-bp10s3szn8rgnxuw7****
OpticalModuleModel	string	The optical module model entered by the user.	SFP-GE-LR-SM1310,10KM
MacsecKeys	object
MacsecKey	array<object>	The list of MACSec key information for the Express Connect circuit.
	object	The MACSec key information for the Express Connect circuit.
CipherSuite	string	The MACSec cipher suite. Valid values: ● GCM-AES-128 ● GCM-AES-XPN-128 ● GCM-AES-256 ● GCM-AES-XPN-256	GCM-AES-128
Ckn	string	The key name.	0123456789ABCDEF0123456789ABCDEF
Cak	string	The key secret.	0123456789ABCDEF0123456789ABCDEF
StartOn	string	The time when the key was created. The time is displayed in the ISO 8601 standard in the YYYY-MM-DDThh:mm:ssZ format. The time is displayed in UTC.	2026-04-13T00:00:00Z
Status	string	The key status. Valid values: ● Associating: Being associated. ● Associated: Associated. ● AssociatedFailed: Association failed. ● Disassociating: Being disassociated. ● Disassociated: Disassociated.	Associated
DownDelayTime	integer	The port down delay time of the Express Connect circuit, in milliseconds. When a physical link down event is detected, the access device waits for this duration before setting the port to down status. This prevents transient disconnections from affecting services. Valid values: 0 to 10000. The step is 100. A value of 0 indicates that the port goes down immediately after the link is down (default). You can modify this value by calling the ModifyPhysicalConnectionAttribute operation.	100
DeviceFeaturesSelected	string	The list of advanced capabilities selected for the access device of the Express Connect circuit. Multiple capabilities are separated by commas (,).	BFD,MACSec,LinkDelay

Examples

Success response

JSON format

{
  "RequestId": "0E6D0EC4-7C91-53E2-9F65-64BF713114B0",
  "PageNumber": 1,
  "PageSize": 10,
  "TotalCount": 1,
  "PhysicalConnectionSet": {
    "PhysicalConnectionType": [
      {
        "Type": "VPC",
        "Status": "Enabled",
        "CreationTime": "2021-08-24T07:30:58Z",
        "AdLocation": "Hangzhou City, Zhejiang Province, China",
        "ReservationActiveTime": "2022-02-25T11:01:04Z",
        "ReservationOrderType": "RENEW",
        "PortNumber": "1/1/1",
        "Spec": "10G",
        "ChargeType": "Prepaid",
        "ReservationInternetChargeType": "PayByBandwidth",
        "Description": "desctest",
        "Bandwidth": 10,
        "EnabledTime": "2021-08-24T07:33:18Z",
        "LineOperator": "CT",
        "PeerLocation": "Hangzhou City, Zhejiang Province, China",
        "RedundantPhysicalConnectionId": "pc-119mfjzm****",
        "Name": "nametest",
        "CircuitCode": "longtel001",
        "EndTime": "2022-04-24T16:00:00Z",
        "PortType": "10GBase-LR",
        "BusinessStatus": "Normal",
        "LoaStatus": "Available",
        "AccessPointId": "ap-cn-hangzhou-finance-yh-E",
        "AccessPointType": "VPC",
        "HasReservationData": "false",
        "PhysicalConnectionId": "pc-bp1ciz7ekd2grn1as****",
        "ProductType": "PhysicalConnection",
        "VirtualPhysicalConnectionCount": 0,
        "ParentPhysicalConnectionId": "pc-bp1ciz7ekd2grn1as****",
        "ParentPhysicalConnectionAliUid": 0,
        "VlanId": "10",
        "OrderMode": "PayByPhysicalConnectionOwner",
        "VpconnStatus": "Confirmed",
        "ExpectSpec": "50M",
        "ResourceGroupId": "rg-acfmwu3k52p****",
        "AdDetailLocation": "Hangzhou City, Zhejiang Province, XX Data Center, ET135ET135-XX-2 Room, JXX Rack, position30",
        "Tags": {
          "tags": [
            {
              "Key": "FinanceDept",
              "Value": "FinanceJoshua"
            }
          ]
        },
        "QosId": "qos-bp10s3szn8rgnxuw7****",
        "OpticalModuleModel": "SFP-GE-LR-SM1310,10KM",
        "MacsecKeys": {
          "MacsecKey": [
            {
              "CipherSuite": "GCM-AES-128",
              "Ckn": "0123456789ABCDEF0123456789ABCDEF",
              "Cak": "0123456789ABCDEF0123456789ABCDEF",
              "StartOn": "2026-04-13T00:00:00Z",
              "Status": "Associated"
            }
          ]
        },
        "DownDelayTime": 100,
        "DeviceFeaturesSelected": "BFD,MACSec,LinkDelay"
      }
    ]
  }
}

Error codes

HTTP status code	Error code	Error message	Description
400	OperationUnsupported.ResourceGroupId	ResourceGroupId in financial region is unsupported.	The operation is not supported because Alibaba Finance Cloud does not support resource group IDs.
400	InvalidTagKey.Malformed	The specified tag key is invalid.	Invalid tag key value. Specify a valid tag key value and try again.
400	OperationFailed.InternalError	The request processing has failed due to some unknown error.	Unknown error. Please retry the operation. The error still exists. Please submit the work order for processing.
404	InvalidFilterKey.ValueNotSupported	Specified filter key is not supported: Filter.X.key	Filter.X.key is not supported.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.