Konfigurasi kebijakan retry Java SDK V1 untuk panggilan API yang tangguh - Alibaba Cloud SDK

Topik ini menjelaskan mekanisme ulang dari Alibaba Cloud SDK V1.0 untuk Java.

Catatan

Mekanisme ulang dan kebijakan pembatasan telah ditambahkan. Untuk informasi lebih lanjut, lihat Mekanisme backoff lanjutan berdasarkan kebijakan pembatasan.

Pustaka inti aliyun-java-sdk-core versi 4.6.0 atau yang lebih baru mendukung mekanisme ulang dan menyediakan skema backoff lanjutan berdasarkan kebijakan pembatasan. Untuk informasi lebih lanjut, lihat Mekanisme backoff lanjutan berdasarkan kebijakan pembatasan. Anda harus menambahkan dependensi Maven berikut:

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

Mekanisme Ulang

Nonaktifkan mekanisme ulang

Mekanisme ulang dinonaktifkan secara default. Anda dapat menggunakan salah satu metode berikut untuk menentukan kebijakan ulang sebagai none guna menonaktifkan mekanisme ulang:

// Tentukan kebijakan ulang untuk klien untuk menonaktifkan mekanisme ulang.
client.setSysRetryPolicy(RetryPolicy.none());

// Tentukan kebijakan ulang untuk permintaan. Konfigurasi kebijakan ulang permintaan mengambil prioritas atas konfigurasi kebijakan ulang klien.
request.setSysRetryPolicy(RetryPolicy.none());

Kebijakan ulang

Jenis kebijakan ulang berikut didukung:

Tentukan pengecualian.
Tentukan kode status HTTP.
Tentukan header respons HTTP.

Ketiga jenis kebijakan tersebut bersifat independen. Jika salah satu kondisi yang Anda tentukan terpenuhi, ulang dilakukan atau tidak dilakukan. Kebijakan tersebut dapat digunakan untuk memicu atau membatasi ulang.

Berikut adalah contoh kode yang menunjukkan cara mengonfigurasi kebijakan untuk memicu atau membatasi ulang:

Buat koleksi kondisi untuk memicu ulang:

Set<RetryCondition> retryConditions = new HashSet<RetryCondition>();

// Contoh kondisi
// Tentukan kode status untuk memicu ulang. Dalam contoh berikut, ulang dilakukan ketika kode status 500 atau 501 dikembalikan.
Set<Integer> statusCodes = new HashSet<Integer>();
statusCodes.add(500); // http statusCode
statusCodes.add(501); // http statusCode
// Tambahkan konfigurasi kode status ke kebijakan yang digunakan untuk memicu ulang.
retryConditions.add(StatusCodeCondition.create(statusCodes));

// Tentukan pengecualian untuk memicu ulang. Dalam contoh berikut, ulang dilakukan ketika SocketTimeoutException atau IOException dilempar.
Set<Class<?  extends Exception>> exceptions = new HashSet<Class<?  extends Exception>>();
exceptions.add(SocketTimeoutException.class); // exception
exceptions.add(IOException.class); // exception
// Tambahkan konfigurasi pengecualian ke kebijakan yang digunakan untuk memicu ulang.
retryConditions.add(ExceptionsCondition.create(exceptions));

Buat koleksi kondisi untuk membatasi ulang:

Set<RetryCondition> throttlingConditions = new HashSet<RetryCondition>();

// Contoh kondisi
// Tentukan kode status untuk membatasi ulang. Dalam contoh berikut, ulang dilarang ketika kode status 429 dikembalikan.
Set<Integer> code = new HashSet<Integer>();
code.add(429); // Tentukan kode status HTTP untuk membatasi ulang. Dalam contoh ini, ulang dilarang jika kode status 429 dikembalikan.
// Tambahkan konfigurasi kode status ke kebijakan yang digunakan untuk membatasi ulang.
throttlingConditions.add(StatusCodeCondition.create(code));

Tambahkan kondisi ke RetryPolicy:

RetryPolicy retryPolicy = RetryPolicy.builder()
                .maxNumberOfRetries(3) // Jumlah maksimum ulang.
                .maxDelayTimeMillis(20 * 1000) // Interval ulang maksimum. Unit: milidetik. Jika durasi yang ditentukan terlampaui, ulang tidak dilakukan.
                .retryConditions(retryConditions) // Kebijakan yang digunakan untuk memicu ulang.
                . .throttlingConditions(throttlingConditions) // Kebijakan yang digunakan untuk membatasi ulang.
                .build();

Interval untuk setiap ulang dihitung menggunakan algoritma backoff eksponensial. Algoritma EqualJitter digunakan untuk menghitung waktu tunggu untuk ulang berikutnya.

Konfigurasikan pengaturan lanjutan untuk kondisi ulang

Tiga kondisi disediakan. Berikut adalah detail masing-masing kondisi:

StatusCodeCondition
1. Kondisi ini menyimpan kumpulan bilangan bulat. SDK membandingkan kode status HTTP dalam kumpulan dengan kode status yang dikembalikan dan menentukan apakah akan memicu atau membatasi ulang.
ExceptionsCondition
1. Kondisi ini menyimpan kumpulan pengecualian. SDK membandingkan pengecualian dalam kumpulan dengan pengecualian yang dilempar untuk panggilan tersebut dan menentukan apakah akan memicu atau membatasi ulang.
HeadersCondition
1. Kondisi ini menyimpan peta. Struktur peta tersebut kompleks. Kunci peta cocok dengan kunci header respons. Antarmuka Pattern(com.aliyuncs.policy.retry.pattern.Pattern) perlu dipanggil untuk mendapatkan nilai peta. Nilai yang sesuai dengan kunci header respons dicocokkan oleh ekspresi. Misalnya, apakah nilai tersebut mengandung string atau sama dengan suatu nilai diperiksa.
2. Dua pola didukung: AliyunThrottlingPattern dan SimplePattern. Antarmuka pola AliyunThrottlingPattern dipanggil berdasarkan kebijakan pembatasan yang disediakan oleh Alibaba Cloud. Untuk informasi lebih lanjut, lihat Mekanisme backoff lanjutan berdasarkan kebijakan pembatasan. Antarmuka pola SimplePattern membandingkan apakah nilainya sama.
3. Anda dapat membuat antarmuka pola kustom. Dalam kelas yang berisi antarmuka pola, Anda harus mengimplementasikan fungsi berikut:
  1. meetState(): menentukan apakah kondisi yang Anda tentukan terpenuhi.
  2. escapeTime(): menentukan waktu pelarian. Fungsi ini hanya berlaku untuk kebijakan yang digunakan untuk membatasi ulang. Jika nilainya bukan -1, ulang tidak dilakukan selama waktu pelarian, dan ulang tidak dibatasi. Sebagai gantinya, ulang dilakukan hingga ulang dapat dilakukan. Jika nilainya lebih besar dari interval ulang maksimum, sistem mengembalikan pesan kesalahan dan Anda tidak perlu menunggu untuk ulang.
  3. readFormHeadersContent(String content): menetapkan nilai ke parameter. Implementasi kelas SimplePattern dapat langsung digunakan.
Kondisi Kustom
1. Anda dapat membuat kondisi kustom dengan hanya memanggil antarmuka RetryCondition. Untuk memanggil antarmuka RetryCondition, Anda harus mengimplementasikan dua fungsi antarmuka berikut:
  1. meetState(RetryPolicyContext var1): menentukan apakah status pencocokan terpenuhi berdasarkan konteks.
  2. escapeTime(RetryPolicyContext var1): menghitung waktu pelarian. Fungsi ini hanya berlaku untuk kebijakan yang digunakan untuk membatasi ulang. Jika Anda ingin menerapkan fungsi ini ke kebijakan yang digunakan untuk memicu ulang, tetapkan nilainya menjadi -1.

Kode sampel lengkap

Kode sampel:

package com.aliyun.sample;

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.exceptions.ThrottlingException;
import com.aliyuncs.policy.retry.RetryPolicy;
import com.aliyuncs.policy.retry.conditions.ExceptionsCondition;
import com.aliyuncs.policy.retry.conditions.RetryCondition;
import com.aliyuncs.policy.retry.conditions.StatusCodeCondition;
import com.aliyuncs.profile.DefaultProfile;

import java.io.IOException;
import java.net.SocketTimeoutException;
import java.util.HashSet;
import java.util.Set;

public class Sample {
    public static void main(String[] args) {
        // Buat instance DefaultAcsClient dan inisialisasi instance tersebut.
        DefaultProfile profile = DefaultProfile.getProfile(
                // ID wilayah.
                "cn-hangzhou",
                // Dapatkan ID AccessKey dari pengguna Resource Access Management (RAM) dari variabel lingkungan.
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // Dapatkan Secret AccessKey dari pengguna RAM dari variabel lingkungan.
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        IAcsClient client = new DefaultAcsClient(profile);
        // Tentukan kebijakan ulang untuk klien.
        client.setSysRetryPolicy(RetryPolicy.none());
        // Panggil operasi. Dalam contoh ini, CommonRequest digunakan. Jika Anda ingin memanggil operasi yang dienkapsulasi dalam SDK layanan Alibaba Cloud, gunakan <APIName>Request.
        CommonRequest request = new CommonRequest();
        // Tentukan kebijakan ulang untuk permintaan. Konfigurasi kebijakan ulang permintaan mengambil prioritas atas konfigurasi kebijakan ulang klien.
        // Gunakan kebijakan ulang default dan aktifkan mekanisme backoff lanjutan.
        // request.setSysRetryPolicy(RetryPolicy.defaultRetryPolicy(true));
        
        // Gunakan kebijakan ulang kustom.
        // Tentukan kode status untuk memicu ulang.
        Set<RetryCondition> retryConditions = new HashSet<RetryCondition>();
        Set<Integer> statusCodes = new HashSet<Integer>();
        statusCodes.add(500); // http statusCode
        statusCodes.add(501); // http statusCode
        retryConditions.add(StatusCodeCondition.create(statusCodes));

        // Tentukan pengecualian untuk memicu ulang.
        Set<Class<?  extends Exception>> exceptions = new HashSet<Class<?  extends Exception>>();
        exceptions.add(SocketTimeoutException.class); // exception
        exceptions.add(IOException.class); // exception
        retryConditions.add(ExceptionsCondition.create(exceptions));

        // Tentukan kode status untuk membatasi ulang.
        Set<RetryCondition> throttlingConditions = new HashSet<RetryCondition>();
        Set<Integer> code = new HashSet<Integer>();
        code.add(429); // Tentukan kode status HTTP untuk membatasi ulang. Dalam contoh ini, ulang dilarang jika kode status 429 dikembalikan.
        throttlingConditions.add(StatusCodeCondition.create(code));

        RetryPolicy retryPolicy = RetryPolicy.builder()
                .maxNumberOfRetries(3) // Jumlah maksimum ulang.
                .maxDelayTimeMillis(20 * 1000) // Interval ulang maksimum. Jika interval terlampaui, ulang tidak dilakukan.
                .retryConditions(retryConditions) // Kebijakan yang digunakan untuk memicu ulang.
                .enableAliyunThrottlingControl(true) // Aktifkan kebijakan pembatasan yang disediakan oleh Alibaba Cloud untuk kontrol pembatasan.
                .throttlingConditions(throttlingConditions) // Anda dapat menulis kebijakan sendiri untuk membatasi ulang.
                .build();
        request.setSysRetryPolicy(retryPolicy);

        try {
            // Panggil operasi. Dalam contoh ini, CommonRequest digunakan. Jika Anda ingin memanggil operasi yang dienkapsulasi dalam SDK layanan Alibaba Cloud, gunakan <APIName>Request.
            CommonResponse response = client.getCommonResponse(request);
            System.out.println(response.getData());
        } catch (ServerException e) {
            e.printStackTrace();
        } catch (ClientException e) {
            e.printStackTrace();
            if (ThrottlingException.class.isAssignableFrom(e.getCause().getClass())) {
                // Pengecualian pembatasan dienkapsulasi dalam ClientException.
            }
        }
    }
}