Gunakan CommonRequest untuk melakukan panggilan dengan Java SDK - Alibaba Cloud SDK

Alibaba Cloud SDK V1.0 untuk Java mendukung panggilan API generik. Topik ini menjelaskan cara melakukan panggilan generik menggunakan Alibaba Cloud SDK V1.0 untuk Java.

Karakteristik

Ringan: Anda hanya perlu menginstal aliyun-java-sdk-core untuk memanggil semua OpenAPI tanpa perlu menginstal SDK produk individual.
Iterasi cepat dan kompatibilitas: Jika layanan cloud tidak menyediakan SDK atau SDK belum diperbarui untuk operasi API terbaru, Anda dapat melakukan panggilan generik sehingga dapat langsung memanggil operasi API terbaru tanpa menunggu pembaruan SDK.

Untuk informasi selengkapnya, lihat Panggilan generik dan panggilan khusus.

Catatan Penggunaan

Sebelum melakukan panggilan generik, Anda harus secara manual memperoleh dan menentukan metadata yang diperlukan, termasuk versi API, URL permintaan, dan jenis parameter. Untuk informasi selengkapnya, lihat Metadata API.

Instal Core SDK

Tambahkan dependensi berikut ke file pom.xml untuk menginstal pustaka inti Alibaba Cloud SDK V1.0 untuk Java.

<dependency>
     <groupId>com.aliyun</groupId>
     <artifactId>aliyun-java-sdk-core</artifactId>
     // Pilih versi.
     <version>[(4.0.0,5.0.0)]</version>
</dependency>

Panggil Operasi API

Inisialisasi klien permintaan

Dalam paket com.aliyuncs, buat modul client untuk menginisialisasi klien permintaan, lalu gunakan client tersebut untuk memanggil operasi API. Pada contoh ini, pasangan AccessKey digunakan untuk menginisialisasi klien permintaan. Untuk informasi selengkapnya, lihat Kelola kredensial akses.

Catatan

Untuk mencegah kebocoran AccessKey, Anda dapat menyimpan pasangan AccessKey dalam variabel lingkungan. Untuk informasi selengkapnya, lihat Konfigurasi variabel lingkungan di Linux, macOS, dan Windows.

 import com.aliyuncs.DefaultAcsClient;
 import com.aliyuncs.profile.DefaultProfile;
 
        // 1. Buat dan inisialisasi instance DefaultAcsClient.
        DefaultProfile profile = DefaultProfile.getProfile(
                // ID wilayah Anda.
                "cn-hangzhou",
                // System.getenv menunjukkan bahwa ID AccessKey pengguna Resource Access Management (RAM) diperoleh dari variabel lingkungan.
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // System.getenv menunjukkan bahwa Rahasia AccessKey pengguna RAM diperoleh dari variabel lingkungan.
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // Opsional. Konfigurasi HTTPS untuk client.
        HttpClientConfig clientConfig = HttpClientConfig.getDefault();
//        // Jangan verifikasi sertifikat sisi server.
//        clientConfig.setIgnoreSSLCerts(true);
//        // Jumlah maksimum koneksi untuk setiap host.
//        clientConfig.setMaxRequestsPerHost(6);
//        // Timeout koneksi.
//        clientConfig.setConnectionTimeoutMillis(30000L);
//        // Timeout baca.
//        clientConfig.setReadTimeoutMillis(30000L);
//        // Timeout tulis.
//        clientConfig.setWriteTimeoutMillis(60000L);
//        // Atur proxy HTTP.
//        clientConfig.setHttpProxy("http://127.0.0.1:9898");
//        // Atur proxy HTTPS.
//        clientConfig.setHttpsProxy("http://user:password@127.0.0.1:8989");
//        // Atur daftar alamat yang diabaikan untuk proxy.
//        clientConfig.setNoProxy("127.0.0.1,localhost");

        profile.setHttpClientConfig(clientConfig);
        IAcsClient client = new DefaultAcsClient(profile);

Konfigurasikan informasi dasar dan parameter permintaan operasi API

Gunakan CommonRequest untuk mengonfigurasi parameter permintaan umum dan parameter spesifik operasi untuk operasi API. Untuk informasi selengkapnya tentang parameter permintaan umum, lihat Pengaturan lanjutan.

Catatan

Modul CommonRequest digunakan untuk mengonversi metadata API—seperti nomor versi, URL, dan jenis parameter—menjadi permintaan HTTP yang valid melalui proses konfigurasi permintaan standar, lalu mengembalikan data respons asli. Cara melewatkan parameter ditentukan oleh gaya dan desain API.

Parameter Permintaan API

Cara melewatkan parameter permintaan ditentukan oleh metadata operasi API. Misalnya, operasi API DescribeInstanceStatus didefinisikan sebagai {"name":"RegionId","in":"query",...} dalam metadata. Dalam kasus ini, "in":"query" menunjukkan bahwa ID wilayah (RegionId) harus dilewatkan melalui putQueryParameter.

Deskripsi	Cara melewatkan parameter
Berlaku ketika parameter permintaan diatur sebagai `"in":"query"`.	putQueryParameter(String key,String value) Catatan Jika parameter permintaan berupa koleksi, Anda dapat menentukan parameter tersebut sebagai putQueryParameter("key.1","value1"); Anda dapat melewatkan parameter menggunakan format putQueryParameter("key.2","value2"); dst.
Berlaku ketika parameter permintaan adalah `"in":"body"` atau `"in": "formData"`.	putBodyParameter(String key,String value) Catatan Jika parameter permintaan tidak berupa string, konversi nilai parameter menjadi string JSON dan tentukan string tersebut sebagai nilai variabel. Contoh: request.putBodyParameter("key",new Gson().toJson(value));
Unggah file	setHttpContent(byte[] content,String charset,FormatType formatType) Catatan Atur formatType ke FormatType.RAW.

        // 2. Buat permintaan API dan konfigurasikan parameter permintaan.
        // Contoh ini menunjukkan cara membuat permintaan untuk memanggil operasi DescribeInstanceStatus, yang digunakan untuk memperoleh status Elastic Compute Service (ECS).
        CommonRequest request = new CommonRequest();
        // 2.1  Konfigurasikan parameter permintaan umum.
        request.setSysMethod(com.aliyuncs.http.MethodType.POST);
        request.setSysDomain("ecs-cn-hangzhou.aliyuncs.com");// Nama domain operasi API.
        request.setSysVersion("2014-05-26");// Versi API.
        request.setSysAction("DescribeInstanceStatus"); // Nama operasi API. Saat memanggil operasi API bergaya RPC, Anda harus mengonfigurasi SysAction() untuk menentukan nama operasi API.
        request.setSysConnectTimeout(30000); // Periode timeout.
        request.setSysProtocol(com.aliyuncs.http.ProtocolType.HTTPS); // Protokol permintaan. Nilai yang valid: HTTP dan HTTPS. Kami menyarankan Anda menggunakan HTTPS. 
//        request.setSysUriPattern("/"); // Pola URI. Jangan konfigurasi parameter ini untuk operasi API bergaya RPC. 
        
        // 2.2 Konfigurasikan parameter permintaan spesifik operasi.
        // Skenario 1: Tentukan parameter kueri dalam putQueryParameter(string key,string value).
        request.putQueryParameter("RegionId", "cn-hangzhou");
        List<String> instanceIds = List.of(
                "i-bp1axhql4dqXXXXXXXX",
                "i-bp124uve8zqXXXXXXXX"
        );
        for(int i = 0; i < instanceIds.size(); ++i) {
            request.putQueryParameter("InstanceId." + (i + 1), (String)instanceIds.get(i));
        }
        request.putQueryParameter("PageNumber", "1");
        request.putQueryParameter("PageSize", "30");

        // Skenario 2: Tentukan parameter body dalam putBodyParameter(string key,string value).
        // request.putBodyParameter("key1", "value1");
        // request.putBodyParameter("key2", "value2");
        // request.putBodyParameter("key3", "value3");

        // Skenario 3: Untuk mengunggah file, tentukan setHttpContent(byte[] content,String charset,FormatType formatType). Atur formatType ke FormatType.RAW. 
        // byte[] bodyImg = Files.readAllBytes(Paths.get("<FILE_PATH>")); // Ganti <FILE_PATH> dengan jalur file aktual.
        // request.setHttpContent(bodyImg, "UTF-8", FormatType.RAW);

Lakukan permintaan

Gunakan client untuk memanggil metode getCommonResponse.

// Kirim permintaan.
CommonResponse response = client.getCommonResponse(request);
// Nilai kembali, response.getData(), adalah data berformat JSON yang berisi RequestId dan parameter kembali OpenAPI.
System.out.println(response.getData());

Kode Contoh

Contoh: Panggil operasi API bergaya RPC

Pada contoh ini, operasi DescribeInstanceStatus ECS dipanggil menggunakan CommonRequest.

import com.aliyuncs.CommonRequest;
import com.aliyuncs.CommonResponse;
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.http.FormatType;
import com.aliyuncs.profile.DefaultProfile;
import com.google.gson.GsonBuilder;

import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

public class Sample {
    public static void main(String[] args) throws ClientException, UnsupportedEncodingException {
        // Buat dan inisialisasi instance DefaultAcsClient.
        DefaultProfile profile = DefaultProfile.getProfile(
                // ID wilayah Anda.
                "cn-hangzhou",
                // Peroleh ID AccessKey pengguna RAM dari variabel lingkungan.
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // Peroleh Rahasia AccessKey pengguna RAM dari variabel lingkungan.
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        IAcsClient client = new DefaultAcsClient(profile);
        
        // Buat permintaan API dan atur parameter.
        CommonRequest request = new CommonRequest();
        request.setSysMethod(com.aliyuncs.http.MethodType.POST); // Metode permintaan.
        request.setSysDomain("ecs-cn-hangzhou.aliyuncs.com"); // Nama domain operasi API.
        request.setSysVersion("2014-05-26"); // Nomor versi API.
        request.setSysAction("DescribeInstanceStatus"); // Nama operasi API. Saat memanggil operasi API bergaya RPC, Anda harus mengonfigurasi SysAction() untuk menentukan nama operasi.
         request.setSysProtocol(com.aliyuncs.http.ProtocolType.HTTPS); // Protokol permintaan. Nilai yang valid: HTTPS dan HTTP. Kami menyarankan Anda menggunakan HTTPS.
        request.putQueryParameter("RegionId", "cn-hangzhou");
        List<String> instanceIds = List.of(
                "i-bp1axhql4dqXXXXXXXX",
                "i-bp124uve8zqXXXXXXXX"
        );
        for(int i = 0; i < instanceIds.size(); ++i) {
            request.putQueryParameter("InstanceId." + (i + 1), (String)instanceIds.get(i));
        }
        request.putQueryParameter("PageNumber", "1");
        request.putQueryParameter("PageSize", "30");
        try {
            CommonResponse response = client.getCommonResponse(request);
            System.out.println(response.getData());
        } catch (ServerException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        } catch (ClientException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        }
    }
}

Contoh: Panggil operasi API RESTful

Pada contoh ini, operasi DescribeClustersV1 Container Service for Kubernetes (ACK) dipanggil menggunakan CommonRequest.

import com.aliyuncs.CommonRequest;
import com.aliyuncs.CommonResponse;
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.profile.DefaultProfile;
public class Sample {
    public static void main(String[] args) {
        // Buat dan inisialisasi instance DefaultAcsClient.
        DefaultProfile profile = DefaultProfile.getProfile(
                // ID wilayah Anda.
                "cn-hangzhou",
                // Peroleh ID AccessKey pengguna RAM dari variabel lingkungan.
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // Peroleh Rahasia AccessKey pengguna RAM dari variabel lingkungan.
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        IAcsClient client = new DefaultAcsClient(profile);
        // Buat permintaan API dan atur parameter.
        CommonRequest request = new CommonRequest();
        request.setSysDomain("cs.aliyuncs.com");// Nama domain.
        request.setSysVersion("2015-12-15");// Versi API.
        request.setSysUriPattern("/clusters"); // URI sumber daya API. Saat memanggil operasi API bergaya ROA, Anda harus mengonfigurasi UriPattern() untuk menentukan jalur sumber daya lengkap. Peroleh jalur sumber daya dari data.path dalam metadata OpenAPI.
        request.setSysMethod(MethodType.GET);// Metode permintaan.
        try {
            CommonResponse response = client.getCommonResponse(request);
            System.out.println(response.getData());
        } catch (ServerException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        } catch (ClientException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        }
    }
}

FAQ

Pesan error menunjukkan bahwa parameter "AccessKeyId" yang diperlukan tidak ada.
Penyebab: Pasangan AccessKey tidak dikonfigurasi dengan benar.
Solusi:
1. Jalankan perintah berikut untuk memeriksa apakah variabel lingkungan ALIBABA_CLOUD_ACCESS_KEY_ID dan ALIBABA_CLOUD_ACCESS_KEY_SECRET telah dikonfigurasi.
  Linux/macOS
```
echo $ALIBABA_CLOUD_ACCESS_KEY_ID
echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET
```
  Windows
```
echo %ALIBABA_CLOUD_ACCESS_KEY_ID%
echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%
```
  Jika pasangan AccessKey yang valid dikembalikan, berarti variabel lingkungan telah dikonfigurasi dengan benar. Jika tidak ada pasangan AccessKey atau pasangan AccessKey tidak valid yang dikembalikan, konfigurasikan variabel lingkungan sesuai kebutuhan. Untuk informasi selengkapnya, lihat Konfigurasi variabel lingkungan di Linux, macOS, dan Windows.
2. Periksa kesalahan terkait pasangan AccessKey dalam kode.
  Contoh kesalahan umum:
```
accessKeyId = System.getenv("yourAccessKeyID"),
accessKeySecret = System.getenv("yourAccessKeySecret")
```
  Catatan
  Pada contoh permintaan error di atas, nilai input System.getenv() digunakan sebagai pasangan AccessKey. Namun, fungsi ini digunakan untuk membaca nilai dari variabel lingkungan. Setelah Anda menentukan nama variabel lingkungan sebagai ALIBABA_CLOUD_ACCESS_KEY_ID dan ALIBABA_CLOUD_ACCESS_KEY_SECRET di mesin Anda, System.getenv dapat membaca nilai dari variabel lingkungan tersebut.
  Contoh yang benar
```
System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")
System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
```
Permintaan gagal dengan pesan error berikut: "com.aliyuncs.exceptions.ClientException: MissingParameter : Parameter input "Timestamp" yang wajib untuk memproses permintaan ini tidak disediakan."
Penyebab: Parameter SysUriPattern dikonfigurasi dalam parameter permintaan umum operasi API bergaya RPC.
Solusi: Hapus parameter SysUriPattern dari parameter permintaan umum.