# pai-network

Part of **PAI**

# Platform for AI (PAI) Network Management

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|--------|----------|------|
| Get VPC Forward Information | Synchronous | Retrieve VPC forwarding configuration details. |
| Configure Network Settings | Synchronous | Set up network configurations for PAI resources. |
| Manage VCC | Async Task, Synchronous | Create, get, list, or initialize VCC connections. |
| Manage VCC Grant Rules | Synchronous | Create, delete, get, or list VCC grant rules. |
| Manage VCC Route Entries | Synchronous | Create, delete, get, or list VCC route entries. |
| Manage Elastic Network Interfaces | Synchronous | Create, delete, attach, detach, get, list, or update elastic network interfaces and their IP addresses. |
| Manage ER Attachments | Synchronous | Create, delete, get, list, or update network instance connections (ER attachments). |
| Manage ER Route Entries | Synchronous | Get or list ER route entries. |
| Manage Lingjun Hub (ER) | Synchronous | Get or list Lingjun hub instances. |
| Manage ER Route Maps | Async Task, Synchronous | Create, delete, get, list, or update ER routing policies. |
| Manage Subnets | Synchronous | Create, delete, get, list, or update subnets. |
| Manage VPD | Async Task, Synchronous | Create, delete, get, list, or update virtual private domains (VPD) and their CIDR blocks. |
| Manage VPD Grant Rules | Synchronous | Create, delete, get, or list VPD grant rules. |
| Manage VPD Route Entries | Synchronous | Get or list VPD route entries. |
| Query Network Information | Synchronous | Get node network info, destination CIDR blocks, or network topology. |
| Manage Network Resources | Synchronous | Handle flow control and RAM authorization for network resources. |
| Query Network Communication Distance | Synchronous | Query the network communication distance for an instance. |
| Query Network Test Result | Synchronous | Retrieve detailed results from completed network test tasks. |
| Manage ACL Policies | Synchronous | Create, delete, or list access control list (ACL) policies. |
| Manage Gateway VPC Peering | Synchronous | Create, delete, or list VPC peering connections for gateways. |
| Describe Resource DLink | Synchronous | Describe the VPC direct connection configuration for a resource. |
| Update VPC Direct Connection | Synchronous | Update the VPC direct connection settings for a resource. |
| Retry VCC | Synchronous | Retry VCC creation or deletion operations. |
| Update VCC | Synchronous | Update a VCC instance. |
| Detach ENI | Synchronous | Detach an elastic network interface from a node. |
| Update ER Route Map | Synchronous | Update an ER route map. |
| Switch VCC Connection | Synchronous | Switch the type of a VCC connection. |
| Query VCC Traffic | Synchronous | Query the traffic rate for Lingjun (VCC) connections. |
| Create Network Test Task | Synchronous | Initiate a network performance test task between specified endpoints. |

## API Calling Patterns

### Authentication
The primary authentication method is Bearer Token authentication.

- **Header format**: `Authorization: Bearer <your_api_key>`
- **Environment variable**: `DASHSCOPE_API_KEY`

### Service Endpoint
The APIs use a region-specific endpoint pattern.

- **Endpoint pattern**: `https://api.aliyun.com/api/eflo/2022-05-30/{operation}` for China regions and `https://api.alibabacloud.com/api/eflo/2022-05-30/{operation}` for international regions
- **Common regions**: `cn-wulanchabu`, `cn-hangzhou`, `cn-beijing`

### Async Task Pattern
Some operations like creating VCC, VPD, or ER route maps are asynchronous.

1. Submit the creation request with required parameters
2. The API immediately returns a task ID or resource ID
3. The system processes the request in the background
4. To check status, use synchronous GET or LIST operations (e.g., `GetVcc`, `ListVpds`) until the status shows as "Available"

### Synchronous Pattern
Most operations follow a synchronous request-response pattern:

1. Send a POST, GET, or DELETE request to the appropriate endpoint
2. Include the `Authorization: Bearer $DASHSCOPE_API_KEY` header
3. Provide required parameters in the request body (POST) or query string (GET)
4. Receive an immediate JSON response with operation result

## Parameter Reference

### Manage VCC

| Parameter | Type | Required | Default | Constraints | Description |
|------|------|------|--------|------|------|
| RegionId | string | false | | | The region ID. |
| ZoneId | string | false | | | The zone ID of the disk. |
| VccName | string | false | | | Lingjun Connection Name |
| VpdId | string | false | | | Lingjun CIDR block instance ID |
| CenId | string | false | | | CEN Instance ID |
| Description | string | false | | | The description of the document. |
| Bandwidth | integer | false | | min: 1000, max: 400000 | The bandwidth. Unit: Mbit /s. The minimum value is 1000, representing 1Gbps bandwidth; the maximum value is 400000, representing 400Gbps bandwidth. |
| Tag | array<object> | false | | max 20 tags | The tag information. You can specify up to 20 tags. |
| VccId | string | false | | | The ID of the Lingjun connection instance. |
| VpcId | string | false | | | Virtual Private Cloud IDs; What is Virtual Private Cloud You can call the DescribeVpcs operation to query the specified VPC. |
| ResourceGroupId | string | false | | | The resource group ID. For more information about resource groups, see Resource groups. |
| ConnectionType | string | false | | one of: VPC, CENTR | The connection mode. Valid values: VPC, CEN (CENTR) |
| VSwitchId | string | false | | | The ID of the vSwitch. Virtual Private Cloud Vswitch You can call the DescribeVSwitches operation to query created vSwitches. |
| BgpCidr | string | false | | | Internet segment, on-premises input, off-premises default |
| AccessCouldService | boolean | false | | one of: true, false | Enabled access to cloud services. Optional values: true: Enable access to cloud services, false: Do not enable access to cloud services |
| CenOwnerId | string | false | | | Account to which cen belongs |
| BgpAsn | integer | false | | | bgp as number |

### Manage Elastic Network Interfaces

| Parameter | Type | Required | Default | Constraints | Description |
|------|------|------|--------|------|------|
| RegionId | string | true | | | The region ID. |
| ZoneId | string | true | | | The ID of the zone. |
| NodeId | string | false | | | The ID of the Lingjun node. |
| VpcId | string | false | | | The ID of the VPC. This parameter is required if `NodeId` is not specified. This parameter is optional if `NodeId` is specified. |
| VSwitchId | string | false | | | The ID of the vSwitch. |
| SecurityGroupId | string | false | | | The ID of the security group. |
| Description | string | false | | | The description. |
| ResourceGroupId | string | false | | | The ID of the resource group. |
| EnableJumboFrame | boolean | false | | | Specifies whether to enable jumbo frames. |
| ClientToken | string | false | | | The POP API does not ignore duplicate requests by default, but it supports idempotent operations. |
| Tag | array<object> | false | | | The tag information. |

### Manage VPD

| Parameter | Type | Required | Default | Constraints | Description |
|------|------|------|--------|------|------|
| RegionId | string | true | | | The region ID of the disk. |
| VpdName | string | true | | | Lingjun CIDR block instance name |
| Cidr | string | true | | Must be a valid CIDR block; recommended: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 | The CIDR block of the VPD. We recommend that you use an RFC private endpoint as the Lingjun CIDR block, such as 10.0.0.0/8,172.16.0.0/12,192.168.0.0/16. In scenarios where the Doringjun CIDR block is connected to each other or where the Lingjun CIDR block is connected to a VPC, make sure that the addresses do not conflict with each other. You can also use a custom CIDR block other than 100.64.0.0/10, 224.0.0.0/4, 127.0.0.0/8, or 169.254.0.0/16 and their subnets as the primary IPv4 CIDR block of the VPD. |
| Subnets | array<object> | false | | Each subnet must have a CIDR that is a proper subset of the parent VPD's CIDR; mask between 16 and 29 bits | Lingjun subnet information list |
| ResourceGroupId | string | false | | | The resource group ID. For more information about resource groups, see Resource groups. |
| Tag | array<object> | false | | Up to 20 tags; key cannot start with 'aliyun' or 'acs:'; value can be empty or up to 128 characters | A tag. You can specify up to 20 tags. |

### Create Network Test Task

| Parameter | Type | Required | Default | Constraints | Description |
|------|------|------|--------|------|------|
| NetTestType | string | false | | one of: DelayTest, TrafficTest, CommTest | The type of network test. Valid values: DelayTest, TrafficTest, and CommTest. |
| Port | string | false | | | The test port number. |
| Protocol | string | false | | one of: RDMA, TCP | The network protocol. Valid values: RDMA and TCP. |
| TrafficModel | string | false | | one of: MTON, Fullmesh | The traffic model. Valid values: MTON and Fullmesh. |
| Duration | integer | false | | | The runtime duration of the flow task, in seconds. |
| QP | integer | false | | | If Protocol is set to TCP, specify the number of concurrent connections for the test. If Protocol is set to RDMA, specify the QP value. |
| GDR | boolean | false | | | If Protocol is set to RDMA, specify True or False. This field is empty if Protocol is set to TCP. |
| ClusterId | string | true | | | The cluster ID. |
| NetworkMode | string | true | | | The network mode. |
| ClusterName | string | true | | | The cluster name. |

## Code Examples

### Create a VCC Connection - Python - cn-wulanchabu

```python
import requests
import json

# API endpoint
url = "https://api.aliyun.com/api/eflo/2022-05-30/CreateVcc"

# Request headers
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Request payload
payload = {
    "RegionId": "cn-wulanchabu",
    "VccName": "my-vcc-connection",
    "VpdId": "vpd-eoiy88ju",
    "CenId": "cen-w15qot0pfvs83pkckj",
    "Bandwidth": 1000,
    "ConnectionType": "VPC",
    "VpcId": "vpc-f8ziirfl9k25h2qn7y4f8",
    "VSwitchId": "vsw-uf6u8473r84e9****"
}

# Make the API call
response = requests.post(url, headers=headers, data=json.dumps(payload))

# Parse response
if response.status_code == 200:
    data = response.json()
    print(json.dumps(data, indent=2))
else:
    print(f"Error: {response.status_code} - {response.text}")
```

### List VCC Connections - Python - all regions

```python
import requests
import json

# API endpoint
url = "https://api.aliyun.com/api/eflo/2022-05-30/ListVccs"

# Headers
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Parameters
params = {
    "RegionId": "cn-wulanchabu",
    "VpcId": "vpc-bp1nrtkmamy329u6a1z0i",
    "PageSize": 20,
    "PageNumber": 1
}

# Make the request
response = requests.get(url, headers=headers, params=params)

# Parse response
if response.status_code == 200:
    data = response.json()
    print(json.dumps(data, indent=2))
else:
    print(f"Error: {response.status_code} - {response.text}")
```

### Create an Elastic Network Interface - curl - all regions

```bash
curl -X POST https://api.aliyun.com/api/eflo/2022-05-30/CreateElasticNetworkInterface \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "RegionId": "cn-wulanchabu",
    "ZoneId": "cn-wulanchabu-b",
    "VpcId": "vpc-j6ctp4n75306phv5tmpsm",
    "VSwitchId": "vsw-uf6u8473r84e6n1n19he5",
    "SecurityGroupId": "sg-0jl5s4p4laalruk7****",
    "Description": "My ENI for PAI"
}'
```

### Query Network Test Results - Python - all regions

```python
import requests
import json

# API endpoint
url = "https://api.alibabacloud.com/api/eflo-controller/2022-12-15/ListNetTestResults"

# Headers
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Parameters
params = {
    "MaxResults": 20,
    "NetTestType": "DelayTest"
}

# Make the request
response = requests.get(url, headers=headers, params=params)

# Parse response
if response.status_code == 200:
    data = response.json()
    print(json.dumps(data, indent=2))
else:
    print(f"Error: {response.status_code} - {response.text}")
```

### Get VPD Details - curl - all regions

```bash
curl -X GET 'https://api.aliyun.com/api/eflo/2022-05-30/GetVpd?VpdId=vpd-ze3na***&RegionId=cn-wulanchabu' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json'
```

### Create a Network Test Task - curl - all regions

```bash
curl -X POST https://api.aliyun.com/api/eflo-controller/2022-12-15/CreateNetTestTask \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "NetTestType": "TrafficTest",
    "ClusterId": "cluster-12345",
    "NetworkMode": "standard",
    "ClusterName": "MyTestCluster",
    "TrafficTest": {
        "Protocol": "TCP",
        "TrafficModel": "Fullmesh",
        "Duration": 60,
        "QP": 4,
        "Clients": [
            {
                "ResourceId": "e01-cn-20s41p6cx01",
                "Bond": "bond1",
                "IP": "192.168.1.1",
                "ServerName": "client1"
            }
        ],
        "Servers": [
            {
                "ResourceId": "e01-cn-wwo3etaqu0b",
                "Bond": "bond1",
                "IP": "47.121.110.190",
                "ServerName": "server1"
            }
        ]
    }
}'
```

### Manage ACL Policy - curl - all regions

```bash
curl -X POST https://api.aliyun.com/api/eas/2021-07-01/CreateAclPolicy \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "ClusterId": "cn-wulanchabu",
    "GatewayId": "gw-1uhcqmsc7x22******",
    "VpcId": "vpc-uf66uio7md****",
    "AclPolicyList": [
        {
            "Entry": "192.168.0.0/16",
            "Comment": "Allow internal network"
        }
    ]
}'
```

### Query VCC Traffic - curl - all regions

```bash
curl -X POST https://api.aliyun.com/api/eflo/2022-05-30/ListVccFlowInfos \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "RegionId": "cn-wulanchabu",
    "VccId": "vcc-cn-zvp2w******",
    "MetricName": "passBytesRate",
    "Direction": "OUT"
}'
```

## Response Format

```json
{
  "Code": 0,
  "Message": "success",
  "RequestId": "039C3C3A-3C37-5672-80D5-D8CD48C676D1",
  "Content": {
    "VccId": "vcc-cn-zvp2w222001"
  },
  "AccessDeniedDetail": "None"
}
```

**Key Fields**:
- `Code` — Response status code (0 indicates success)
- `Message` — Human-readable description of the response status
- `RequestId` — Unique identifier for the API request (useful for troubleshooting)
- `Content` — Contains the operation-specific response data (e.g., resource IDs, configuration details)
- `AccessDeniedDetail` — Provides additional information when access is denied

## Error Handling

| Error Code (Code) | Description (Description) | Recommended Action (Recommended Action) |
|---------------|--------------------|-----------------------------|
| 400 | Bad request. Check the request parameters for errors. | Verify all required parameters are provided and formatted correctly. Check constraints like CIDR format, bandwidth limits, etc. |
| 403 | Forbidden. The user does not have sufficient permissions to perform this operation. | Ensure your API key has the necessary permissions. Check RAM policies and verify you have the required access level for the resource. |
| 404 | Not found. The specified resource (e.g., VPC, CEN) does not exist. | Confirm the resource IDs (VPC ID, CEN ID, etc.) are correct and exist in the specified region. |
| 500 | Internal server error. Try again later or contact support. | Retry the request after a short delay. If the issue persists, contact Alibaba Cloud support with the RequestId. |
| 429 | Too many requests. Rate limit exceeded. Reduce the request frequency or wait before retrying. | Implement exponential backoff in your client code. Check the rate limits section for specific quotas. |

### Rate Limits & Retry
- Most APIs have a rate limit of 100 requests per second per account
- Some operations like `AssignPrivateIpAddress` have stricter limits (60 requests per 60 seconds)
- Implement exponential backoff with jitter for retries
- For async operations, poll status endpoints with increasing intervals (e.g., 1s, 2s, 4s, 8s)

## Environment Requirements

- **Authentication**: Set the `DASHSCOPE_API_KEY` environment variable with your API key
- **SDK**: No specific SDK required; standard HTTP clients (requests, curl, etc.) work with the REST API
- **Python**: Any version that supports the `requests` library (Python 3.6+ recommended)

## FAQ

Q: How do I handle asynchronous operations like VCC or VPD creation?
A: After submitting the creation request, you'll receive an immediate response with a resource ID. The actual creation happens in the background. To check completion status, periodically call the corresponding GET or LIST API (e.g., `GetVcc` or `ListVpds`) until the status field shows "Available".

Q: What authentication method should I use for these APIs?
A: Use Bearer Token authentication by setting the `Authorization: Bearer YOUR_API_KEY` header in all requests. Store your API key securely in the `DASHSCOPE_API_KEY` environment variable.

Q: How can I troubleshoot permission errors (403 responses)?
A: First, verify your API key is valid and has the necessary permissions. Then check your RAM policies to ensure they include the required actions (e.g., `eflo:CreateVcc`, `eflo:GetVpd`). The `AccessDeniedDetail` field in the response may provide additional context.

Q: What's the difference between VCC and VPD in the Lingjun network?
A: VPD (Virtual Private Domain) represents a private CIDR block/network segment, while VCC (Virtual Connection) connects your Lingjun network environment with Alibaba Cloud network resources like VPC or CEN. VPD defines the address space, and VCC provides connectivity.

Q: How do I monitor network performance between my resources?
A: Use the network testing APIs: first create a test task with `CreateNetTestTask` specifying the test type (delay, traffic, or communication library), then retrieve results using `DescribeNetTestResult` or `ListNetTestResults`. For real-time traffic monitoring, use `ListVccFlowInfos`.

## Pricing & Billing

### Billing Model
Most operations follow a per-request billing model, where each API call counts as one request regardless of success or failure.

### Price Reference

| Tier/model | Input price | Output price | Other fees |
|-----------|---------|---------|---------|
| standard | 0.001 / | 0.001 / |
| default | 0.001 / | 0.001 / |
| CreateVpd | 0.01 / | |

### Free Tier
- Many operations include a monthly free tier of 100-1000 requests
- Some operations like `InitializeVcc` are completely free
- Free tier resets monthly

### Usage Limits
- Rate limits typically range from 20-100 requests per second per account
- Some operations have additional quotas (e.g., each tenant can create up to three additional CIDR blocks per region)

### Billing Notes
- Asynchronous tasks are billed upon completion
- Failed requests still count toward your usage quota and billing
- Minimum charge applies for long-running operations in some cases