This topic describes how to use an SDK to call the Cloud Control API to manage resources. In this topic, the vSwitch in a Virtual Private Cloud (VPC) is used as an example and the sample code is written in Java. This tutorial walks you through the procedure to import SDK, query resource metadata, create, query, update, and delete resources, and query task status when asynchronous operation is enabled for Cloud Control API operation.
Prerequisites
RAM user:
Create an AccessKey pair for a RAM user. An Alibaba Cloud account has all permissions on resources. If the AccessKey pair of your Alibaba Cloud account is leaked, your resources are exposed to great risks. We recommend that you use the AccessKey pair of a RAM user. For more information, see Create an AccessKey pair.
Grant the required permissions on VPC resources to the RAM user that you want to use. This operation instruction involves a variety of operations on the vSwitch in a VPC. You must select AliyunVPCFullAccess as system policy. You can create a custom policy based on your business requirements. For more information, see Create a custom policy.
The AccessKey pair of a RAM user is configured in environment variables. For more information, see Configure environment variables in Linux, macOS, and Windows.
VPC
You must create a VPC to which the vSwitch is associated. For more information, see Create and manage a VPC.
Resource metadata
Resource management is implemented based on resource metadata. You must be familiar with Resource metadata.
Synchronous and asynchronous operations
Resource creation and deletion are not performed synchronously with Cloud Control API operations. For more information, see synchronous and asynchronous operations. If you want to query the task status when asynchronous operation is enabled for Cloud Control API, see Query task status.
Java
You must use Java 8 or later.
Initialize a project
Install CloudControlAPI SDK to obtain the AccessKey in the environment variable.
Import the SDK to your project. For more information, see Install CloudControlAPI SDK. You can use an SDK to integrate and use the Cloud Control API. In this example, an SDK is imported as follows:
<dependency> <groupId>com.aliyun</groupId> <artifactId>cloudcontrol20220830</artifactId> <version>1.1.1</version> </dependency>Create an ExampleDemo to implement resource management. Add the createClient method to the ExampleDemo to obtain the AccessKey pair in the environment variable and initialize the client. Sample code:
/** * Initialize the client. * @return Client */ public static Client createClient() throws Exception { // If the project code is leaked, the AccessKey pair may be leaked and the security of all resources in your account may be compromised. The following sample code is provided only for reference. Config config = new Config() // Required. Make sure that the ALIBABA_CLOUD_ACCESS_KEY_ID environment variable is configured. .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")) // Required. Make sure that the ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variable is configured. .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")); # For more information about endpoints, see https://api.aliyun.com/product/cloudcontrol. config.endpoint = "cloudcontrol.aliyuncs.com"; return new Client(config); }
Query the details of a resource type
You can query the details of a resource type based on product code and resource type code. The returned data is resource metadata. Subsequent resource management operations such as creation, query, listing, and deletion are implemented based on resource metadata.
You can call the GetResourceType operation to obtain the details of a resource type. In this example, the vSwitch in a VPC is used. The product code of the VPC is VPC, and the resource type code of the vSwitch is vSwitch. Sample code:
NoteFor more information about how to obtain the product code and resource code, see Where can I find the service code and resource type code?
/** * Query the details of a resource type. * @param productCode The product code, which is "VPC" in this example. * @param resourceTypeCode The resource type code, which is "vSwitch" in this example. * @param client The client * @return resourceTypeWithOptions The response */ public GetResourceTypeResponse getResourceType(String productCode, String resourceTypeCode, Client client) throws Exception { String requestPath = "/api/v1/providers/Aliyun/products/" + productCode + "/resourceTypes/" + resourceTypeCode; com.aliyun.cloudcontrol20220830.models.GetResourceTypeHeaders getResourceTypeHeaders = new com.aliyun.cloudcontrol20220830.models.GetResourceTypeHeaders() .setXAcsAcceptLanguage("zh_CH"); com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions(); // Write your own code to display the response of the API operation if necessary. GetResourceTypeResponse resourceTypeWithOptions = client.getResourceTypeWithOptions(requestPath, getResourceTypeHeaders, runtime); return resourceTypeWithOptions; }The resource metadata whose response body is vSwitch is returned. For more information about how to interpret the resource metadata, see GetResourceType - Query resource type. In this operation, the body of the response is:
Create resources
Create a vSwitch for subsequent operations such as update, query, and delete.
You can call the CreateResource operation and enter request parameters based on the resource metadata. Sample code:
/** * Create resources * @param regionId The region ID. * @param productCode The product code, which is "VPC" in this example. * @param resourceTypeCode The resource type code, which is "vSwitch" in this example. * @param client RAM user (client) * @return resourceWithOptions The response. */ public CreateResourceResponse createResource(String regionId, String productCode, String resourceTypeCode, Client client) throws Exception { String requestPath = "/api/v1/providers/Aliyun/products/" + productCode + "/resources/" + resourceTypeCode; // The response parameters Map body = new HashMap(); body.put("VpcId", "vpc-m5esjf3a6b380olet****"); // The ID of the VPC. body.put("CidrBlock", "172.16.24.0/24"); // The CIDR block of the vSwitch. body.put("ZoneId", "cn-qingdao-b"); // The ID of the zone. CreateResourceRequest createResourceRequest = new CreateResourceRequest() .setRegionId(regionId) .setBody(body); com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions(); Map<String, String> headers = new HashMap<>(); CreateResourceResponse resourceWithOptions = client.createResourceWithOptions(requestPath, createResourceRequest, headers, runtime); return resourceWithOptions; }If the call is successful, statusCode=202 is returned, which indicates that the task is an asynchronous operation. You need to further query the task status. For more information, see Query tasks. To query, update, and delete resources, you must record the resourceid. The response body is as follows:
List resources
You can call the GetResources operation to list all vSwitch resources. Sample code:
/** * List resources * @param regionId The region ID * @param productCode The product code, which is "VPC" in this example. * @param resourceTypeCode The resource type code, which is "vSwitch" in this example. * @param client RAM user (client) * @return resourceWithOptions The response. */ public GetResourcesResponse getResources(String regionId, String productCode, String resourceTypeCode, Client client) throws Exception { String requestPath = "/api/v1/providers/aliyun/products/" + productCode + "/resources/" + resourceTypeCode; GetResourcesRequest getResourcesRequest = new GetResourcesRequest() .setRegionId(regionId); com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions(); Map<String, String> headers = new HashMap<>(); GetResourcesResponse resourcesWithOptions = client.getResourcesWithOptions(requestPath, getResourcesRequest, headers, runtime); return resourcesWithOptions; }If the call is successful, the following response body is returned:
Updates resources
You can call the UpdateResource operation to update a specified resource. Sample code:
ImportantProceed with caution when you update a resource to prevent accidental operations from affecting other resources.
/** * Update resources * @param regionId The region ID * @param productCode The product code, which is "VPC" in this example. * @param productCode The product code, which is "vSwitch" in this example. * @param resourceId The ID of the resource. This parameter specifies the ID of the vSwitch that is created in this example. * @param client RAM user (client) * @return resourceWithOptions The response. */ public UpdateResourceResponse updateResource(String regionId, String productCode, String resourceTypeCode, String resourceId, Client client) throws Exception { String requestPath = "/api/v1/providers/Aliyun/products/" + productCode + "/resources/" + resourceTypeCode + "/" + resourceId; // The response parameters. Map body = new HashMap(); body.put("Description", "Test update"); UpdateResourceRequest updateResourceRequest = new UpdateResourceRequest() .setRegionId(regionId) .setBody(body); com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions(); Map<String, String> headers = new HashMap<>(); UpdateResourceResponse updateResourceResponse = client.updateResourceWithOptions(requestPath, updateResourceRequest, headers, runtime); return updateResourceResponse; }The response code statusCode=200 indicates that the request is successful. The following response body is returned: You can query the details of the resource to verify whether the resource is updated. For more information, see Query resources.
Query resources
You can call the GetResources operation to query a specified resource. Sample code:
/** * Query resources * @param regionId The region ID * @param productCode The product code, which is "VPC" in this example. * @param productCode The product code, which is "vSwitch" in this example. * @param resourceId The ID of the resource. This parameter specifies the ID of the vSwitch that is created in this example. * @param client RAM user (client) * @return resourceWithOptions The response. */ public GetResourcesResponse getResources(String regionId, String productCode, String resourceTypeCode, String resourceId, Client client) throws Exception { String requestPath = "/api/v1/providers/aliyun/products/" + productCode + "/resources/" + resourceTypeCode + "/" + resourceId; Map<String, String> body = new HashMap<>(); GetResourcesRequest getResourcesRequest = new GetResourcesRequest() .setRegionId(regionId); com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions(); Map<String, String> headers = new HashMap<>(); GetResourcesResponse resourcesWithOptions = client.getResourcesWithOptions(requestPath, getResourcesRequest, headers, runtime); return resourcesWithOptions; }If the request is successful, the following body is returned:
Delete resources
You can call the DeleteResource operation to delete a specified resource. Sample code:
ImportantProceed with caution when you delete a resource to prevent accidental operations from affecting other resources.
/** * Delete resources * @param regionId The region ID * @param productCode The product code, which is "VPC" in this example. * @param productCode The product code, which is "vSwitch" in this example. * @param resourceId The ID of the resource. This parameter specifies the ID of the vSwitch that is created in this example. * @param client RAM user (client) * @return deleteResourceResponse The response. */ public DeleteResourceResponse deleteResource(String regionId, String productCode, String resourceTypeCode, String resourceId, Client client) throws Exception { String requestPath = "/api/v1/providers/Aliyun/products/" + productCode + "/resources/" + resourceTypeCode + "/" + resourceId; DeleteResourceRequest deleteResourceRequest = new DeleteResourceRequest() .setRegionId(regionId); com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions(); Map<String, String> headers = new HashMap<>(); DeleteResourceResponse deleteResourceResponse = client.deleteResourceWithOptions(requestPath, deleteResourceRequest, headers, runtime); return deleteResourceResponse; }If the call is successful, statusCode=202 is returned, which indicates that the task is an asynchronous operation. You need to further query the task status. For more information, see Query task status.
Query task status
Queries the status of a specified task.
You can call the GetTask operation to query the status of a specified task. The call example is to query the task in which a vSwitch is being created:
/** * Query asynchronous task * @param taskId The ID of the task * @param client RAM user (client) * @return taskWithOptions The response. */ public GetTaskResponse getTask(String taskId, Client client) throws Exception { com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions(); Map<String, String> headers = new HashMap<>(); GetTaskResponse taskWithOptions = client.getTaskWithOptions(taskId, headers, runtime); return taskWithOptions; }If the request is successful, status="Succeeded" in the body is returned, indicating that the vSwitch is created.
Complete sample code
The complete ExampleDemo in this tutorial is as follows: