Help Center> Elastic IP > API Reference> APIs> EIP> Assigning an EIP (Yearly/Monthly)
Updated on 2024-01-12 GMT+08:00

Assigning an EIP (Yearly/Monthly)

Function

This API is used to assign a yearly/monthly EIP.

URI

POST /v2.0/{project_id}/publicips

Table 1 describes the parameters.
Table 1 Parameter description

Name

Mandatory

Description

project_id

Yes

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

Request parameter

  • Request parameter
    Table 2 Request parameter

    Name

    Mandatory

    Type

    Description

    publicip

    Yes

    publicip object

    Specifies the EIP object. For details, see Table 3.

    bandwidth

    Yes

    bandwidth object

    Specifies the bandwidth objects. For details, see Table 4.

    extendParam

    No

    extendParam object

    Specifies the extended parameter, which is used to apply for resources in yearly/monthly billing mode. For details, see section Table 5.

    enterprise_project_id

    No

    String

    • Specifies the enterprise project ID. The value is 0 or a string that contains a maximum of 36 characters in UUID format with hyphens (-).
    • When you assign an EIP, associate an enterprise project ID with the EIP.
    • If this parameter is not specified, the default value is 0, which indicates that the default enterprise project is used.
    NOTE:

    For more information about enterprise projects and how to obtain enterprise project IDs, see the Enterprise Management User Guide.

    Table 3 Description of the publicip field

    Name

    Mandatory

    Type

    Description

    type

    Yes

    String

    • Specifies the EIP type.
    • The value can be 5_bgp (dynamic BGP) or 5_sbgp (static BGP).
      • CN South-Guangzhou: 5_bgp and 5_sbgp
      • CN East-Shanghai1: 5_bgp and 5_sbgp
      • CN East-Shanghai2: 5_bgp and 5_sbgp
      • CN North-Beijing1: 5_bgp and 5_sbgp
      • CN-Hong Kong: 5_bgp
      • AP-Bangkok: 5_bgp
      • AP-Singapore: 5_bgp
      • AF-Johannesburg: 5_bgp
      • CN Southwest-Guiyang1: 5_sbgp
      • CN North-Beijing4: 5_bgp and 5_sbgp
      • LA-Santiago: 5_bgp
      • LA-Sao Paulo1: 5_bgp
      • LA-Mexico City1: 5_bgp
      • LA-Buenos Aires1: 5_bgp
      • LA-Lima1: 5_bgp
      • LA-Santiago2: 5_bgp
    • Constraints:
      • The configured value must be supported by the system.
      • publicip_id is an IPv4 port. If publicip_type is not specified, the default value is 5_bgp.

    ip_version

    No

    Integer

    • Specifies the EIP version.
    • The value can be 4 and 6, indicating IPv4 address and IPv6 address, respectively.
    • Constraints:
      • The configured value must be supported by the system.
      • If this parameter is left blank or is an empty string, IPv4 address is created by default.

    alias

    No

    String

    • Specifies the EIP name.
    • The value can contain 1 to 64 characters, including letters, digits, underscores (_), hyphens (-), and periods (.).

    port_id

    No

    String

    • Specifies the port ID.
    • The value must be an ID of an existing port. If the port does not exist or has been bound to an EIP, an error message is displayed.
    Table 4 Description of the bandwidth field

    Name

    Mandatory

    Type

    Description

    name

    No

    String

    • Specifies the bandwidth name.
    • The value can contain 1 to 64 characters, including letters, digits, underscores (_), hyphens (-), and periods (.).
    • Constraints:
      • This parameter is mandatory when share_type is set to PER.
      • This parameter will be ignored if the bandwidth has a specified ID.

    size

    No

    Integer

    • Specifies the bandwidth size.
    • The value ranges from 1 Mbit/s to 2000 Mbit/s by default. (The specific range may vary depending on the configuration in each region. You can see the available bandwidth range on the management console.)
    • This parameter is mandatory when share_type is set to PER. This parameter will be ignored if the bandwidth has a specified ID.
    • The minimum increment for bandwidth adjustment varies depending on the bandwidth range. The details are as follows:
      • The minimum increment is 1 Mbit/s if the allowed bandwidth ranges from 0 Mbit/s to 300 Mbit/s (with 300 Mbit/s included).
      • The minimum increment is 50 Mbit/s if the allowed bandwidth ranges from 300 Mbit/s to 1000 Mbit/s (with 1000 Mbit/s included).
      • The minimum increment is 500 Mbit/s if the allowed bandwidth is greater than 1000 Mbit/s.

    id

    No

    String

    • Use the existing shared bandwidth to assign an IP address.
    • Specifies the ID of the shared bandwidth.
    • Constraints:
      • The value must be the ID of bandwidth whose share_type is WHOLE.
      • This parameter does not need to be specified in prepayment mode. This parameter will be ignored if its value is left blank.

    share_type

    Yes

    String

    • Specifies the bandwidth type.
    • Possible values are as follows:
      • PER: Dedicated bandwidth
      • WHOLE: Shared bandwidth
    • When the existing bandwidth is used to assign an IP address, the value of this parameter depends on the bandwidth type.
    • The parameter value can only be PER in prepayment mode.

    charge_mode

    No

    String

    • Specifies the billing mode. The yearly/monthly billing mode supports only the bandwidth-based billing.
    • The value can be bandwidth.
    Table 5 Description of the extendParam field

    Name

    Mandatory

    Type

    Description

    charge_mode

    No

    String

    • Specifies the billing mode.
    • Possible values are as follows:
      • prePaid: prepayment. The billing mode is yearly/monthly.
      • postPaid: postpayment. The billing mode is pay per use.
      • The default value is postPaid.
    • In the postpayment mode, parameters in extendParam will be ignored.

    period_type

    No

    String

    • Specifies the subscription unit.
    • Possible values are as follows:
      • month: indicates that resources are subscribed by month.
      • year: indicates that resources are subscribed by year.
    • Constraints:

      If you assign an EIP that uses an existing yearly/monthly shared bandwidth (that is, you specify the shared bandwidth ID to assign an EIP), this parameter is optional. This parameter is mandatory when the billing mode is prepayment and the EIP does not use a shared bandwidth.

    When an EIP is created using the shared bandwidth, the expiration time of the bandwidth is the same as that of the EIP.

    period_num

    No

    Integer

    • Specifies the subscription period.
    • The value range varies depending on the operation strategy.
      • When period_type is set to month, the parameter value ranges from 1 to 9.
      • When period_type is set to year, the parameter value must be set to 1.
    • The constraints for period_num are the same as those for period_type.

    is_auto_renew

    No

    boolean

    • Specifies whether to renew the subscription.
    • Possible values are as follows:

      The value false indicates that the automatic subscription renewal is enabled. The value true indicates that the automatic subscription renewal is disabled. The default value is false.

    • Constraints:

      After the subscription is expired, the system automatically renews the subscription for one month by default (the automatic renewal period may change). For details, contact the customer service personnel.

    is_auto_pay

    No

    boolean

    • Specifies whether the fee is automatically deducted from the customer's account balance after an order is submitted. The non-automatic payment mode is used by default.
    • Possible values are as follows:
      • true: indicates automatic payment. The system will automatically deduct fees from the account balance after an order is submitted.
      • false: indicates non-automatic payment. This is the default value. Customers need to pay manually.
    • Constraints:

      If you use the automatic payment mode, only your account balance can be used. If you want to use a voucher, do not use the automatic payment mode, and select the voucher for the payment in the Billing Center.

Example Request

Assign an EIP that uses a new yearly/monthly dedicated bandwidth. The bandwidth size is 1 Mbit/s and the required duration is 1 month. The system does not automatically renew the subscription and deduct the fee after an order is submitted.

POST https://{Endpoint}/v2.0/{project_id}/publicips

{
    "publicip": {
        "type": "5_bgp"
    },
    "bandwidth": {
        "name": "bw_666",
        "size": 1,
        "share_type": "PER",
        "charge_mode": "bandwidth"
    },
    "extendParam": {
        "charge_mode": "prePaid",
        "period_type": "month",
        "period_num": 1,
        "is_auto_renew": "false",
        "is_auto_pay": "false"
    }
}

Assign an EIP that uses a pay-per-use bandwidth. Leave the parameter extendParam blank.

POST https://{Endpoint}/v2.0/{project_id}/publicips

{
    "publicip": {
        "type": "5_bgp"
    },
    "bandwidth": {
        "name": "bw_666",
        "size": 1,
        "share_type": "PER",
        "charge_mode": "bandwidth"
    }
}

Response Message

  • Response parameter

    Name

    Type

    Description

    publicip

    publicip object

    Specifies the EIP object. (This parameter is returned in the pay-per-use scenario.)

    order_id

    String

    Specifies the order ID. (This parameter is returned in the yearly/monthly scenario.)

    publicip_id

    String

    Specifies the EIP ID. This parameter takes effect 1 minute later in the yearly/monthly scenario.

    Table 6 Description of the publicip field

    Name

    Type

    Description

    id

    String

    Specifies the unique identifier of an EIP.

    status

    String

    • Specifies the EIP status.
    • Possible values are as follows:
      • FREEZED (Frozen)
      • BIND_ERROR (Binding failed)
      • BINDING (Binding)
      • PENDING_DELETE (Releasing)
      • PENDING_CREATE (Assigning)
      • PENDING_UPDATE (Updating)
      • NOTIFYING (Assigning)
      • NOTIFY_DELETE (Releasing)
      • DOWN (Unbound)
      • ACTIVE (Bound)
      • ELB (Bound to a load balancer)
      • ERROR (Exceptions)

    type

    String

    • Specifies the EIP type.
    • The value can be 5_bgp (dynamic BGP) or 5_sbgp (static BGP).
      • CN South-Guangzhou: 5_bgp and 5_sbgp
      • CN East-Shanghai1: 5_bgp and 5_sbgp
      • CN East-Shanghai2: 5_bgp and 5_sbgp
      • CN North-Beijing1: 5_bgp and 5_sbgp
      • CN-Hong Kong: 5_bgp
      • AP-Bangkok: 5_bgp
      • AP-Singapore: 5_bgp
      • AF-Johannesburg: 5_bgp
      • CN Southwest-Guiyang1: 5_sbgp
      • CN North-Beijing4: 5_bgp and 5_sbgp
      • LA-Santiago: 5_bgp
      • LA-Sao Paulo1: 5_bgp
      • LA-Mexico City1: 5_bgp
      • LA-Buenos Aires1: 5_bgp
      • LA-Lima1: 5_bgp
      • LA-Santiago2: 5_bgp
    • Constraints:
      • The configured value must be supported by the system.
      • publicip_id is an IPv4 port. If publicip_type is not specified, the default value is 5_bgp.

    public_ip_address

    String

    Specifies the obtained EIP if only IPv4 EIPs are available.

    public_ipv6_address

    String

    Specifies the obtained EIP if IPv6 EIPs are available. This parameter does not exist if only IPv4 EIPs are available.

    ip_version

    Integer

    Specifies the IP address version. The value can be 4 or 6.

    • 4: IPv4 address
    • 6: IPv6

    tenant_id

    String

    Specifies the project ID.

    create_time

    String

    Specifies the time (UTC) when the EIP is assigned.

    Format: yyyy-MM-ddTHH:mm:ss

    bandwidth_size

    Integer

    Specifies the bandwidth size.

    alias

    String

    Specifies the EIP name.

    enterprise_project_id

    String

    • Specifies the enterprise project ID. The value is 0 or a string that contains a maximum of 36 characters in UUID format with hyphens (-).
    • When assigning an EIP, you need to associate an enterprise project ID with the EIP.
    • If this parameter is not specified, the default value is 0, which indicates that the default enterprise project is used.
    NOTE:

    For more information about enterprise projects and how to obtain enterprise project IDs, see the Enterprise Management User Guide.

Example Response

Yearly/monthly
{
    "order_id": "CS1802081410IMDRN",
    "publicip_id": "4eaf3b63-48ca-4410-ab85-bdfddf4b35fd"
}
Pay-per-use
{
  "publicip": {
    "id": "4eaf3b63-48ca-4410-ab85-bdfddf4b35fd",
    "status": "PENDING_CREATE",
    "type": "5_bgp",
    "public_ip_address": "10.xx.xx.238",
    "tenant_id": "26ae5181a416420998eb2093aaed84d9",
    "create_time": "2019-03-27 13:11:58",
    "bandwidth_size": 0,
    "enterprise_project_id": "0",
    "ip_version": 4
  }
}

Status Code

See Status Codes.

Error Code

See Error Codes.