Assigns a public IP address to an Elastic Compute Service (ECS) instance.

Description

When you call this operation, take note of the following items:

  • The instance to which to assign a public IP address must be in the Running (Running) or Stopped (Stopped) state.
  • If OperationLocks in the DescribeInstances response contains "LockReason" : "security" for an instance, the instance is locked for security reasons and cannot be assigned a public IP address.
  • You can assign only a single public IP address to an instance. If the instance already has a public IP address, the AllocatedAlready error code is returned.
  • After you assign a public IP address to an instance, you must restart the instance (RebootInstance) or start the instance (StartInstance) for the public IP address to take effect.

If an instance is located in a virtual private cloud (VPC), you can assign a public IP address to the instance or associate an elastic IP address (EIP) with the instance. For more information, see AssociateEipAddress.

Note After an EIP is associated with an instance located in a VPC, no public IP addresses can be assigned to the instance.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes AllocatePublicIpAddress

The operation that you want to perform. Set the value to AllocatePublicIpAddress.

InstanceId String Yes i-bp1gtjxuuvwj17zr****

The ID of the instance to which to assign a public IP address.

IpAddress String No 112.124.**.**

The public IP address to assign to the instance. If you leave this parameter empty, the system randomly assigns a public IP address to the specified instance.

VlanId String No 720

The virtual LAN (VLAN) ID of the instance.

Note This parameter will be removed in the future. We recommend that you use other parameters to ensure future compatibility.

Response parameters

Parameter Type Example Description
IpAddress String 112.124.**.**

The public IP address assigned to the instance.

RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

The ID of the request.

Examples

Sample requests

https://ecs.aliyuncs.com/?Action=AllocatePublicIpAddress
&InstanceId=i-bp1gtjxuuvwj17zr****
&IpAddress=112.124.**.**
&<Common request parameters>

Sample success responses

XML format 

HTTP/1.1 200 OK
Content-Type:application/xml

<AllocatePublicIpAddressResponse>
    <RequestId>F2EF6A3B-E345-46B9-931E-0EA094818567</RequestId>
    <IpAddress>112.124.**.**</IpAddress>
</AllocatePublicIpAddressResponse>

JSON format 

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "F2EF6A3B-E345-46B9-931E-0EA094818567",
  "IpAddress" : "112.124.**.**"
}

Error codes

HTTP status code Error code Error message Description
400 OperationDenied Specified operation is denied as your instance is in VPC. The error message returned because the operation is not supported while the instance resides in a VPC.
400 AllocateIpInvalidInstanceBandwidth OperationDenied The InternetMaxBandwidthOut of the specified instance cannot be less than 0. The error message returned because the operation is not supported while the maximum outbound public bandwidth is not greater than 0 Mbit/s.
403 IncorrectInstanceStatus The current status of the resource does not support this operation. The error message returned because the operation is not supported while the resource is in the current state.
403 InstanceLockedForSecurity The specified operation is denied as your instance is locked for security reasons. The error message returned because the operation is not supported while the instance is locked for security reasons.
403 InstanceExpiredOrInArrears The specified operation is denied as your prepay instance is expired (prepay mode) or in arrears (afterpay mode). The error message returned because the subscription instance has expired. Renew the instance and try again.
403 IpInUse The specified IP is already in use. The error message returned because the specified IP address is already in use.
403 AllocatedAlready There is an IpAddress allocated already for the specified instance. The error message returned because the instance is already assigned another IP address.
403 NAT_PUBLIC_IP_ALLOCATE_FAILED Nat public ip binding failed. The error message returned because the public IP address cannot be assigned.
404 InvalidInstanceId.NotFound The specified InstanceId does not exist. The error message returned because the specified InstanceId parameter is invalid.
404 InvalidVlanId.NotFound The VlanId provided does not exist in our records. The error message returned because the specified VlanId parameter does not exist.
404 InvalidIpAddress.NotFound The specified IP is not in the specified vlan. The error message returned because the specified IP address is not in the specified VLAN.

For a list of error codes, visit the API Error Center.