Java SDK

クイックスタート

Alibaba Cloud ソフトウェア開発キット (SDK) へようこそ。 Java 用 Alibaba Cloud SDK では、 Elastic Compute Service (ECS) 、Server Load Balancer (SLB) 、CloudMonitor などの Alibaba Cloud リソースを複雑なコーディングをすることなく、独自のクラウド Java アプリケーションを構築できます。 このチュートリアルでは、 Java 開発環境の設定に関するガイダンスを 段階的に示します。

前提条件

  • Alibaba Cloud アカウント、および対応する AccessKeyID と Secret が必要です。 AccessKey は Alibaba Cloud console で作成し取得するか、チケットを起票し、サポートセンターへお問い合わせください。
  • 製品の API を呼び出すために Alibaba Cloud Java SDK を使用するには、必要に応じて、まず Alibaba Cloud コンソールで製品を有効にする必要があります。
  • JDK 1.6 以降であることが必要です。

Java SDK のインストール

Apache Maven を使用して Java プロジェクトを管理する場合は、対応する依存関係をプロジェクトの pom.xml ファイルに追加するだけです。 Alibaba Cloud GitHubから異なるクラウド製品の Maven 依存関係をダウンロードできます。
どのクラウド製品を使用するかにかかわらず、コアライブラリをインストールする必要があります。 たとえば、 ECS リソースを使用する場合は、 ECS SDK ライブラリと SDK コアライブラリの両方をインストールする必要があります。
コアライブラリのバージョンが 3.7.0 で ECS ライブラリのバージョンが 4.11.0 の場合は、以下の通り pom.xml ファイルでこれら 2つ の SDK ライブラリを宣言する必要があります。

  1. <dependency>
  2. <groupId>com.aliyun</groupId>
  3. <artifactId>aliyun-java-sdk-core</artifactId>
  4. <version>3.7.0</version>
  5. </dependency>
  6. <dependency>
  7. <groupId>com.aliyun</groupId>
  8. <artifactId>aliyun-java-sdk-core</artifactId>
  9. <version>4.11.0</version>
  10. </dependency>

Java SDKの使用

次のコード例は、 Alibaba Cloud Java SDK を使用するための 3 つの主な手順を示しています。

  1. DefaultAcsClient インスタンスを作成して開始します。
  2. API リクエストを作成してパラメーターを設定します。
  3. リクエストを開始して応答を処理します。
    1. package com.testprogram;
    2. import com.aliyuncs.profile.DefaultProfile;
    3. import com.aliyuncs.DefaultAcsClient;
    4. import com.aliyuncs.IAcsClient;
    5. import com.aliyuncs.exceptions.ClientException;
    6. import com.aliyuncs.exceptions.ServerException;
    7. import com.aliyuncs.kms.model.v20160120。*;
    8. public class Main {
    9. public static void main(String[] args) {
    10. // Create and initialize a DefaultAcsClient instance
    11. DefaultProfile profile = DefaultProfile.getProfile(
    12. "<your-region-id>", // Region ID
    13. "<your-access-key-id>", // The AccessKey ID of the RAM account
    14. "<your-access-key-secret>"); // The AccessKey Secret of the RAM account
    15. IAcsClient client = new DefaultAcsClient(profile);
    16. // Initiate the request and handle the response or exceptions
    17. DescribeInstancesRequest request = new DescribeInstancesRequest();
    18. request.setPageSize(10);
    19. request.setConnectTimeout(5000); // Set the connection timeout to 5000 milliseconds
    20. request.setReadTimeout(5000); // Set the read timeout to 5000 milliseconds
    21. // Initiate the request and process the response
    22. DescribeInstancesResponse response;
    23. try {
    24. response = client.getAcsResponse(request);
    25. for (DescribeInstancesResponse.Instance instance:response.getInstances()) {
    26. System.out.println(instance.getPublicIpAddress());
    27. }
    28. } catch (ServerException e) {
    29. e.printStackTrace();
    30. } catch (ClientException e) {
    31. e.printStackTrace();
    32. }
    33. }
    34. }

Java SDK のインストール

Alibaba Cloud Java SDK は JDK 1.6 以降をサポートします。 Maven プロジェクトファイル pom.xml を直接修正して Alibaba Cloud Java SDK をインストールできます。

Maven の使用(推奨)

Maven を使用して Java プロジェクトを管理している場合は、 Alibaba Cloud SDK をインストールするために pom.xml に Maven の依存関係を追加できます。 クラウド製品の Maven 依存関係は Maven ライブラリで確認できます。
次のコードを実行して Alibaba Cloud SDK コアライブラリと ECS Java SDK をインストールします。

  1. <dependency>
  2. <groupId>com.aliyun</groupId>
  3. <artifactId>aliyun-java-sdk-core</artifactId>
  4. <version>3.7.1</version>
  5. </dependency>
  6. <dependency>
  7. <groupId>com.aliyun</groupId>
  8. <artifactId>aliyun-java-sdk-core</artifactId>
  9. <version>1.1.0</version>
  10. </dependency>

統合開発環境への JAR ファイルインポート

Eclipse または IntelliJ を使用している場合は、 JAR ファイルをインポートして直接 Java SDK をインストールできます。 クラウド製品の JAR ファイルは、 Alibaba Cloud SDK からダウンロードできます。

注:このインストール方法は段階的に廃止され、将来的には Maven を介したインストールのみサポートされる予定です。

  • Eclipse の使用
    Eclipse に Alibaba Cloud Java SDK をインストールするには、以下の手順に従ってください。
    1. ダウンロードした aliyun-java-sdk-xxx.jar ファイルをプロジェクトフォルダにコピーします。
    2. Eclipse でプロジェクトを開き、[プロパティー] を右クリックします。
    3. ダウンロードした JAR ファイルを追加するため、表示されたダイアログボックスで、 [Java Build Path] > [ライブラリ] > [JARs の追加] をクリックします。
    4. [適用して閉じる] をクリックします。
  • IntelliJ の使用
    IntelliJ を使用して Alibaba Cloud Java SDK をインストールするには、以下の手順に従ってください。
    1. ダウンロードした aliyun-java-sdk-xxx.jar ファイルをプロジェクトフォルダーにコピーします。
    2. IntelliJ でプロジェクトを開きます。 メニューバーで[ファイル] > [プロジェクト構造] をクリックします。
    3. [適用] 、 [OK] の順にクリックします。

SDK の使用

サービスの呼び出し

Java SDK を使用する前に、 Java SDK をインストールして認証情報を取得していることを確認してください。
このドキュメントでは、 Alibaba Cloud Java SDK を使用してリクエストを行う方法を、 ECS を例として説明します。

  1. AcsClient インスタンスの作成
    1. AcsClient client = new DefaultAcsClient(profile);
  2. リクエストの作成
    リクエストの命名規則は $ {apiName}Request です。 DescribeInstances のように、$ {apiName} となっている箇所が API 名です。
    複数の製品 SDK が使用されている場合、異なるリクエストが同じ名前を持つことがあります。 パッケージによってリクエストを区別します。
    1. DescribeInstancesRequest request = new DescribeInstancesRequest();
    2. request.setPageSize(10);
    3. request.setConnectTimeout(5000); // Set the connection timeout to 5000 milliseconds
    4. request.setReadTimeout(5000); // Set the read timeout to 5000 milliseconds
  3. 呼び出しと応答の処理
    1. DescribeInstancesResponse response;
    2. try {
    3. response = client.getAcsResponse(request);
    4. for (DescribeInstancesResponse.Instance instance:response.getInstances()) {
    5. System.out.println(instance.getPublicIpAddress());
    6. }
    7. } catch (ServerException e) {
    8. e.printStackTrace();
    9. } catch (ClientException e) {
    10. e.printStackTrace();
    11. }

    返された全てのフィールドは、応答へ逆シリアル化されます。 応答フィールドを取得するため、直接 response.getXXX() を呼び出すことができます。

    1. instanceStatus := response.getStatus()

    ただし、例外が発生した場合、または元の HTTP 応答を取得したい場合は、 doAction() メソッドを使用することができます。

    1. HttpResponse response = client.doAction(request);

コード例

リージョン内の ECS インスタンスをクエリを実行するため、以下のコードを実行します。

  1. package TEST.TEST;
  2. import com.aliyuncs.profile.DefaultProfile;
  3. import com.aliyuncs.DefaultAcsClient;
  4. import com.aliyuncs.IAcsClient;
  5. import com.aliyuncs.exceptions.ClientException;
  6. import com.aliyuncs.exceptions.ServerException;
  7. import com.aliyuncs.ecs.model.v20140526.*;
  8. public class ECS {
  9. public static void main(String[] args) {
  10. //Create a DefaultAcsClient instance and initialize it
  11. DefaultProfile profile = DefaultProfile.getProfile(
  12. "cn-hangzhou",// The region ID
  13. "LTAIiiarxj0AhJRX",//The AccessKey ID of the RAM account
  14. "kFTcJkI8fLpo1LDrtAKbZyHH0RrC4X"); // The Access Key Secret of the RAM account
  15. IAcsClient client = new DefaultAcsClient(profile);
  16. // Create the request and set parameters
  17. DescribeInstancesRequest request = new DescribeInstancesRequest();
  18. request.setPageSize(10);
  19. request.setConnectTimeout(5000); // Set the connection timeout to 5000 milliseconds
  20. request.setReadTimeout(5000); // Set the read timeout to 5000 milliseconds
  21. // Initiate the request and handle the response or exceptions
  22. DescribeInstancesResponse response;
  23. try {
  24. response = client.getAcsResponse(request);
  25. for (DescribeInstancesResponse.Instance instance:response.getInstances()) {
  26. System.out.println(instance.getPublicIpAddress());
  27. }
  28. } catch (ServerException e) {
  29. e.printStackTrace();
  30. } catch (ClientException e) {
  31. e.printStackTrace();
  32. }
  33. }
  34. }kTrace();
  35. }
  36. }
  37. }

CommonRequest の使用

Alibaba Cloud プロダクトが API 用の SDK を提供していない場合は、プロダクト API を呼び出すために汎用呼び出しメソッド( CommonRequest )を使用することができます。 CommonRequest 呼び出しメソッドを使用して、 任意の API を呼び出すことができます。

例: RPC API の呼び出し

次のコードは、 DescribeInstanceStatus API を呼び出すための CommonRequest 呼び出しメソッドの使用方法です。

  1. import com.aliyuncs.CommonRequest;
  2. import com.aliyuncs.CommonResponse;
  3. import com.aliyuncs.DefaultAcsClient;
  4. import com.aliyuncs.IAcsClient;
  5. import com.aliyuncs.exceptions.ClientException;
  6. import com.aliyuncs.exceptions.ServerException;
  7. import com.aliyuncs.profile.DefaultProfile;
  8. public class Sample {
  9. public static void main(String[] args) {
  10. //Create a DefaultAcsClient instance and initialize it.
  11. DefaultProfile profile = DefaultProfile.getProfile(
  12. "<your-region-id>", // your region ID
  13. "<your-access-key-id>", // AccessKey ID
  14. "<your-access-key-secret>"); // AccessKey Secret
  15. IAcsClient client = new DefaultAcsClient(profile);
  16. // Create an API request and set parameters
  17. CommonRequest request = new CommonRequest();
  18. request.setDomain("ecs.aliyuncs.com");
  19. request.setVersion("2014-05-26");
  20. request.setAction("DescribeInstanceStatus");
  21. request.putQueryParameter("PageNumber", "1");
  22. request.putQueryParameter("PageSize", "30");
  23. try {
  24. CommonResponse response = client.getCommonResponse(request);
  25. System.out.println(response.getData());
  26. } catch (ServerException e) {
  27. // TODO Auto-generated catch block
  28. e.printStackTrace();
  29. } catch (ClientException e) {
  30. // TODO Auto-generated catch block
  31. e.printStackTrace();
  32. }

例: RESTful API の呼び出し

次のコードは、CommonRequestを使用してすべてのクラスターインスタンスインターフェイスの Container Service ビューを呼び出す方法を示しています。

  1. import com.aliyuncs.CommonRequest;
  2. import com.aliyuncs.CommonResponse;
  3. mport com.aliyuncs.DefaultAcsClient;
  4. import com.aliyuncs.IAcsClient;
  5. import com.aliyuncs.exceptions.ClientException;
  6. import com.aliyuncs.exceptions.ServerException;
  7. import com.aliyuncs.profile.DefaultProfile;
  8. public class Sample {
  9. public static void main(String[] args) {
  10. //Create a DefaultAcsClient instance and initialize it.
  11. DefaultProfile profile = DefaultProfile.getProfile(
  12. "<Your-region-ID>", // your region ID
  13. "<Your-access-key-ID>", // your AccessKey ID
  14. "<Your-access-key-secret>"); // AccessKey Secret
  15. IAcsClient client = new DefaultAcsClient(profile);
  16. // Create an API request and set parameters
  17. CommonRequest request = new CommonRequest();
  18. request.setDomain("cs.aliyuncs.com");
  19. request.setVersion("2015-12-15");
  20. request.setUriPattern("/clusters");
  21. try {
  22. CommonResponse response = client.getCommonResponse(request);
  23. System.out.println(response.getData());
  24. } catch (ServerException e) {
  25. // TODO Auto-generated catch block
  26. e.printStackTrace();
  27. } catch (ClientException e) {
  28. // TODO Auto-generated catch block
  29. e.printStackTrace();

エンドポイントの管理

エンドポイントは Alibaba Cloud サービスのサービスエントリです。 サービスのエンドポイントはリージョンによって異なります。 たとえば、中国(杭州)リージョンの ECS インスタンスのエンドポイントは、 ecs-cn-hangzhou.aliyuncs.com ですが、 ECS インスタンスが日本(東京)リージョンにある場合、エンドポイントは ecs.ap-northeast-1.aliyuncs.com です。 Alibaba Cloud SDK にはエンドポイントアドレス指定モジュールが組み込まれています。 リクエストが送信されると、 Alibaba Cloud SDK はクライアントの作成時に指定されたリージョン ID とプロダクト ID に従って、使用するエンドポイントを見つけます。

例外処理

SDK.InvalidRegionID 、または SDK.EndpointResolvingError のようなエラーが発生した場合は、解決するために次の解決策をご参照ください。

エラーコード エラーメッセージ 解決策
SDK.InvalidRegionId Can not find endpoint to access. The current SDK version is too low. SDK コアライブラリ aliyun-java-sdk-core をバージョン 2.9.0 以降にアップグレードしてください。
SDK.EndpointResolvingError No such region <region-id>. Please check your region ID. リージョン ID をご確認下さい。 リージョン ID を見つけるために、 DescribeRegions API を呼び出すことができます。
SDK.EndpointResolvingError No endpoint for product <product-id>.
  • お持ちの SDK が旧バージョンです。 SDK コアライブラリ aliyun-java-sdk-core をバージョン 2.9.0 以降にアップグレードし、 aliyun-java-sdk-ecs などの SDK プロダクト を最新バージョンにアップグレードしてください。
  • 直接使用するようにエンドポイントを構成します。
SDK.EndpointResolvingError No endpoint in the region <region-id> for product <product-id>. 指定されたリージョンにプロダクトのエンドポイントが見つかりません。
  • 指定されたリージョンではプロダクトが利用できない場合があります。 状況に応じてリージョン ID を変更してください。
  • 最新のエンドポイントアドレス指定設定を使用するために、 SDK コアライブラリ aliyun-java-sdk-core を最新バージョンにアップグレードしてください。 サービスエンドポイントが変更されると、 SDK コアライブラリの新しいバージョンがリリースされます。
  • リクエストを送信するためにエンドポイントを直接設定します。

エンドポイントを直接設定する

以下のコードを参照して、使用するリクエストに対してエンドポイントを設定します。 利用可能なエンドポイントについては、各プロダクトのAPIドキュメントをご参照ください。

注:実際の状況( ecs-cn-hangzhou.aliyuncs.com )に応じて、コード例のエンドポイントを置き換えます。

  1. DescribeInstancesRequest request = new DescribeInstancesRequest();
  2. // Configure an endpoint for this request
  3. configuration.setEndpoint("ecs-cn-hangzhou.aliyuncs.com");
  4. DescribeInstancesResponse response = client.getAcsResponse(request);

エラー処理

サービス側または SDK 側でエラーが発生すると、 Alibaba Cloud Java SDK は対応する例外を返します。 これらの例外には、エラーコード (ErrCode) やエラーメッセージ (ErrMsg) を含む 詳細なエラー情報が含まれています。
Alibaba Cloud Java SDK から返された例外を処理する必要はありません。サービスから返されたエラーについてのみ、解決する必要があります。

  • ServerException は対応する Alibaba Cloud サービスによって返される例外です。
  • ClientException は Alibaba Cloud Java SDK によって返される例外です。

たとえば、次のエラーが発生した場合、エラーメッセージに従って、 AccessKey の ID を変更する必要があります。

  1. com.aliyuncs.exceptions.ClientException: InvalidAccessKeyId.NotFound : Specified access key is not found.

Alibaba Cloud Java SDK から返されたクライアントエラーを処理する場合は、次の例を参考にしてコードを記述してください。

  1. try {
  2. FooResponse response = client.getAcsResponse(request);
  3. // Handle the response
  4. }catch (ServerException e){
  5. // You can add your own error handling logic here
  6. // For example, print the error message
  7. System.out.println("ErrorCode=" + e.getErrCode());
  8. System.out.println("ErrorMessage=" + e.getErrMsg());
  9. // If the problem is tricky, you can open a ticket and provide the RequestId to us
  10. System.out.println("ResponseId=" + e.getRequestId());
  11. }catch (ClientException e){
  12. // You can add your own error handling logic here
  13. // For example, print the error message
  14. System.out.println("ErrorCode=" + e.getErrCode());
  15. System.out.println("ErrorMessage=" + e.getErrMsg());

エラーとトラブルシューティング

ここでは、Alibaba Cloud SDK 使用時に発生する可能性がある一般的なエラーを紹介します。 これらの一般的なエラーについて、考えられる原因と解決策を記載します。DingTalk グループ (11771185) から Alibaba Cloud へ、または GitHub Issue に問題を報告してください。

エラーコード エラー情報 原因 解決策
SDK.CanNotResolveEndpoint エンドポイントを解決できません。ユーザーガイドをご確認ください。 SDK は、指定されたリージョンで呼び出されたプロダクトのエンドポイントを自動的に取得することはできません。 提供されたリージョン ID とエンドポイントが正確かご確認ください。 以下のコードを実行して、エンドポイントを設定します。
  1. DefaultProfile.addEndpoint("cn-hangzhou", "cn-hangzhou", "Ecs", "ecs.aliyuncs.com");
SDK.JsonUnmarshalError マーシャリング解除レスポンスに失敗しました。 SDK レスポンスの逆シリアル化に失敗しました。 ほとんどの場合、 SDK が受け取るレスポンス構造が API メタデータに準拠していないためです。 フィールドがマッチしていない、またはフォーマットが正しくないことなどが考えられます。 オリジナル HTTP レスポンスを取得するために、client.doAction(request)メソッドを使用することが可能です。
SDK.TimeoutError リクエストが4回タイムアウトしました (再試行3回)。しきい値を少し上げてください。 リクエストはタイムアウトし、すべての再試行は失敗しました。
  • リージョンをまたいだ呼び出しやネットワーク低品質などの場合では、タイムアウトまたは最大再試行回数を増やすことを推奨します。

  • 問題が解決せず、ネットワーク品質が良好であることが確認されている場合は、チケットを起票し、サービスセンターへお問い合わせください。

SDK.ServerError:InvalidProtocol.NeedSsl リクエストは SSL 欠如のため拒否されました。protect.Recommend:https://error-center.aliyun.com/status/search?Keyword=InvalidProtocol.NeedSsl&source=PopGw API は HTTPS リクエストのみを受け入れ、 HTTP リクエストは受け入れません。 リクエストを送信する前に、次のコードを追加してください。
  1. request.setProtocol(ProtocolType.HTTPS)