Integrate the dependencies of SDK V1.0 for Java of Alibaba Cloud services - Alibaba Cloud SDK

To facilitate API calls, we recommend that you integrate with Alibaba Cloud SDK in your project. SDKs simplify the development process, quickly integrate features, and greatly reduce the O&M cost. This topic describes how to integrate Alibaba Cloud SDK V1.0 for Java in your project and use the SDK for development.

Prerequisites

JDK 1.6 or later is installed.

Install the SDK

To use Alibaba Cloud SDK V1.0 for Java, you must also install the SDK of the cloud service and the core library of the SDK.

Cloud service SDK

The SDK of a cloud service includes the request object that is required for calling API operations and the response object. In this example, Elastic Compute Service (ECS) SDK V1.0 for Java is configured as a Maven dependency. The following sample code shows the Maven dependency.

<dependencies>
  <!--  ecs V1.0 SDK  -->
  <dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-ecs</artifactId>
    <version>5.11.7</version>
  </dependency>
</dependencies>

The SDK V1.0 for Java of an Alibaba Cloud service is named in the aliyun-java-sdk-${Service code} format. You can also view the information about the SDK V1.0 for Java of a specific Alibaba Cloud Service in the SDK Center.

Core library of an SDK

The core library of an SDK includes the client object, the signature logic, and the error handling logic, which are required information for calling API operations. We recommend that you configure the core library of the SDK as a Maven dependency. The following sample code shows the Maven dependency.

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <version>4.7.3</version>
</dependency>

For more information about the core library version, see Maven Repository: com.aliyun » aliyun-java-sdk-core.

Use the SDK

The following example shows how to use Alibaba Cloud SDK V1.0 to call the DescribeInstances API operation of ECS.

1. Initialize a request client

All API operations are called by using the Client object provided by the core library. Before you call an API operation, you must initialize a request client. In this example, the request client is initialized by using an AccessKey pair. For more information, see Manage access credentials.

Note

In this example, the AccessKey pair is obtained from the ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables, which must be configured before you run the code. For more information, see Configure environment variables in Linux, macOS, and Windows.

com.aliyuncs.profile.DefaultProfile profile = com.aliyuncs.profile.DefaultProfile.getProfile(
        "<REGION_ID>",
        // Obtain the AccessKey ID of the Resource Access Management (RAM) user from an environment variable.
        System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
        // Obtain the AccessKey secret of the RAM user from an environment variable.
        System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
com.aliyuncs.IAcsClient client = new com.aliyuncs.DefaultAcsClient(profile);

Note

If one SDK client processes multiple threads, security issues may occur. If multiple Alibaba Cloud services share the same profile information, unauthorized access may occur. We recommend that you use Alibaba Cloud SDK V2.0 for development.

2. Create a request object

You can use the request object provided by the SDK to encapsulate the request parameters.

Note

Name the request object of the API operation in the following format: <API operation name>Request.

com.aliyuncs.ecs.model.v20140526.DescribeInstancesRequest request = new com.aliyuncs.ecs.model.v20140526.DescribeInstancesRequest();
request.setRegionId("cn-hangzhou");
request.setInstanceIds(new com.google.gson.Gson().toJson(Arrays.asList("i-bp1fq61ktxxxxxxxxxxxx","i-bp1fq62ktxxxxxxxxxxxx")));

3. Initiate an API request

Use the request client built in Step 1 to call the getAcsResponse operation. The request parameters of the operation are the request object created in Step 2. If the call is successful, a response object is returned.

Note

Name the response object of the API operation in the following format: <API operation name>Response.

com.aliyuncs.ecs.model.v20140526.DescribeInstancesResponse response = client.getAcsResponse(request);
System.out.println(new com.google.gson.Gson().toJson(response));

4. Handle errors

If an error is triggered when you can an API operation, you can capture ServerException and ClientException to obtain the error message. In most cases, ClientException errors are caused by invalid parameters during client initialization, such as invalid AccessKey parameters. ServerException errors may be caused by several factors. You can request customer service for troubleshooting and provide the request ID.

Complete sample code

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.ecs.model.v20140526.DescribeInstancesRequest;
import com.aliyuncs.ecs.model.v20140526.DescribeInstancesResponse;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.profile.DefaultProfile;
import com.google.gson.Gson;

import java.util.Arrays;

public class Sample {
    public static void main(String[] args) {
        try {
            DefaultProfile profile = DefaultProfile.getProfile(
                    "<REGION_ID>",
                    // Obtain the AccessKey ID of the RAM user from an environment variable.
                    System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                    // Obtain the AccessKey secret of the RAM user from an environment variable.
                    System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
            IAcsClient client = new DefaultAcsClient(profile);
            DescribeInstancesRequest request = new DescribeInstancesRequest();
            request.setRegionId("cn-hangzhou");
            request.setInstanceIds(new Gson().toJson(Arrays.asList("i-bp1fq61ktxxxxxxxxxxxx", "i-bp1fq62ktxxxxxxxxxxxx")));
            DescribeInstancesResponse response = client.getAcsResponse(request);
            System.out.println(new Gson().toJson(response));
        } catch (ServerException e) {
            // In this example, error information is displayed when an exception occurs. In actual business scenarios, handle exceptions with caution and never ignore exceptions in your project. 
            System.out.println("ServerException:" + e.getErrMsg());
        } catch (ClientException e) {
            // In this example, error information is displayed when an exception occurs. In actual business scenarios, handle exceptions with caution and never ignore exceptions in your project. 
            System.out.println("ClientException:" + e.getErrMsg());
        }
    }
}

References

For more information about SDK settings, such as proxy settings and timeout settings, see Advanced settings.
For more information about how to create an AccessKey pair, see Create an AccessKey pair.