Panggilan generik - Alibaba Cloud SDK

Alibaba Cloud SDK for Java V2.0 mendukung pemanggilan API generik. Topik ini menjelaskan cara melakukan pemanggilan generik menggunakan Alibaba Cloud SDK for Java V2.0.

Karakteristik

Ringan: Anda hanya perlu menginstal pustaka inti dari Alibaba Cloud SDK for Java V2.0 dan tidak perlu menginstal SDK untuk layanan cloud tertentu.

Mudah digunakan: Cukup buat parameter permintaan umum dan gunakan klien umum untuk memulai permintaan. Respon akan dikembalikan dalam format umum.

Untuk informasi lebih lanjut, lihat Pemanggilan generik dan spesifik.

Catatan penggunaan

Sebelum melakukan pemanggilan generik, disarankan untuk melihat metadata operasi API untuk mengetahui gaya API, parameter permintaan, dan URL. Untuk informasi lebih lanjut, lihat Metadata API.

Instal pustaka inti dari Alibaba Cloud SDK for Java V2.0

Tambahkan dependensi berikut ke file pom.xml untuk menginstal pustaka inti dari SDK for Java V2.0. Untuk informasi lebih lanjut tentang versi terbaru, lihat Maven Repository.

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

Panggil operasi API

Inisialisasi klien permintaan

Buat objek com.aliyun.teaopenapi.Client untuk menginisialisasi klien permintaan, lalu gunakan klien tersebut untuk memanggil operasi API. Saat menginisialisasi klien, Anda juga dapat menggunakan alat Credentials. Untuk informasi lebih lanjut tentang alat Credentials, lihat Kelola kredensial akses.

Catatan

Anda tidak perlu secara manual menghapus objek klien karena objek tersebut akan otomatis didaur ulang oleh mekanisme pengumpulan sampah.

        // 1. Inisialisasi klien permintaan
        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"));
        // Tentukan titik akhir ASAPI.
        config.setEndpoint("ecs.cn-hangzhou.aliyuncs.com");
        // Opsional. Konfigurasikan proxy dengan menggunakan objek Config saat menginisialisasi klien.
        // Tentukan HTTPS sebagai protokol saat menginisialisasi klien.
        // config.setProtocol("HTTPS");
        // Tentukan ID wilayah.
        // config.setRegionId("<regionId>");
        // Konfigurasikan proxy saat menginisialisasi klien.
        // 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");
        // Konfigurasikan periode timeout saat menginisialisasi klien SDK.
        // Periode timeout default untuk permintaan koneksi adalah 5.000 milidetik. Nilainya dihitung dengan rumus: 5 × 1.000 = 5.000.
        // config.setConnectTimeout(5000);
        // Periode timeout default untuk permintaan baca adalah 10.000 milidetik.
        // config.setReadTimeout(10000);
        com.aliyun.teaopenapi.Client client = new com.aliyun.teaopenapi.Client(config);

//        // Gunakan alat 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);

Konfigurasikan informasi tentang operasi API

Gunakan kelas com.aliyun.teaopenapi.models.Params untuk mengonfigurasi informasi dasar tentang operasi API yang ingin dipanggil, seperti gaya API, versi API, dan metode permintaan. Dalam contoh berikut, operasi DescribeInstanceTypeFamilies dipanggil.

        com.aliyun.teaopenapi.models.Params params = new com.aliyun.teaopenapi.models.Params()
                .setStyle("RPC")  // Gaya API, seperti remote procedure call (RPC) atau resource-oriented architecture (ROA).
                .setVersion("2014-05-26") // Versi API.
                .setMethod("POST") // Metode permintaan.
                .setAction("DescribeInstanceTypeFamilies")  // Nama operasi API.
                .setPathname("/") // URL operasi. Jalur default untuk operasi bergaya RPC adalah /. Anda bisa mendapatkan URL operasi bergaya ROA dari parameter data.path dalam metadata API.
                .setProtocol("HTTPS") // Protokol permintaan, seperti HTTPS atau HTTP. Kami sarankan Anda menggunakan HTTPS.
                .setAuthType("AK") // Jenis autentikasi. Gunakan tipe default. Jika operasi mendukung permintaan anonim, Anda dapat menentukan parameter Anonymous untuk memulai permintaan anonim.
                .setReqBodyType("json") // Tipe body permintaan. Nilai valid: byte, json, dan formData.
                .setBodyType("json"); // Format respons. JSON didukung.

Konfigurasikan parameter permintaan

Gunakan com.aliyun.teaopenapi.models.OpenApiRequest untuk mengonfigurasi parameter permintaan. Anda dapat meneruskan parameter permintaan dalam string kueri, body, atau aliran. Pilih metode untuk meneruskan parameter permintaan berdasarkan metadata operasi API. Sebagai contoh, parameter permintaan RegionId dari operasi API DescribeInstanceTypeFamilies didefinisikan sebagai {"name":"RegionId","in":"query",...}} dalam metadata. "in":"query" menunjukkan bahwa parameter RegionId diteruskan dalam string kueri.

Bagaimana parameter diteruskan	Skenario
setQuery	Jika metadata mendefinisikan `"in":"query"`, teruskan parameter dalam setQuery.
setBody	Jika metadata mendefinisikan `"in":"body''` atau `"in": "formData"`, teruskan parameter dalam setBody. Jika Anda meneruskan parameter permintaan dalam body permintaan, tentukan nilai untuk parameter `reqBodyType` berdasarkan tipe body permintaan.
setStream	Jika Anda perlu mengunggah file, Anda dapat meneruskan aliran file dalam setStream.

        // Skenario 1: Konfigurasikan string kueri.
        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));

//        // Metode 2: Konfigurasikan body dan atur reqBodyType ke 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));

//        // Metode 3: Konfigurasikan body dan atur reqBodyType ke 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);

//        // Metode 4: Konfigurasikan parameter Stream untuk meneruskan aliran file
//        com.aliyun.teaopenapi.models.OpenApiRequest request = new com.aliyun.teaopenapi.models.OpenApiRequest()
//                .setStream("<FILE_STREAM>");  // Ganti <FILE_STREAM> dengan aliran file sebenarnya.

Mulai permintaan

Gunakan objek com.aliyun.teaopenapi.Client untuk memanggil metode callApi guna memulai permintaan. Saat memanggil operasi API, Anda dapat menentukan parameter runtime, seperti timeout dan proxy. Untuk informasi lebih lanjut, lihat Pengaturan lanjutan.

        // Konfigurasikan opsi runtime.
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
// Nonaktifkan autentikasi sertifikat SSL.
//        runtime.ignoreSSL = true;
// Aktifkan mekanisme pengulangan otomatis.
//        runtime.autoretry = true;
// Tentukan jumlah pengulangan otomatis.
//        runtime.maxAttempts = 3;
// Tentukan periode timeout koneksi.
//        runtime.connectTimeout = 5000;
// Tentukan periode timeout permintaan baca.
//       runtime.readTimeout = 10000;
        // Respons bertipe MAP, yang berisi body respons, header respons, dan kode status HTTP.
        java.util.Map<String, ?> response = client.callApi(params, request, runtime);
        System.out.println(new com.google.gson.Gson().toJson(response));

Kode contoh

Contoh: Panggil operasi API bergaya RPC

Dalam contoh ini, operasi DescribeInstanceTypeFamilies dari Elastic Compute Service (ECS) dipanggil untuk menunjukkan cara melakukan pemanggilan generik suatu operasi.

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")  // Gaya API.
                .setVersion("2014-05-26") // Nomor versi operasi.
                .setMethod("POST") // Metode HTTP operasi.
                .setAction("DescribeInstanceTypeFamilies")  // Nama operasi API.
                .setPathname("/")
                .setProtocol("HTTPS")
                .setAuthType("AK")
                .setReqBodyType("json")
                .setBodyType("json");
        // Tentukan parameter kueri.
        Map<String, Object> queries = new HashMap<>();
        queries.put("RegionId", "cn-hangzhou");
        // Buat objek konfigurasi runtime.
        RuntimeOptions runtime = new RuntimeOptions();
        OpenApiRequest request = new OpenApiRequest()
                .setQuery(query(queries));
        // Respons bertipe MAP, yang berisi body respons, header respons, dan kode status HTTP.
        Map<String, ?> response = client.callApi(params, request, runtime);
        System.out.println(new Gson().toJson(response));
    }
}

Contoh: Panggil operasi API bergaya RESTful (ROA)

Dalam contoh ini, operasi DescribeClustersV1 dari Container Service for Kubernetes (ACK) dipanggil untuk menunjukkan cara melakukan pemanggilan generik suatu operasi.

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") // Gaya API.
                .setVersion("2015-12-15") // Versi API.
                .setAction("DescribeClustersV1") // Operasi yang ingin Anda panggil.
                .setPathname("/api/v1/clusters") // URI API.
                .setMethod("GET") // Metode permintaan.
                .setProtocol("HTTPS")
                .setAuthType("AK")
                .setReqBodyType("json")
                .setBodyType("json");
        // Tentukan parameter kueri.
        Map<String, Object> queries = new HashMap<>();
        queries.put("name", "cluster-demo");
        OpenApiRequest request = new OpenApiRequest()
                .setQuery(query(queries));
        RuntimeOptions runtime = new RuntimeOptions();
        // Respons bertipe MAP, yang berisi body respons, header respons, dan kode status HTTP.
        Map<String, ?> response = client.callApi(params, request, runtime);
        System.out.println(new Gson().toJson(response));
    }
}