Tüm Ürünler
Search
Belge Merkezi

API Gateway:Devre kesici eklentileri (yalnızca özel örnekler için)

Son Güncelleme:Oct 04, 2026

Devre kesiciler, arka uç performansı düştüğünde sisteminizi korur. Özel örnekler için tetikleme koşullarını, açık kalma sürelerini ve yedek arka uçları yapılandırın.

Sınırlamalar

  • Yalnızca özel örneklerde kullanılabilir.

  • İfade başına maksimum 512 karakter.

  • Maksimum eklenti yapılandırma boyutu: 50 KB.

1. Genel Bakış

Varsayılan olarak, bir API arka ucunda 30 saniye içinde 1.000 zaman aşımı oluşursa devre kesici tetiklenir ve 90 saniye boyunca açık duruma geçer. Bu süre zarfında tüm istekler Status=503 durumu ve X-Ca-Error-Code=D503CB hata kodu ile döndürülür. 90 saniye sonra devre kesici yarı açık duruma geçer ve sınırlı sayıda isteğe izin verir. Arka uç kurtulduğunda devre kesici kapanır ve istekler normal şekilde devam eder.

Bir dedicated instance üzerinde circuit breaker plugin aşağıdaki circuit breaker ayarlarını özelleştirmenize olanak tanır:

  • Tetikleme koşulu: Belirli bir zaman penceresinde arka uç zaman aşımları veya belirtilen hatalar bir eşiği aştığında devre kesici tetiklenir.

  • Tetikleme koşullarının değerlendirildiği zaman penceresi.

  • Devre kesici tetiklendikten sonra açık kalma süresi.

  • Devre kesici açıkken isteklerin yönlendirileceği yedek arka uç.

2. Yapılandırmalar

Devre kesici eklenti yapılandırmaları yalnızca özel örneklerdeki API'ler için geçerlidir. Sunucusuz örneklerde, bir eklenti API'ye bağlansa bile varsayılan devre kesici yapılandırması kullanılır.

2,1 Arka uç zaman aşımlarına göre degradasyon ilkesi yapılandırma

Arka uç zaman aşımlarına dayalı bir degradasyon ilkesi yapılandırın. Bir istek, API tarafından tanımlanan zaman aşımı süresi içinde arka uç yanıt vermezse zaman aşımı olarak sayılır.

timeoutThreshold: 15         # The threshold of the number of occurrences of timeout at the backend.
windowInSeconds: 30          # The time window during which the number of occurrences of timeout at the backend is checked by the circuit breaker to determine whether to trip.
openTimeoutSeconds: 15       # The period of time during which the circuit breaker stays open after it trips.
downgradeBackend:            # The backend to which API requests are directed when the circuit breaker is open.
  type: mock
  statusCode: 418

Alanlar:

  • timeoutThreshold: Devre kesiciyi tetikleyen arka uç zaman aşımı sayısı. Maksimum değer: 5000. Çok küçük bir değer sık sık tetiklenmeye neden olur.

  • windowInSeconds: Değerlendirme zaman penceresi. Geçerli değerler: 10 ila 90. Birim: saniye.

  • openTimeoutSeconds: Devre kesicinin açık kaldığı süre. Geçerli değerler: 15 ila 300. Birim: saniye.

  • downgradeBackend: İsteğe bağlı. Devre kesici açıkken kullanılan yedek arka uç.

2,2 Arka uç yanıt süresine göre degradasyon ilkesi yapılandırma

Ağ geçidinin bir istek göndermesinden yanıt almasına kadar geçen süreyi ölçen arka uç yanıt süresine dayalı bir degradasyon ilkesi yapılandırın.

errorThreshold: 10         # The threshold of the number of occurrences of long response at the backend.
windowInSeconds: 60          # The time window during which the number of occurrences of long response at the backend is checked by the circuit breaker to determine whether to trip.
openTimeoutSeconds: 120        # The period of time during which the circuit breaker stays open after it trips.
errorCondition: "$LatencyMilliSeconds > 500"     # The conditional expression that is used to determine whether the backend response is counted as a long response. In this example, if the backend response time exceeds 500 ms, the response is considered as a long response.
downgradeBackend:               # The backend to which API requests are directed when the circuit breaker is open.
  type: mock
  statusCode: 403

Alanlar:

  • errorThreshold: Devre kesiciyi tetikleyen yavaş yanıt sayısı.

  • windowInSeconds: Değerlendirme zaman penceresi. Geçerli değerler: 10 ila 90. Birim: saniye.

  • openTimeoutSeconds: Devre kesicinin açık kaldığı süre. Geçerli değerler: 15 ila 300. Birim: saniye.

  • errorCondition: Yavaş bir yanıtı tanımlayan ifade. Kullanılabilir değişkenler: $LatencyMilliSeconds (milisaniye) ve $LatencySeconds (saniye).

  • downgradeBackend: İsteğe bağlı. Devre kesici açıkken kullanılan yedek arka uç.

2,3 Arka uç hatalarına göre degradasyon ilkesi yapılandırma

Arka uç hata kodlarına dayalı bir degradasyon ilkesi yapılandırın.

errorCondition: "$StatusCode == 503"  # The conditional expression that specifies the error whose number of occurrences is checked by the circuit breaker to determine whether to trip.
errorThreshold: 1000                  # The threshold of the number of occurrences of the specified error.
windowInSeconds: 30                   # The time window during which the number of occurrences of the specified error at the backend is checked by the circuit breaker to determine whether to trip.
openTimeoutSeconds: 15                # The period of time during which the circuit breaker stays open after it trips.
downgradeBackend:                     # The backend to which API requests are directed when the circuit breaker is open.
  type: "HTTP"
  address: "http://api.foo.com"
  path: "/system-busy.json"
  method: GET
  • errorCondition: Hata ifadesi. Kullanılabilir değişkenler: $StatusCode (yanıt kodu) ve $LatencySeconds (saniye cinsinden gecikme süresi).

    • Örneğin, $StatusCode = 503 or $StatusCode = 504 ifadesi, arka uç yanıtının durum kodu 503 veya 504 ise doğru olarak değerlendirilir.

    • Örneğin, $LatencySeconds > 30 ifadesi zaman aşımının 30 saniyeyi aştığını gösterir.

  • errorThreshold: Devre kesiciyi tetikleyen eşleşen hata sayısı.

  • windowsInSeconds: Değerlendirme zaman penceresi. Geçerli değerler: 10 ila 90. Birim: saniye.

  • openTimeoutSeconds: Devre kesicinin açık kaldığı süre. Geçerli değerler: 15 ila 300. Birim: saniye.

  • downgradeBackend: İsteğe bağlı. Devre kesici açıkken kullanılan yedek arka uç.

2,4 Hassas durum kontrolü

API Gateway birden çok küme düğümünde çalışır ve her düğüm kendi devre kesici durumunu tutar. Bu durum düğümler arasında durum tutarsızlığına neden olabilir. Küresel olarak tutarlı bir devre kesici durumu sağlamak için eklenti yapılandırmanıza useGlobalState alanını ekleyin:

---
timeoutThreshold: 15 # The threshold of the number of occurrences of timeout at the backend.
windowInSeconds: 30 # The time window during which the number of occurrences of timeout at the backend is checked by the circuit breaker to determine whether to trip.
openTimeoutSeconds: 15 # The period of time during which the circuit breaker stays open after it trips.
useGlobalState: true # Accurate status control is enabled.
downgradeBackend: # The backend to which API requests are directed when the circuit breaker is open.
 type: mock
 statusCode: 302
 body: |
 <result>
 <errorCode>I's a teapot</errorCode>
 </result>

useGlobalState varsayılan değeri false şeklindedir. Bu değeri true olarak ayarlamak, küçük bir performans yükü karşılığında hassas durumu etkinleştirir; bu durum örneğinizin garanti edilen QPS ve SLA değerlerini etkilemez.

2,5 Yüzdelik dilime göre degradasyon ilkesi yapılandırma

Aşağıdaki dört koşuldan herhangi biri karşılandığında devre kesici tetiklenir. Tüm koşulların önceliği eşittir.

  • errorThreshold: Devre kesiciyi tetikleyen arka uç hata sayısı (errorCondition ile eşleşen).

  • timeoutThreshold: Devre kesiciyi tetikleyen arka uç zaman aşımı sayısı.

  • errorThresholdByPercent: Önceki zaman penceresindeki hata oranına göre değerlendirilen hata oranı eşiği.

  • timeoutThresholdByPercent: Bir zaman penceresindeki toplam isteklerin yüzdesi olarak zaman aşımı oranı eşiği.

Örnek:

---
windowInSeconds: 3  # The time window during which the circuit breaker determines whether to trip. Valid values: 10 to 90. Unit: seconds.
openTimeoutSeconds: 3
errorThreshold: 90  # The threshold of the number of occurrences of the specified error.
timeoutThreshold: 90   # The threshold of the number of occurrences of timeout.
errorThresholdByPercent: 20    # The threshold of the percentage of requests in which the specified error occurs to the total number of requests.
timeoutThresholdByPercent: 20   # The threshold of the percentage of requests in which timeout occurs to the total number of requests.
errorCondition: "$StatusCode = 500"   # The error condition.
downgradeBackend:
  type: mock
  statusCode: 418
  body: |
    <result>
      <errorCode>I's a teapot</errorCode>
    </result>
Önemli
  • Yüzdelik eşiklerin etkili olması için bir zaman penceresinde en az 100 istek olmalıdır.

  • Bu örnekte, errorThreshold: 90 ve timeoutThreshold: 90 değerleri, bir zaman penceresinde hata veya zaman aşımı sayısı 90'ı aşarsa devre kesiciyi tetikler.

  • errorThresholdByPercent: 20 ve timeoutThresholdByPercent: 20 değerleri, önceki zaman penceresinde en az 100 istek varsa ve hata veya zaman aşımı oranı %20'yi aşarsa devre kesiciyi tetikler.

  • Yüzdelik tabanlı zaman aşımı ilkeleri Haziran 2023 sürümünden itibaren desteklenmektedir.

2,6 Devre kesici tetiklendiğinde istekleri kısıtlama

Devre kesici tetiklendiğinde, devre kesici açık veya yarı açık durumdayken tüm trafiğe geçici bir kısıtlama yapılandırması uygulanır:

---
windowInSeconds: 1             # The time window in which the circuit breaker checks the number of occurrences of timeout at the backend.
openTimeoutSeconds: 15          # The period of time during which the circuit breaker stays open after it trips.
errorThreshold: 3
errorCondition: "$LatencyMilliSeconds > 1"
downgradeTrafficLimit:               # The backend to which API requests are directed when the circuit breaker is open.
  limit: 2
  period: MINUTE

3. Yedek arka uç yapılandırması

Devre kesici açıkken bir yedek arka uç belirtmek için downgradeBackend kullanın. Arka uç yapılandırması, API Gateway'de kullanılan API teknik özellikler formatıyla eşleşmelidir (API Gateway uzantıları ile API'ler oluşturmak için Swagger dosyalarını içe aktarma). Aşağıdaki arka uç türleri desteklenir:

  • HTTP arka ucu

---
backend:
  type: HTTP
  address: "http://10.10.100.2:8000"
  path: "/users/{userId}"
  method: GET
  timeout: 7000        
  • HTTP arka ucu (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. Hata kodları


Hata kodu


HTTP durum kodu


Mesaj


Açıklama


D503BB


503


Backend circuit breaker busy


API, devre kesicisi tarafından korunmaktadır.


D503CB


503


Backend circuit breaker open, ${Reason}


Devre kesici açıktır. API çağrılarını yeniden test etmeden önce arka uç performansını kontrol edin.