Help Center/ Elastic Cloud Server/ API Reference/ APIs/ NIC Management/ Adding NICs to an ECS in a Batch
Updated on 2025-12-10 GMT+08:00
View PDF
Share

Adding NICs to an ECS in a Batch

Function

This API is used to add one or multiple NICs to an ECS.

This API is an asynchronous API. After the NIC addition request is successfully delivered, a job ID is returned. This does not mean the NIC addition is complete. You need to call the API by referring to Querying Job Execution Status to query the job status. The SUCCESS status indicates that the NIC addition is successful.

Constraints

Do not detach or delete the NICs that are being added.

Debugging

You can debug this API in API Explorer.

Authorization

Each account has all of the permissions required to call all APIs, but IAM users must have the required permissions specifically assigned.
  • If you are using role/policy-based authorization, see the required permissions in Permissions and Supported Actions.
  • If you are using identity policy-based authorization, the permissions listed below are required.

Action

Access Level

Resource Type (*: required)

Condition Key

Alias

Dependencies

ecs:cloudServers:addNics

write

instance *
  • ecs:SubnetId
  • ecs:PortId

-

-

URI

POST /v1/{project_id}/cloudservers/{server_id}/nics

Table 1 describes the parameters in the URI.
Table 1 Parameter description

Parameter

Mandatory

Description

project_id

Yes

Specifies the project ID.

For details about how to obtain the ID, see Obtaining a Project ID.

server_id

Yes

Specifies the ECS ID.

Request

Table 2 describes the request parameters.
Table 2 Request parameters

Parameter

Mandatory

Type

Description

nics

Yes

Array of objects

Specifies the NICs to be added. For details, see Table 3.
Table 3 nics field description

Parameter

Mandatory

Type

Description

subnet_id

No

String

Specifies the information about the NICs to be added to an ECS.

The value must be the ID of a created network in UUID format.

security_groups

No

Array of objects

Specifies the security groups for NICs. For details, see Table 4.

ip_address

No

String

Specifies the IP address. If this parameter is unavailable, the IP address is automatically assigned.

port_id

No

String

Specifies the NIC ID in UUID format. If this parameter is not left blank, the specified NIC is attached. Either port_id or subnet_id can be left blank.

You can obtain the NIC ID using the VPC API for querying ports.

Constraints:

The NIC must be in DOWN state.

If both port_id and subnet_id are specified, port_id is used preferentially.

If port_id is specified, a network interface is used. In such a case, security_groups and ip_address do not take effect.

ipv6_enable

No

Boolean

Indicates whether to support IPv6 addresses.

If this parameter is set to true, the NIC supports IPv6 addresses.

ipv6_bandwidth

No

Object

Specifies the bound shared bandwidth. For details, see ipv6_bandwidth Field Description.
Table 4 security_groups field description

Parameter

Mandatory

Type

Description

id

Yes

String

Specifies the ID of the security group.

Response

Table 5 describes the response parameters.

Table 5 Response parameters

Parameter

Type

Description

job_id

String

Definition

Specifies the job ID returned after a job is delivered. The job ID can be used to query the job execution progress. For details about how to query the job execution status based on job_id, see Job Status Management.

Range

N/A

For details about abnormal responses, see Responses (Jobs).

Example Request

Add the NIC whose ID is d32019d3-bc6e-4319-9c1d-6722fc136a23 and security group ID is f0ac4394-7e4a-4409-9701-ba8be283dbc3 to an ECS.

POST https://{endpoint}/v1/{project_id}/cloudservers/{server_id}/nics

{
    "nics": [
        {
            "subnet_id": "d32019d3-bc6e-4319-9c1d-6722fc136a23", 
            "security_groups": [
                {
                    "id": "f0ac4394-7e4a-4409-9701-ba8be283dbc3"
                }
            ]
        }
    ]
}

Example Response

{      
    "job_id": "ff80808288d41e1b018990260955686a" 
}

Returned Values

See Returned Values for General Requests.

Error Codes

See Error Codes.

Parent topic: NIC Management