API Gateway：Plugin pemutus sirkuit (hanya untuk instance khusus)

Batasan

• Plugin pemutus sirkuit hanya berlaku untuk API dalam instance khusus.

• Setiap ekspresi kondisional dapat berisi maksimal 512 karakter.

• Setiap plugin dapat berisi maksimal 50 KB metadata.

1. Ikhtisar

API Gateway menyediakan pemutus sirkuit untuk setiap API guna melindunginya dari penurunan performa backend yang abnormal. Secara default, jika terjadi timeout sebanyak 1.000 kali di backend API dalam 30 detik, pemutus sirkuit akan aktif. Pemutus sirkuit tetap terbuka selama 90 detik, selama waktu itu kesalahan berikut dikembalikan untuk semua permintaan API: Status=503,X-Ca-Error-Code=D503CB. Setelah 90 detik, pemutus sirkuit mengizinkan beberapa permintaan API dilewatkan. Jika permintaan tersebut berhasil, pemutus sirkuit menutup dan permintaan API dapat diproses seperti biasa.

Anda juga dapat mengaitkan plugin tipe Circuit Breaker ke API untuk menyesuaikan konfigurasi pemutus sirkuitnya. Perlu diperhatikan bahwa plugin pemutus sirkuit hanya berlaku untuk API dalam instance khusus. Berikut adalah konfigurasi pemutus sirkuit yang dapat disesuaikan:

• Kondisi di mana pemutus sirkuit aktif. Anda dapat menentukan bahwa pemutus sirkuit aktif setelah jumlah kejadian timeout atau kesalahan tertentu di backend mencapai ambang batas dalam periode waktu tertentu.

• Jendela waktu selama jumlah kejadian timeout, respons lama, atau kesalahan tertentu di backend diperiksa oleh pemutus sirkuit untuk menentukan apakah akan aktif.

• Periode waktu selama pemutus sirkuit tetap terbuka setelah aktif.

• Backend ke mana permintaan API diarahkan ketika pemutus sirkuit terbuka.

2. Konfigurasi

Circuit breaker plug-ins take effect only for APIs in dedicated instances. If you bind a circuit breaker plug-in to an API in a shared or serverless instance, the circuit breaker still uses the default configurations.

2.1 Tentukan bahwa pemutus sirkuit aktif setelah jumlah kejadian timeout di backend mencapai ambang batas

Saat mengonfigurasi plugin pemutus sirkuit, Anda dapat menentukan bahwa pemutus sirkuit aktif setelah jumlah kejadian timeout di backend mencapai ambang batas dalam periode waktu tertentu. Misalnya, jika ambang batas timeout backend ditetapkan pada 10 detik dan tidak ada respons yang diterima dari backend dalam 10 detik, satu kejadian timeout dihitung.

timeoutThreshold: 15         # Ambang batas jumlah kejadian timeout di backend.
windowInSeconds: 30          # Jendela waktu selama jumlah kejadian timeout di backend diperiksa oleh pemutus sirkuit untuk menentukan apakah akan aktif.
openTimeoutSeconds: 15       # Periode waktu selama pemutus sirkuit tetap terbuka setelah aktif.
downgradeBackend:            # Backend ke mana permintaan API diarahkan ketika pemutus sirkuit terbuka.
  type: mock
  statusCode: 418

Dalam potongan kode sebelumnya, Anda dapat menentukan parameter berikut:

• timeoutThreshold: Ambang batas jumlah kejadian timeout di backend. Jika ambang batas ini tercapai, pemutus sirkuit aktif. Nilai maksimum adalah 5000. Kami sarankan menentukan nilai yang sesuai. Jika nilainya terlalu kecil, pemutus sirkuit akan aktif secara teratur setelah hanya beberapa timeout.

• windowInSeconds: Jendela waktu selama jumlah kejadian timeout di backend diperiksa oleh pemutus sirkuit untuk menentukan apakah akan aktif. Nilai valid: 10 hingga 90. Unit: detik.

• openTimeoutSeconds: Periode waktu selama pemutus sirkuit tetap terbuka setelah aktif. Nilai valid: 15 hingga 300. Unit: detik.

• downgradeBackend: Opsional. Backend ke mana permintaan API diarahkan ketika pemutus sirkuit terbuka.

2.2 Tentukan bahwa pemutus sirkuit aktif setelah jumlah kejadian respons lama di backend mencapai ambang batas

Saat mengonfigurasi plugin pemutus sirkuit, Anda dapat menentukan bahwa pemutus sirkuit aktif setelah jumlah kejadian respons lama di backend mencapai ambang batas dalam periode waktu tertentu. Waktu respons backend adalah durasi antara saat API Gateway mengirim permintaan ke backend dan saat API Gateway menerima respons dari backend.

errorThreshold: 10         # Ambang batas jumlah kejadian respons lama di backend.
windowInSeconds: 60          # Jendela waktu selama jumlah kejadian respons lama di backend diperiksa oleh pemutus sirkuit untuk menentukan apakah akan aktif.
openTimeoutSeconds: 120        # Periode waktu selama pemutus sirkuit tetap terbuka setelah aktif.
errorCondition: "$LatencyMilliSeconds > 500"     # Ekspresi kondisional yang digunakan untuk menentukan apakah respons backend dihitung sebagai respons lama. Dalam contoh ini, jika waktu respons backend melebihi 500 ms, respons dianggap sebagai respons lama.
downgradeBackend:               # Backend ke mana permintaan API diarahkan ketika pemutus sirkuit terbuka.
  type: mock
  statusCode: 403

Dalam potongan kode sebelumnya, Anda dapat menentukan parameter berikut:

• errorThreshold: Ambang batas jumlah kejadian respons lama.

• windowInSeconds: Jendela waktu selama jumlah kejadian timeout di backend diperiksa oleh pemutus sirkuit untuk menentukan apakah akan aktif. Nilai valid: 10 hingga 90. Unit: detik.

• openTimeoutSeconds: Periode waktu selama pemutus sirkuit tetap terbuka setelah aktif. Nilai valid: 15 hingga 300. Unit: detik.

• errorCondition: Ekspresi kondisional yang digunakan untuk menentukan apakah respons backend dihitung sebagai respons lama. Anda dapat menggunakan variabel $LatencyMilliSeconds dan $LatencySeconds. Satuan $LatencyMilliSeconds adalah milidetik. Satuan $LatencySeconds adalah detik.

• downgradeBackend: Opsional. Backend ke mana permintaan API diarahkan ketika pemutus sirkuit terbuka.

2.3 Tentukan bahwa pemutus sirkuit aktif setelah jumlah kejadian kesalahan tertentu di backend mencapai ambang batas

Saat mengonfigurasi plugin pemutus sirkuit, Anda dapat menentukan bahwa pemutus sirkuit aktif setelah jumlah kejadian kesalahan tertentu di backend mencapai ambang batas dalam periode waktu tertentu.

errorCondition: "$StatusCode == 503"  # Ekspresi kondisional yang menentukan kesalahan yang jumlah kejadiannya diperiksa oleh pemutus sirkuit untuk menentukan apakah akan aktif.
errorThreshold: 1000                  # Ambang batas jumlah kejadian kesalahan tertentu.
windowInSeconds: 30                   # Jendela waktu selama jumlah kejadian kesalahan tertentu di backend diperiksa oleh pemutus sirkuit untuk menentukan apakah akan aktif.
openTimeoutSeconds: 15                # Periode waktu selama pemutus sirkuit tetap terbuka setelah aktif.
downgradeBackend:                     # Backend ke mana permintaan API diarahkan ketika pemutus sirkuit terbuka.
  type: "HTTP"
  address: "http://api.foo.com"
  path: "/system-busy.json"
  method: GET

• errorCondition: Ekspresi kondisional yang menentukan kesalahan yang jumlah kejadiannya diperiksa oleh pemutus sirkuit untuk menentukan apakah akan aktif. Anda dapat menggunakan variabel $StatusCode dan $LatencySeconds.

  • Jika Anda menentukan ekspresi kondisional sebagai $StatusCode = 503 or $StatusCode = 504, pemutus sirkuit memeriksa jumlah total kejadian kode status HTTP 503 atau 504.

  • Jika Anda menentukan ekspresi kondisional sebagai $LatancySeconds > 30, pemutus sirkuit memeriksa jumlah total kejadian timeout yang berlangsung lebih dari 30 detik.

• errorThreshold: Ambang batas jumlah kejadian kesalahan tertentu.

• windowInSeconds: Jendela waktu selama jumlah kejadian timeout di backend diperiksa oleh pemutus sirkuit untuk menentukan apakah akan aktif. Nilai valid: 10 hingga 90. Unit: detik.

• openTimeoutSeconds: Periode waktu selama pemutus sirkuit tetap terbuka setelah aktif. Nilai valid: 15 hingga 300. Unit: detik.

• downgradeBackend: Opsional. Backend ke mana permintaan API diarahkan ketika pemutus sirkuit terbuka.

2.4 Kontrol status akurat

Layanan API Gateway diterapkan di beberapa node dalam kluster untuk memastikan ketersediaan tinggi dan performa. Secara default, node layanan yang berbeda secara independen menghitung dan menyimpan status pemutus sirkuit. Akibatnya, dari perspektif global, pemutus sirkuit mungkin memiliki ketidakakuratan status. Jika Anda memerlukan status pemutus sirkuit yang akurat, Anda dapat menambahkan bidang useGlobalState ke konfigurasi plugin. Contoh:

---
timeoutThreshold: 15 # Ambang batas jumlah kejadian timeout di backend.
windowInSeconds: 30 # Jendela waktu selama jumlah kejadian timeout di backend diperiksa oleh pemutus sirkuit untuk menentukan apakah akan aktif.
openTimeoutSeconds: 15 # Periode waktu selama pemutus sirkuit tetap terbuka setelah aktif.
useGlobalState: true # Kontrol status akurat diaktifkan.
downgradeBackend: # Backend ke mana permintaan API diarahkan ketika pemutus sirkuit terbuka.
 type: mock
 statusCode: 302
 body: |
 <result>
 <errorCode>I's a teapot</errorCode>
 </result>

Nilai default useGlobalState adalah false. Jika Anda mengaturnya ke true, status pemutus sirkuit yang akurat diperoleh dengan biaya hilangnya performa layanan hingga tingkat yang tidak mengganggu queries per second (QPS) dan service level agreement (SLA) yang dijanjikan untuk instance saat ini.

2.5 Tentukan bahwa pemutus sirkuit aktif setelah persentase permintaan di mana kesalahan tertentu terjadi dari semua permintaan dalam periode waktu tertentu mencapai ambang batas

API Gateway mengaktifkan pemutus sirkuit ketika salah satu dari kondisi berikut terpenuhi:

• errorThreshold: Ambang batas jumlah kejadian kesalahan tertentu di backend. Bidang ini digunakan bersama dengan ekspresi kondisional.

• timeoutThreshold: Ambang batas jumlah kejadian timeout di backend.

• errorThresholdByPercent: Ambang batas persentase jumlah permintaan di mana kesalahan tertentu terjadi dari total jumlah permintaan dalam jendela waktu.

• timeoutThresholdByPercent: Ambang batas persentase jumlah permintaan di mana timeout terjadi dari total jumlah permintaan dalam jendela waktu.

Kode berikut menunjukkan contohnya:

---
windowInSeconds: 3  # Jendela waktu selama pemutus sirkuit menentukan apakah akan aktif. Nilai valid: 10 hingga 90. Unit: detik.
openTimeoutSeconds: 3
errorThreshold: 90  # Ambang batas jumlah kejadian kesalahan tertentu.
timeoutThreshold: 90   # Ambang batas jumlah kejadian timeout.
errorThresholdByPercent: 20    # Ambang batas persentase permintaan di mana kesalahan tertentu terjadi dari total jumlah permintaan.
timeoutThresholdByPercent: 20   # Ambang batas persentase permintaan di mana timeout terjadi dari total jumlah permintaan.
errorCondition: "$StatusCode = 500"   # Kondisi kesalahan.
downgradeBackend:
  type: mock
  statusCode: 418
  body: |
    <result>
      <errorCode>I's a teapot</errorCode>
    </result>

2.6 Batasi permintaan saat pemutus sirkuit aktif

Segera setelah pemutus sirkuit aktif, konfigurasi pembatasan sementara ditambahkan ke API, dan semua trafik dibatasi berdasarkan konfigurasi ini saat pemutus sirkuit terbuka atau setengah terbuka. Contoh:

---
windowInSeconds: 1             # Jendela waktu di mana pemutus sirkuit memeriksa jumlah kejadian timeout di backend.
openTimeoutSeconds: 15          # Periode waktu selama pemutus sirkuit tetap terbuka setelah aktif.
errorThreshold: 3
errorCondition: "$LatencyMilliSeconds > 1"
downgradeTrafficLimit:               # Backend ke mana permintaan API diarahkan ketika pemutus sirkuit terbuka.
  limit: 2
  period: MINUTE

3. Konfigurasikan backend ke mana permintaan API diarahkan saat pemutus sirkuit terbuka

Anda dapat mengatur parameter downgradeBackend untuk menentukan backend ke mana permintaan API diarahkan saat pemutus sirkuit terbuka. Konfigurasi backend harus konsisten dengan file spesifikasi API yang diimpor ke API Gateway. Untuk informasi lebih lanjut, lihat Impor file Swagger untuk membuat API dengan ekstensi API Gateway. Anda dapat mengonfigurasi jenis backend berikut menggunakan sampel:

• HTTP

---
backend:
  type: HTTP
  address: "http://10.10.100.2:8000"
  path: "/users/{userId}"
  method: GET
  timeout: 7000        

• HTTP-VPC

---
backend:
  type: HTTP-VPC
  vpcAccessName: vpcAccess1
  path: "/users/{userId}"
  method: GET
  timeout: 10000        

• Function Compute

---
backend:
  type: FC
  fcRegion: cn-shanghai
  serviceName: fcService
  functionName: fcFunction
  arn: "acs:ram::111111111:role/aliyunapigatewayaccessingfcrole"        

• MOCK

---
backend:
  type: MOCK
  mockResult: "mock result sample"
  mockStatusCode: 200
  mockHeaders:
    - name: Content-Type
      value: text-plain
    - name: Content-Language
      value: zhCN

4. Kode kesalahan