Skip to content

Commit feecfda

Browse files
author
duongau
committed
create circuit placement API article
1 parent 169430c commit feecfda

File tree

1 file changed

+246
-0
lines changed

1 file changed

+246
-0
lines changed

‎articles/expressroute/circuit-placement-api.md

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
---
2+
title: 'Azure ExpressRoute CrossConnnections circuit placement API'
3+
description: This article provides a detailed overview for ExpressRoute partners about the ExpressRoute CrossConnections circuit placement API.
4+
services: expressroute
5+
author: mialdrid
6+
ms.service: expressroute
7+
ms.topic: conceptual
8+
ms.date: 10/19/2021
9+
ms.author: mialdrid
10+
---
11+
12+
# ExpressRoute circuit placement API
13+
14+
The ExpressRoute partner circuit placement API allows ExpressRoute partner to provision circuit connectivity on a specific port pair. Specifically, if an ExpressRoute partner manages multiple port pairs at one peering location, they can use this API to select which port pair will facilitate the ExpressRoute circuit.
15+
16+
This API uses the expressRouteCrossConnection resource type. For more information, see [ExpressRoute CrossConnection API development and integration](https://docs.microsoft.com/azure/expressroute/cross-connections-api-development)
17+
18+
## Workflow
19+
20+
1. ExpressRoute customers share the service key of the target ExpressRoute circuit.
21+
22+
1. ExpressRoute partner executes a GET using the expressRouteProviderPorts API to identify the **PortPairDescription** of the target port pair. The ExpressRoute partner can query a list of PortPairDescriptions across all port pairs in the subscription, or scope the query for a specific peering location.
23+
24+
1. Once the target PortPairDescription gets identified, the ExpressRoute partner does GET/PUT expressRouteCrossConnection to move the ExpressRoute circuit to the target port pair.
25+
26+
ExpressRoute partners manage layer-2 and layer-3 configuration by issuing REST operations against the expressRouteCrossConnections resource.
27+
28+
## API development and integration steps
29+
30+
### GET using the expressRouteProviderPorts API to list port pairs
31+
32+
The ExpressRoute partner can list all port pairs within the target provider subscription or they can list the port pairs within a specific peering location,
33+
34+
### To get a list of all port pairs for a provider
35+
36+
https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Network/expressRouteProviderPorts
37+
38+
#### Get Operation
39+
40+
```rest
41+
{
42+
"parameters": {
43+
"api-version": "2020-03-01",
44+
"subscriptionId": "subid"
45+
},
46+
"responses": {
47+
"200": {
48+
"body": {
49+
"value": [
50+
{
51+
"portPairDescriptor": "bvtazureixpportpair1",
52+
"id": "/subscriptions/subid/providers/Microsoft.Network/ExpressRouteProviderPort/bvtazureixpportpair1",
53+
"type": "Microsoft.Network/expressRouteProviderPort",
54+
"location": "uswest",
55+
"etag": "W/\"c0e6477e-8150-4d4f-9bf6-bb10e6acb63a\"",
56+
"properties": {
57+
"portPairDescriptor": "bvtazureixpportpair",
58+
"primaryAzurePort": "bvtazureixp01a",
59+
"secondaryAzurePort": "bvtazureixp01b",
60+
"peeringLocation": "SiliconValley",
61+
"overprovisionFactor": 4,
62+
"portBandwidthInMbps": 4000,
63+
"usedBandwidthInMbps": 2500,
64+
"remainingBandwidthInMbps": 1500
65+
}
66+
},
67+
{
68+
"portPairDescriptor": "bvtazureixpportpair2",
69+
"id": "/subscriptions/subid/providers/Microsoft.Network/ ExpressRouteProviderPort/bvtazureixpportpair2",
70+
"type": "Microsoft.Network/expressRouteProviderPort",
71+
"location": "uswest",
72+
"etag": "W/\"c0e6477e-8150-4d4f-9bf6-bb10e6acb63a\"",
73+
"properties": {
74+
"portPairDescriptor": "bvtazureixpportpair2",
75+
"primaryAzurePort": "bvtazureixp02a",
76+
"secondaryAzurePort": "bvtazureixp02b",
77+
"peeringLocation": "seattle",
78+
"overprovisionFactor": 4,
79+
"portBandwidthInMbps": 4000,
80+
"usedBandwidthInMbps": 1200,
81+
"remainingBandwidthInMbps": 1800
82+
}
83+
}
84+
]
85+
}
86+
}
87+
}
88+
}
89+
}
90+
}
91+
```
92+
93+
**Response status code**
94+
95+
* 200 (OK)  The request is success. It will fetch list of ports.
96+
* 4XX (Bad Request)  One of validations failed – for example: Provider subid is not valid.
97+
98+
### List of all port for a provider for a particular peering location
99+
100+
This is same API as above with an extra query parameter of location.
101+
102+
#### GET
103+
104+
https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Network/expressRouteProviderPorts?location={locationName}
105+
106+
#### GET Operation
107+
108+
```rest
109+
{
110+
"parameters": {
111+
"api-version": "2020-03-01",
112+
"locationName": "SiliconValley",
113+
"subscriptionId": "subid"
114+
},
115+
"responses": {
116+
"200": {
117+
"body": {
118+
"value": [
119+
{
120+
"portPairDescriptor": "bvtazureixpportpair1",
121+
"id": "/subscriptions/subid/providers/Microsoft.Network/ ExpressRouteProviderPort /bvtazureixpportpair1",
122+
"type": "Microsoft.Network/expressRouteProviderPort",
123+
"location": "uswest",
124+
"etag": "W/\"c0e6477e-8150-4d4f-9bf6-bb10e6acb63a\"",
125+
"properties": {
126+
"portPairDescriptor": "bvtazureixpportpair",
127+
"primaryAzurePort": "bvtazureixp01a",
128+
"secondaryAzurePort": "bvtazureixp01b",
129+
"peeringLocation": "SiliconValley",
130+
"overprovisionFactor": 4,
131+
"portBandwidthInMbps": 4000,
132+
"usedBandwidthInMbps": 2500,
133+
"remainingBandwidthInMbps": 1500
134+
}
135+
}
136+
]
137+
}
138+
}
139+
}
140+
}
141+
```
142+
143+
**Response status code**
144+
145+
* 200 (OK) The request is success. It will fetch list of ports.
146+
* 4XX (Bad Request) One of validations failed – for example: Provider subid isn't valid or location isn't valid.
147+
148+
To get port details of a particular port using port pair descriptor ID.
149+
150+
#### GET
151+
152+
https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Network/expressRouteProviderPorts/{portPairDescriptor}
153+
154+
#### GET Operation
155+
156+
```rest
157+
{
158+
"parameters": {
159+
"api-version": "2020-03-01",
160+
"portPairDescriptor": " bvtazureixpportpair1",
161+
"subscriptionId": "subid"
162+
},
163+
"responses": {
164+
"200": {
165+
"body": {
166+
"value":
167+
{
168+
"portPairDescriptor": "bvtazureixpportpair1",
169+
"id": "/subscriptions/subid/providers/Microsoft.Network/ExpressRouteProviderPort/bvtazureixpportpair1",
170+
"type": "Microsoft.Network/expressRouteProviderPort",
171+
"location": "uswest",
172+
"etag": "W/\"c0e6477e-8150-4d4f-9bf6-bb10e6acb63a\"",
173+
"properties": {
174+
"portPairDescriptor": "bvtazureixpportpair",
175+
"primaryAzurePort": "bvtazureixp01a",
176+
"secondaryAzurePort": "bvtazureixp01b",
177+
"peeringLocation": "SiliconValley",
178+
"overprovisionFactor": 4,
179+
"portBandwidthInMbps": 4000,
180+
"usedBandwidthInMbps": 2500,
181+
"remainingBandwidthInMbps": 15
182+
}
183+
}
184+
}
185+
}
186+
}
187+
}
188+
```
189+
190+
**Status code description**
191+
192+
* 200 (OK) The request is success. It will fetch port detail.
193+
* 204 The port pair with the mentioned descriptor ID isn't available.
194+
* 4XX (Bad Request) One of validations failed – For example: Provider subid isn't valid.
195+
196+
### PUT expressRouteCrossConnection API to move a circuit to a specific port pair
197+
198+
Once the portPairDescriptor of the target port pair is identified, the ExpressRoute Partner can use the expressRouteCrossConnection API to move the ExpressRoute circuit to a specific port pair.
199+
200+
https://docs.microsoft.com/en-us/rest/api/expressroute/express-route-cross-connections/create-or-update
201+
202+
Currently this API is used by providers to update provisioning state of circuit. This same API will be used by providers to update port pair of the circuit.
203+
204+
Currently the primaryAzurePort and secondaryAzurePort are read-only properties. Now we have disabled the read-only properties for these ports.
205+
206+
#### PUT
207+
208+
https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/expressRouteCrossConnections/{crossConnectionName}?api-version=2021-02-01
209+
210+
#### PUT Operation
211+
212+
```rest
213+
{
214+
"parameters": {
215+
"api-version": "2020-03-01",
216+
"crossConnectionName": "The name of the cross connection",
217+
"subscriptionId": "subid"
218+
}
219+
},
220+
{
221+
Request "body": {
222+
" primaryAzurePort ": " bvtazureixp03a"
223+
"secondaryAzurePort": "bvtazureixp03b",
224+
}
225+
}
226+
Response:
227+
{
228+
"name": "<circuitServiceKey>",
229+
"id": "/subscriptions/subid/resourceGroups/CrossConnectionSiliconValley/providers/Microsoft.Network/expressRouteCrossConnections/<circuitServiceKey>",
230+
"type": "Microsoft.Network/expressRouteCrossConnections",
231+
"location": "brazilsouth",
232+
"properties": {
233+
"provisioningState": "Enabled",
234+
"expressRouteCircuit": {
235+
"id": "/subscriptions/subid/resourceGroups/ertest/providers/Microsoft.Network/expressRouteCircuits/er1"
236+
},
237+
"peerings": [],
238+
"peeringLocation": "SiliconValley",
239+
"bandwidthInMbps": 1000,
240+
"primaryAzurePort": "bvtazureixp03a",
241+
"secondaryAzurePort": "bvtazureixp03b",
242+
"sTag": 2,
243+
"serviceProviderProvisioningState": "NotProvisioned"
244+
}
245+
}
246+
```

0 commit comments

Comments
 (0)