Function

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

After assigning a yearly/monthly EIP by calling API successfully,

• If you need to pay for the order, see Paying for the Order of Yearly/Monthly-Billed Resources. If you want to use coupons to pay, set isAutoPay in the request to false.
• If you need to view the resource provisioning details in your order, see Querying Resource Provisioning Details in an Order.
• If you need to unsubscribe from a yearly/monthly resource, see Unsubscribing from Year/Monthly Resources.

URI

POST /v2.0/{project_id}/publicips

Request parameter

• Request parameter

  Table 2 Request parameter

  Name	Mandatory	Type	Description
  publicip	Yes	Object	Specifies the EIP object. For details, see Table 3.
  bandwidth	Yes	Object	Specifies the bandwidth objects. For details, see Table 4.
  extendParam	No	Object	Specifies the extended parameter, which is used to apply for resources in yearly/monthly billing mode. For details, see section Table 5.

  Table 3 Description of the publicip field

  Name	Mandatory	Type	Description
  type	Yes	String	Specifies the EIP type. Possible values are 5_telcom (China Telecom), 5_union (China Unicom), 5_bgp (dynamic BGP), and 5_sbgp (static BGP). CN Northeast-Dalian: 5_telcom and 5_union 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 AP-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.

  Table 4 Description of the bandwidth field

  Name	Mandatory	Type	Description
  name	No	String	Specifies the bandwidth name. The value is a string of 1 to 64 characters that can contain 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 whether the bandwidth is billed by traffic or by bandwidth size. The value can be bandwidth or traffic. The default value is bandwidth. If the value is traffic, the bandwidth is billed by traffic. A yearly/monthly EIP can only be billed by bandwidth.

  Table 5 Description of the extendParam field

  Name	Mandatory	Type	Description
  charge_mode	No	String	Specifies the billing mode (postpayment: pay-per-use; prepayment: yearly/monthly). 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 (yearly and monthly). 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 ranges from 1 to 3. 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 1

  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": "true"
      }
  }

• Example request 2

  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	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 parameter in the yearly/monthly scenario.) NOTE: If you need to pay for the order, see Paying for the Order of Yearly/Monthly-Billed Resources. If you need to view the resource provisioning details in your order, see Querying Resource Provisioning Details in an Order. If you need to unsubscribe from a yearly/monthly resource, see Unsubscribing from Year/Monthly Resources.
  publicip_id	String	Specifies the EIP ID. (This parameter is returned parameter 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) DOWN (Unbound) ACTIVE (Bound) ELB (Bound to a load balancer) ERROR (Exceptions)
  type	String	Specifies the EIP type. Possible values are 5_telcom (China Telecom), 5_union (China Unicom), 5_bgp (dynamic BGP), and 5_sbgp (static BGP). CN Northeast-Dalian: 5_telcom and 5_union 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 AP-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. Specifies the IPv4 address corresponding to the IPv6 address if IPv6 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 address
  tenant_id	String	Specifies the project ID.
  create_time	String	Specifies the time (UTC) when the EIP is assigned.
  bandwidth_size	Integer	Specifies the bandwidth size.
  enterprise_project_id	String	Specifies the enterprise project ID. The value can contain a maximum of 36 characters. It is string "0" or in UUID format with hyphens (-). When assigning an EIP, you need to associate an enterprise project ID with the EIP.

• Example response 1
  Yearly/monthly

  {
      "order_id": "CS1802081410IMDRN",
      "publicip_id": "4eaf3b63-48ca-4410-ab85-bdfddf4b35fd"
  }

• Example response 2
  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.