Common Scenarios of Using APIs

Scenarios

This section describes common scenarios of using APIs.

Purchasing ECSs Billed in Yearly/Monthly Mode

You can refer to Creating ECSs to purchase yearly/monthly ECSs. Different from calling the API for creating pay-per-use ECSs, you only need to set extendparam.chargingMode to prePaid and set the purchase period in the request body. For details about extendparam, see extendparam Field Description for Creating ECSs.

The following is an example to show how to purchase a yearly/monthly ECS in the ap-southeast-1 region with the usage duration for one month, and automatic payment and auto-renewal enabled.

{
    "server": {
        "name": "newserver",
        "availability_zone": "ap-southeast-1a",
        "flavorRef": "s3.small.1",
        "imageRef": "8da46d6d-6079-4e31-ad6d-a7167efff892",
        "root_volume": {
            "volumetype": "SATA"
        },
        "vpcid": "7e1a7e70-3f3e-4581-955e-26a4848d8f31",
        "nics": [
	        {
		 "subnet_id": "04548cde-4067-48b0-9323-5c7b67ac13fc"
	        }	
        ],
        "data_volumes": [
	   {
                "volumetype": "SSD", 
                "size": 50
            }
        ],
        "publicip": {
            "id": "publicip_123", 
            "eip": {
                "iptype": "5_bgp",
                "bandwidth": {
                    "size": 10, 
                    "sharetype": "PER"
                }
            }
        },
        "extendparam": {
            "chargingMode": "prePaid",
            "periodType": "month",
            "periodNum": 1,
            "isAutoRenew": "true",
            "isAutoPay": "true",
            "regionID": "ap-southeast-1"
        }
    }
}

After a yearly/monthly ECS is created, an order ID order_id is returned.

{
    "job_id": "ff808082739334d80173943ec9b42130",
    "order_id": "CS2007281506xxxxx",
    "serverIds": [
        "fe0528f0-5b1c-4c8c-9adf-e5d5047b8c17"
    ] 
}

In the preceding request body, the value of extendparam.isAutoPay is true, indicating automatic payment is enabled. If this parameter is left blank or set to false, you need to manually pay for the order (you can use coupons if any) by referring to Paying Yearly-Monthly Product Orders.

POST https://bss.myhuaweicloud.com/v2/orders/customer-orders/pay

{
    "order_id": "CS20052715001E4CR"
}

Unsubscribing from Yearly/Monthly ECSs

To unsubscribe from yearly/monthly ECSs, refer to Unsubscribing from Yearly/Monthly Resources.

POST https://bss.myhuaweicloud.com/v2/orders/subscriptions/resources/unsubscribe

{
  "resource_ids": [
    "21e09f37c5c9420c8746ad5c71fb3aab"
  ],
  "unsubscribe_type": 1
}

The resource_ids indicates the returned serverIds when yearly/monthly ECSs are being purchased.

Querying Available Public Images

Query images using search criteria by referring to Querying Images. You can type a question mark (?) and an ampersand (&) at the end of the URI to define multiple search criteria.

The following is an example to show how to query the public image list.

GET /v2/cloudimages?__imagetype=gold&visibility=public&protected=true

When calling the IMS API, you need to replace the endpoint information of the IMS service.

When querying the image list, use pagination query to return all images. You can specify marker and limit to query images by page.

marker indicates the image from which the query starts and the value is the image ID. limit specifies the number of images to be queried. The value is an integer and is 500 by default.

GET /v2/cloudimages?__imagetype=gold&visibility=public&protected=true&marker=af92bb51-ec9d-4b02-912f-da0b3f0f7635&limit=5

To query other types of images:

• Public images

  GET /v2/cloudimages?__imagetype=gold&visibility=public&protected=true

• Private images

  GET /v2/cloudimages?owner={project_id}

• Available shared images

  GET /v2/cloudimages?member_status=accepted&visibility=shared&__imagetype=shared

• Rejected shared images

  GET /v2/cloudimages?member_status=rejected&visibility=shared&__imagetype=shared

• Unaccepted shared images

  GET /v2/cloudimages?member_status=pending&visibility=shared&__imagetype=shared

• Public images supported by a BMS flavor

  GET /v2/cloudimages?__imagetype=gold&__support_xxx=true&virtual_env_type=Ironic

If the image type is not specified, you can determine the image type from the __imagetype field in the response.

Renewing Yearly/Monthly ECSs

If your yearly/monthly ECSs are about to expire, you can renew them by referring to Renewing Subscription to Yearly/Monthly Resources.

The following is an example to show how to renew a yearly/monthly ECS for a month, set the billing mode to pay-per-use after the renewal period expires, and enable the automatic payment.

POST https://bss.myhuaweicloud.com/v2/orders/subscriptions/resources/renew

{
    "resource_ids": [
        "96308d5efd7841b9a4dac673d84d0e14"
    ],
    "period_type": 2,
    "period_num": 1,
    "expire_policy": 1,
    "is_auto_pay": 1
}

After the renewal is successful, an order ID is returned.

{
  "order_ids": [
    "CS190401192xxxxxx"
  ]
}

In the preceding request body, the value of isAutoPay is 1, indicating automatic payment is enabled. If this parameter is left blank or set to 0, you need to manually pay for the order (you can use coupons if any) by referring to Paying Yearly-Monthly Product Orders. The following is an example payment using a coupon.

POST https://bss.myhuaweicloud.com/v2/orders/customer-orders/pay

{
    "coupon_infos": [
        {
            "id": "CP2005270256xxxxxx",
            "type": 301
        }
    ],
    "order_id": "CS190401192xxxxxx"
}

Querying Whether Flavors Can Be Purchased or Sold Out

You can check whether specific ECS flavors are sufficient in an AZ by referring to Querying Details About Flavors and Extended Flavor Information, and check the cond:operation:status and cond:operation:az values in the response to determine the AZ and flavor availability.

The following is an example to show how to query flavors in AZ1 of the CN-Hong Kong region.

GET https://ecs.ap-southeast-1.myhuaweicloud.com/v1/05041fea8a8025662f4ac00927982f3e/cloudservers/flavors?availability_zone=ap-southeast-1a

Response message

{
    "id": "c3.3xlarge.2", 
    "name": "c3.3xlarge.2", 
     ...
    "os_extra_specs": {
        "cond:spot_block:operation:az": "ap-southeast-1a(sellout),ap-southeast-1b(normal),ap-southeast-1c(normal)",
        "cond:operation:az": "ap-southeast-1a(normal),ap-southeast-1b(sellout)"
        ...
        "cond:operation:status": "abandon", 
        "cond:spot_block:operation:interrupt_policy":  "ap-southeast-1a(immediate),ap-southeast-1b(immediate),ap-southeast-1c(immediate)", 
        "resource_type": "IOoptimizedC3_2"
    }
}

In the response, view cond:operation:status and cond:operation:az to check whether flavors are available.

View cond:operation:az first. If an AZ is not configured in cond:operation:az, the cond:operation:status value is used by default.

In the CN-Hong Kong region in this example, c3.3xlarge.2 has been commercially used in AZ 1 and has been sold out in AZ 2. cond:operation:az has not been configured in AZ3 and therefore the cond:operation:status value is used, that is, c3.3xlarge.2 has been brought offline in AZ3.

Payment Method

When you are creating a yearly/monthly ECS (chargingMode is prePaid), you can choose the payment mode by setting the extendparam.isAutoPay parameter.

If this parameter is set to true, the order is automatically paid after being created.

If this parameter is set to false, you need to manually pay for the order (you can use coupons if any).

You can pay for the order by referring to Paying Yearly-Monthly Product Orders. The following is an example payment using a coupon.

POST https://bss.myhuaweicloud.com/v2/orders/customer-orders/pay

{
    "coupon_infos": [
        {
            "id": "CP2005270256xxxxxx",
            "type": 301
        }
    ],
    "order_id": "CS190401192xxxxxx"
}

Querying Available Quotas of Resources

You can query the resource quotas, including the used quotas, of the current account by referring to Querying Tenant Quotas.

GET https://ecs.cn-east-2.myhuaweicloud.com/v1/05041fea8a8025662f4ac00927982f3e/cloudservers/limits

In the following response message,.the maxTotalInstances value is the maximum number of ECSs that can be created, and the totalInstancesUsed value is the number of ECSs that are being used.

{
	-"absolute": {
		"maxServerMeta": 128,
		"maxPersonality": 5,
		"maxImageMeta": 128,
		"maxPersonalitySize": 10240,
		"maxSecurityGroupRules": 20,
		"maxTotalKeypairs": 1000,
		"totalRAMUsed": 22528,
		"totalInstancesUsed": 4,
		"maxSecurityGroups": 10,
		"totalFloatingIpsUsed": 0,
		"maxTotalCores": 8000,
		"totalSecurityGroupsUsed": 1,
		"maxTotalFloatingIps": 10,
		"maxTotalInstances": 1000,
		"totalCoresUsed": 11,
		"maxTotalRAMSize": 16384000,
		"maxServerGroups": 32,
		"maxServerGroupMembers": 16,
		"totalServerGroupsUsed": 0,
		"maxTotalSpotInstances": 20,
		"maxTotalSpotCores": 320,
		"maxTotalSpotRAMSize": 655360,
		"totalSpotInstancesUsed": 0,
		"totalSpotCoresUsed": 0,
		"totalSpotRAMUsed": 0,
		"maxFaultDomainMembers": 200,
		"limit_by_flavor": []
	}
}

Querying Resource Prices

You can call APIs by referring to Querying the Price of a Pay-Per-Use Product and Querying the Price of a Yearly/Monthly Product and set the cloud service type, resource type, resource specifications, and cloud service region to query product prices.

The following is an example to show how to query the monthly price of general computing ECS running the Linux OS and using the s6.small.1 flavor in the AZ of the CN-Hong Kong region.

POST https://bss.myhuaweicloud.com/v2/bills/ratings/period-resources/subscribe-rate

{
	"product_infos": [

		{
			   "id": "1",
			"cloud_service_type": "hws.service.type.ec2",
			"resource_type": "hws.resource.type.vm",
			"resource_spec": "s6.small.1.linux",
			"region": "ap-southeast-1",
			"available_zone": "ap-southeast-1a",
			"period_type": 2,
			"period_num": 1,
			"subscription_num": 1
		}
	],
	"project_id": "05041fea8a8025662f4ac00927982f3e"
}

In the following response message, the official_website_amount value is the price of the yearly/monthly ECS.

{
	-"official_website_rating_result": {
		"official_website_amount": 11.38,
		"measure_id": 1,
		-"product_rating_results": [-{
			"id": "1",
			"product_id": "00301-233164-0--0",
			"official_website_amount": 11.38,
			"measure_id": 1
		}]
	},
	"optional_discount_rating_results": [],
	"currency": USD"
}