ジェネリック呼び出し - Alibaba Cloud SDK - Alibaba Cloud ドキュメントセンター

Alibaba Cloud SDK for Java V2.0 は、汎用 API 呼び出しをサポートしています。このトピックでは、Alibaba Cloud SDK for Java V2.0 を使用して汎用呼び出しを行う方法について説明します。

特徴

軽量：Alibaba Cloud SDK for Java V2.0 のコアライブラリのみをインストールする必要があります。特定のクラウドサービスの SDK をインストールする必要はありません。

使いやすさ：共通のリクエストパラメータを作成し、共通のクライアントを使用してリクエストを開始するだけで済みます。レスポンスは共通のフォーマットで返されます。

詳細については、「汎用呼び出しと専用呼び出し」をご参照ください。

使用上の注意

汎用呼び出しを行う前に、API 操作のメタデータを表示して、API スタイル、リクエストパラメータ、および URL を取得することをお勧めします。詳細については、「API メタデータ」をご参照ください。

Alibaba Cloud SDK for Java V2.0 コアライブラリのインストール

pom.xml ファイルに次の依存関係を追加して、SDK for Java V2.0 のコアライブラリをインストールします。最新バージョンについては、「Maven Repository」をご参照ください。

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>tea-openapi</artifactId>
    <version>0.3.10</version>
</dependency>

API 操作の呼び出し

リクエストクライアントの初期化

com.aliyun.teaopenapi.Client オブジェクトを作成してリクエストクライアントを初期化し、クライアントを使用して API 操作を呼び出します。クライアントを初期化するときに、Credentials ツールを使用することもできます。 Credentials ツールの詳細については、「アクセス認証情報の管理」をご参照ください。

説明

クライアントオブジェクトを手動で破棄する必要はありません。ガベージコレクションメカニズムによって自動的にリサイクルされます。

        // 1. リクエストクライアントを初期化する
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        config.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // ASAPI のエンドポイントを指定します。
        config.setEndpoint("ecs.cn-hangzhou.aliyuncs.com");
        // オプション。クライアントの初期化時に Config オブジェクトを使用してプロキシを構成します。
        // クライアントの初期化時に、プロトコルとして HTTPS を指定します。
        // config.setProtocol("HTTPS");
        // リージョン ID を指定します。
        // config.setRegionId("<regionId>");
        // クライアントの初期化時にプロキシを構成します。
        // config.setHttpProxy("http://127.0.0.1:9898");
        // config.setHttpsProxy("http://user:password@127.0.0.1:8989");
        // config.setNoProxy("127.0.0.1,localhost");
        // SDK クライアントの初期化時にタイムアウト期間を構成します。
        // 接続リクエストのデフォルトのタイムアウト期間は 5,000 ミリ秒です。値は、式 5 × 1,000 = 5,000 を使用して計算されます。
        // config.setConnectTimeout(5000);
        // 読み取りリクエストのデフォルトのタイムアウト期間は 10,000 ミリ秒です。
        // config.setReadTimeout(10000);
        com.aliyun.teaopenapi.Client client = new com.aliyun.teaopenapi.Client(config);

//        //  Credentials ツールを使用する
//        com.aliyun.credentials.models.Config credentialConfig = new com.aliyun.credentials.models.Config();
//        credentialConfig.setType("access_key");
//        credentialConfig.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
//        credentialConfig.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
//        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
//        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
//                .setCredential(credentialClient)
//                .setEndpoint("ecs.cn-hangzhou.aliyuncs.com");
//        com.aliyun.teaopenapi.Client client = new com.aliyun.teaopenapi.Client(config);

API 操作に関する情報の構成

com.aliyun.teaopenapi.models.Params クラスを使用して、呼び出す API 操作の基本情報 (API スタイル、API バージョン、リクエストメソッドなど) を構成します。次の例では、DescribeInstanceTypeFamilies 操作が呼び出されます。

        com.aliyun.teaopenapi.models.Params params = new com.aliyun.teaopenapi.models.Params()
                .setStyle("RPC")  // API スタイル (リモートプロシージャコール (RPC) やリソース指向アーキテクチャ (ROA) など)。
                .setVersion("2014-05-26") // API バージョン。
                .setMethod("POST") // リクエストメソッド。
                .setAction("DescribeInstanceTypeFamilies")  // API 操作の名前。
                .setPathname("/") // 操作の URL。RPC スタイルの操作のデフォルトパスは / です。ROA スタイルの操作の URL は、API メタデータの data.path パラメータから取得できます。
                .setProtocol("HTTPS") // リクエストプロトコル (HTTPS または HTTP)。HTTPS を使用することをお勧めします。
                .setAuthType("AK") // 認証タイプ。デフォルトタイプを使用します。操作が匿名リクエストをサポートしている場合は、Anonymous パラメータを指定して匿名リクエストを開始できます。
                .setReqBodyType("json") // リクエスト本文のタイプ。有効な値：byte、json、formData。
                .setBodyType("json"); // レスポンスフォーマット。JSON がサポートされています。

リクエストパラメータの構成

com.aliyun.teaopenapi.models.OpenApiRequest を使用してリクエストパラメータを構成します。リクエストパラメータは、クエリ文字列、本文、またはストリームで渡すことができます。API 操作のメタデータに基づいて、リクエストパラメータを渡すメソッドを選択します。たとえば、DescribeInstanceTypeFamilies API 操作の RegionId リクエストパラメータは、メタデータで {"name":"RegionId","in":"query",...}} として定義されています。"in":"query" は、RegionId パラメータがクエリ文字列で渡されることを示します。

パラメータの渡し方	シナリオ
setQuery	メタデータで `"in":"query"` が定義されている場合は、setQuery でパラメータを渡します。
setBody	メタデータで `"in":"body''` または `"in": "formData"` が定義されている場合は、setBody でパラメータを渡します。リクエスト本文でリクエストパラメータを渡す場合は、リクエスト本文のタイプに基づいて `reqBodyType` パラメータの値を指定します。
setStream	ファイルをアップロードする必要がある場合は、setStream でファイルストリームを渡すことができます。

        // シナリオ 1: クエリ文字列を構成する。
        java.util.Map<String, Object> queries = new java.util.HashMap<>();
        queries.put("RegionId", "cn-hangzhou");
        com.aliyun.teaopenapi.models.OpenApiRequest request = new com.aliyun.teaopenapi.models.OpenApiRequest()
                .setQuery(com.aliyun.openapiutil.Client.query(queries));

//        // 方法 2: 本文を構成し、reqBodyType を json に設定する。
//        java.util.Map<String, Object> body = new java.util.HashMap<>();
//        body.put("param1", "value1");
//        body.put("param2", "value2");
//        com.aliyun.teaopenapi.models.OpenApiRequest request = new com.aliyun.teaopenapi.models.OpenApiRequest()
//                .setBody(com.aliyun.openapiutil.Client.query(body));

//        // 方法 3: 本文を構成し、reqBodyType を formData に設定する。
//        java.util.Map<String, Object> formData = new java.util.HashMap<>();
//        formData.put("param1", "value1");
//        formData.put("param2", "value2");
//        com.aliyun.teaopenapi.models.OpenApiRequest request = new com.aliyun.teaopenapi.models.OpenApiRequest()
//                .setBody(formData);

//        // 方法 4: Stream パラメータを構成してファイルストリームを渡す
//        com.aliyun.teaopenapi.models.OpenApiRequest request = new com.aliyun.teaopenapi.models.OpenApiRequest()
//                .setStream("<FILE_STREAM>");  // <FILE_STREAM> を実際のファイルストリームに置き換えます。

リクエストの開始

com.aliyun.teaopenapi.Client オブジェクトを使用して callApi メソッドを呼び出し、リクエストを開始します。API 操作を呼び出すときに、タイムアウトパラメータやプロキシパラメータなどのランタイムパラメータを指定できます。詳細については、「詳細設定」をご参照ください。

        // ランタイムオプションを構成する。
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
// SSL 証明書認証を無効にする。
//        runtime.ignoreSSL = true;
// 自動再試行メカニズムを有効にする。
//        runtime.autoretry = true;
// 自動再試行の回数を指定する。
//        runtime.maxAttempts = 3;
// 接続タイムアウト期間を指定する。
//        runtime.connectTimeout = 5000;
// 読み取りリクエストのタイムアウト期間を指定する。
//       runtime.readTimeout = 10000;
        // レスポンスは MAP タイプで、レスポンス本文、レスポンスヘッダー、HTTP ステータスコードが含まれています。
        java.util.Map<String, ?> response = client.callApi(params, request, runtime);
        System.out.println(new com.google.gson.Gson().toJson(response));

サンプルコード

例：RPC スタイルの API 操作の呼び出し

この例では、Elastic Compute Service (ECS) の DescribeInstanceTypeFamilies 操作を呼び出して、操作の汎用呼び出しを行う方法を示します。

import com.aliyun.teaopenapi.Client;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teaopenapi.models.OpenApiRequest;
import com.aliyun.teaopenapi.models.Params;
import com.aliyun.teautil.models.RuntimeOptions;
import com.google.gson.Gson;

import java.util.HashMap;
import java.util.Map;

import static com.aliyun.openapiutil.Client.query;

public class Sample {
    public static void main(String[] args) throws Exception {
        Config config = new Config()
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
                .setEndpoint("ecs-cn-hangzhou.aliyuncs.com");
        Client client = new Client(config);
        Params params = new Params()
                .setStyle("RPC")  // API スタイル。
                .setVersion("2014-05-26") // 操作のバージョン番号。
                .setMethod("POST") // 操作の HTTP メソッド。
                .setAction("DescribeInstanceTypeFamilies")  // API 操作の名前。
                .setPathname("/") 
                .setProtocol("HTTPS")
                .setAuthType("AK")
                .setReqBodyType("json")
                .setBodyType("json");
        // クエリパラメータを指定します。
        Map<String, Object> queries = new HashMap<>();
        queries.put("RegionId", "cn-hangzhou");
        // ランタイム構成オブジェクトを作成します。
        RuntimeOptions runtime = new RuntimeOptions();
        OpenApiRequest request = new OpenApiRequest()
                .setQuery(query(queries));
        // レスポンスは MAP タイプで、レスポンス本文、レスポンスヘッダー、HTTP ステータスコードが含まれています。
        Map<String, ?> response = client.callApi(params, request, runtime);
        System.out.println(new Gson().toJson(response));
    }
}

例：RESTful スタイル (ROA スタイル) の API 操作の呼び出し

この例では、Container Service for Kubernetes (ACK) の DescribeClustersV1 操作を呼び出して、操作の汎用呼び出しを行う方法を示します。

import com.aliyun.teaopenapi.Client;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teaopenapi.models.OpenApiRequest;
import com.aliyun.teaopenapi.models.Params;
import com.aliyun.teautil.models.RuntimeOptions;
import com.google.gson.Gson;

import java.util.HashMap;
import java.util.Map;

import static com.aliyun.openapiutil.Client.query;

public class Test3 {
    public static void main(String[] args_) throws Exception {
        Config config = new Config()
                .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
                .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
                .setEndpoint("cs.cn-hangzhou.aliyuncs.com");
        Client client = new Client(config);
        Params params = new Params()
                .setStyle("ROA") // API スタイル。
                .setVersion("2015-12-15") // API バージョン。
                .setAction("DescribeClustersV1") // 呼び出す操作。
                .setPathname("/api/v1/clusters") // API URI。
                .setMethod("GET") // リクエストメソッド。
                .setProtocol("HTTPS")
                .setAuthType("AK")
                .setReqBodyType("json")
                .setBodyType("json");
        // クエリパラメータを指定します。
        Map<String, Object> queries = new HashMap<>();
        queries.put("name", "cluster-demo");
        OpenApiRequest request = new OpenApiRequest()
                .setQuery(query(queries));
        RuntimeOptions runtime = new RuntimeOptions();
        // レスポンスは MAP タイプで、レスポンス本文、レスポンスヘッダー、HTTP ステータスコードが含まれています。
        Map<String, ?> response = client.callApi(params, request, runtime);
        System.out.println(new Gson().toJson(response));
    }
}