Tüm Ürünler
Search
Belge Merkezi

API Gateway:Backend routing

Son Güncelleme:Oct 04, 2026

Arka uç yönlendirme eklentisi (konsolda Yönlendirme türü olarak da bilinir), arayan kimliği, ortam, istemci IP adresi ve özel parametreler gibi istek niteliklerini değerlendirir ve her isteği uygun arka uç hizmetine yönlendirir. Bu eklentiyi çok kiracılı yönlendirme, mavi-yeşil dağıtımlar ve ortama dayalı trafik bölme senaryolarında kullanabilirsiniz.

Nasıl çalışır?

API Gateway, yönlendirme kurallarını sırayla değerlendirir. Koşulu istekle eşleşen ilk kural arka ucu belirler. Hiçbir kural eşleşmezse istek API'de tanımlanan varsayılan arka uca gider.

Her yönlendirme kuralı aşağıdakileri belirtir:

  • İsteğin eşleşmesi gereken bir condition

  • Eşleşen isteklerin yönlendirileceği bir backend

  • (İsteğe bağlı) Birden fazla eşleşen arka uç arasında trafiği dağıtmak için bir ağırlık

  • (İsteğe bağlı) İletimden önce isteğe eklemek için Constant parameters

Kullanım durumları


Senaryo


Nasıl çalışır?


Yapılandırma yaklaşımı


Çok kiracılı yönlendirme


VIP arayanları özel sunucu kümelerine yönlendirir.


Bir VPC arka ucuna yönlendirmek için $CaAppId değerini eşleştirin.


Ortama dayalı yönlendirme


Test aşamasındaki istekleri bir test sunucusuna yönlendirir.


Arka uç URL'sini geçersiz kılmak için $CaStage değerini eşleştirin.


Mavi-yeşil dağıtım


Trafiği kararlı ve yeni sürümler arasında böler.


1 = 1 koşullarıyla birden fazla rotaya ağırlık atayın.


Tutarlı karma


Aynı IP adresinden gelen veya aynı parametreye sahip istekleri tek bir arka uca sabitler.


Bir karma faktörüyle routeByHash ayarlayın.

Yapılandırma biçimi

Eklentiler JSON veya YAML kabul eder. Her iki biçim de aynı şemayı paylaşır ve birbirine dönüştürülebilir.

Aşağıdaki YAML şablonu temel yapıyı göstermektedir:

---
routes:
  # Route VIP callers to a dedicated VPC backend
  - name: Vip
    condition: "$CaAppId = 123456"
    backend:
      type: "HTTP-VPC"
      vpcAccessName: "slbAccessForVip"

  # Return a mock response for outdated clients
  - name: MockForOldClient
    condition: "$ClientVersion < '2.0.5'"
    backend:
      type: "MOCK"
      statusCode: 400
      body: "This version is not supported!!!"

Rota nesnesi


Alan


Zorunlu


Açıklama


name


Evet


Eklenti içinde benzersiz ad. Sadece harf ve rakam içerebilir. Bir istek bu kural ile eşleştiğinde API Gateway bu değere sahip bir X-Ca-Routing-Name başlığı ekler.


condition


Evet


Bir isteğin bu kural ile eşleşip eşleşmediğini belirleyen koşullu ifade. Kurallar sırayla değerlendirilir; ilk eşleşen kural geçerli olur.


backend


Evet


API'nin varsayılan arka ucunu geçersiz kılan arka uç yapılandırması. API Gateway OpenAPI teknik özelliklerine uygun olmalıdır. Eksik yapılandırma X-Ca-Error-Code: I504RB hatası döndürür.


constant-parameters


Hayır


İletimden önce isteğe eklenen özel sabit parametreler. Her parametre için name, location (header veya query) ve value gerekir.


weight


Hayır


Bu rota için trafik ağırlığı. Birden fazla rota eşleştiğinde kullanılır.

Koşullu ifadeler

Söz dizimi

Koşullu ifadeler SQL benzeri bir söz dizimi kullanır:

$ParamName = 'value' and $AnotherParam = 'value'

Kurallar:

  • Her parametrenin başına $ işaretini ekleyin. API'de tanımlanan herhangi bir istek parametresine (MAPPING veya PASSTHROUGH modunda) başvurun.

  • İfadeleri and ve or ile birleştirin. Önceliği kontrol etmek için parantez () kullanın.

  • Bir koşulda mevcut olmayan bir parametre false olarak değerlendirilir.

Desteklenen veri türleri:


Tür


Açıklama


Örnek


STRING


Tek veya çift tırnak içine alın


'Hello', "Hello"


INTEGER


Tamsayı değerleri


1001, -1


NUMBER


Ondalıklı sayı değerleri


0.1, 100.0


BOOLEAN


Boolean değerleri


true, false

Sistem parametreleri

Bu yerleşik parametrelere API'de tanımlanmadan başvurabilirsiniz. API aynı ada sahip bir parametre tanımlarsa API parametre değeri öncelik kazanır.


Parametre


Açıklama


Örnek değerler


$CaStage


API'nin dağıtım aşaması


RELEASE, PRE, TEST


$CaDomain


API grubunun alan adı


-


$CaRequestHandleTime


İsteğin alındığı zaman (UTC)


-


$CaAppId


Arayanın AppId değeri


10098


$CaAppKey


Arayanın AppKey değeri


-


$CaClientIp


İstemci IP adresi


47.47.XX.XX


$CaApiName


İstenen API'nin adı


-


$CaHttpScheme


İstek protokolü


HTTP, HTTPS


$CaClientUa


İstemci UserAgent dizesi


-

İfade örnekleri

Test aşamasında yayınlanan API'ler için istekleri yönlendirin:

$CaStage = 'TEST'

Belirli bir IP adresinden gelen belirli bir kullanıcıyı eşleştirin:

$UserName = 'Admin' and $CaClientIp = '47.47.XX.XX'

HTTPS üzerinden birden fazla AppId'yi eşleştirin:

$CaHttpScheme = 'HTTPS' and ($CaAppId = 1001 or $CaAppId = 1098 or $CaAppId = 2011)

Arka uç türleri

Bir yönlendirme kuralındaki arka uç yapılandırması bağlı API'nin varsayılan arka ucunu geçersiz kılar. Arka uç türünü değiştirmeden yalnızca belirli alanları değiştirmek için sadece geçersiz kılmak istediğiniz alanları belirtin. Arka uç yapılandırmaları API Gateway'e aktarılan Swagger dosyalarıyla tutarlı olmalıdır. Daha fazla bilgi için bkz. API Gateway uzantıları içeren Swagger dosyalarını aktarma.

Önemli

İstekleri ağırlığa göre dağıtmak için tüm arka uç parametrelerini belirtin. Host başlığı önceliği ayrıntıları için bkz. Host başlığını yapılandırma. Yapılandırılabilir minimum zaman aşımı 300 ms'dir. Bu eşiğin altındaki değerler varsayılan olarak 300 ms'ye ayarlanır.

Arka uç parametre referansı


Arka uç türü


Parametre


Açıklama


HTTP


address


Arka uç URL'si örn. http://10.10.100.2:8000


httpTargetHostName


Host başlığı geçersiz kılma (en yüksek öncelik)


path


İstek yolu örn. /users/{userId}


method


HTTP yöntemi örn. GET


timeout


Zaman aşımı milisaniye cinsinden (minimum 300 ms)


HTTP-VPC


vpcAccessName


VPC erişim yetkilendirme adı


vpcTargetHostName


Host başlığı geçersiz kılma (en yüksek öncelik)


vpcScheme


VPC arka ucu için protokol örn. https


path


İstek yolu


method


HTTP yöntemi


timeout


Zaman aşımı milisaniye cinsinden (minimum 300 ms)


FC


fcRegion


Function Compute bölgesi örn. cn-shanghai


fcType


Tetikleyici türü: FCEvent veya HttpTrigger


serviceName


FC hizmet adı (FCEvent)


functionName


FC işlev adı (FCEvent)


fcUrl


İşlev URL'si (HttpTrigger)


roleArn


API Gateway'in FC'ye erişmesi için RAM rolü ARN'si


method


HTTP yöntemi (yalnızca HttpTrigger)


OSS


ossRegionId


Object Storage Service (OSS) bölgesi örn. cn-hangzhou


bucketName


OSS paket adı


key


Nesne anahtarı örn. /objectName


timeout


Zaman aşımı milisaniye cinsinden (minimum 300 ms)


action


OSS işlemi örn. putObject


MOCK


mockResult


Mock yanıt gövdesi


mockStatusCode


Mock yanıtı için HTTP durum kodu


mockHeaders


Yanıt başlıkları dizisi (her biri name ve value içerir)

Yapılandırma örnekleri

HTTP

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

HTTP-VPC

---
backend:
  type: HTTP-VPC
  vpcAccessName: vpcAccess1
  vpcTargetHostName: "a.b.com"
  vpcScheme: "https"
  path: "/users/{userId}"
  method: GET
  timeout: 10000

Function Compute (FCEvent)

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

Function Compute (HttpTrigger)

---
backend:
  type: FC
  fcRegion: cn-shenzhen
  method: GET
  fcType: HttpTrigger
  fcUrl: https://1833848375796824.cn-shenzhen.fc.aliyuncs.com/2016-08-15/proxy/servicetest/fctest3/fctest3
  roleArn: acs:ram::1833848375796824:role/aliyunapigatewayaccessingfcrole

OSS

---
backend:
  type: OSS
  ossRegionId: cn-hangzhou
  bucketName: bucketName
  key: /objectName
  timeout: 10000
  action: putObject

MOCK

---
backend:
  type: MOCK
  mockResult: "mock resul sample"
  mockStatusCode: 200
  mockHeaders:
    - name: server
      value: mock
    - name: proxy
      value: GW

Ağırlıklı trafik dağıtımı

Trafiği orantılı olarak dağıtmak için rotalara ağırlık atayabilirsiniz. Daha yüksek ağırlığa sahip rotalar daha fazla istek alır.

---
routes:
  - name: Backend01
    condition: "1 = 1"   # Always matches
    weight: 100
    backend:
      type: "HTTP"
      address: "https://test01.com"
      path: "/web/cloudapi"
  - name: Backend02
    condition: "1 = 1"
    weight: 80
    backend:
      type: "HTTP"
      address: "https://test02.com"
      path: "/web/cloudapi"

Trafik dağıtım kuralları:


Koşul


Davranış


Bir rota eşleşir


Tüm istekler o rotanın arka ucuna gider.


Birden fazla rota eşleşir


İstekler ağırlığa göre orantılı olarak dağıtılır.


Hiçbir rota eşleşmez


İstekler API'nin varsayılan arka ucuna gider.

Önemli

Ağırlığa dayalı dağıtım her rotada tüm arka uç parametrelerinin belirtilmesini gerektirir.

Tutarlı karma

Tutarlı karma bir karma faktörüne göre istekleri dağıtır. Aynı karma faktörüne sahip istekler her zaman aynı arka uca ulaşır.

Desteklenen karma faktörleri:


Karma faktörü


Açıklama


Kaynak IP adresi


Aynı istemci IP adresinden gelen istekler aynı arka uca gider.


İstek parametresi


Aynı parametre değerine sahip istekler aynı arka uca gider.

Örnek: kaynak IP karma

---
parameters:
  clientIp: "System:CaClientIp"
routeByHash: clientIp
routes:
  - name: route1
    condition: "1 = 1"
    backend:
      type: "MOCK"
      statusCode: 200
      mockResult: "Hello World!!!"
  - name: route2
    condition: "1 = 1"
    backend:
      type: "MOCK"
      statusCode: 400
      mockResult: "mock resul sample"
  - name: route3
    condition: "1 = 0"   # Never matches
    backend:
      type: "HTTP"
      address: "https://test.com"
    constant-parameters:
      - name: x-route-by-hash
        location: header
        value: "route-by-hash"

Bu örnekte parameters clientIp değerini sistem parametresi CaClientIp ile eşler. routeByHash alanı karma faktörü olarak clientIp değerini seçer. Aynı istemci IP adresinden gelen istekler eşleşen rotalar arasında tutarlı bir şekilde aynı arka uca yönlendirilir.

Yönlendirme senaryoları

Uygulama Kimliğine göre yönlendirme

VIP arayanları (AppId 10098 veya 10099) özel bir sanal özel bulut (VPC) arka ucuna yönlendirin:

---
routes:
  - name: Vip
    condition: "$CaAppId = 10098 or $CaAppId = 10099"
    backend:
      type: "HTTP-VPC"
      vpcAccessName: "slbAccessForVip"

Ortama göre yönlendirme

Tüm test aşaması isteklerini genel bir test sunucusuna gönderin:

---
routes:
  - name: Vip
    condition: "$CaStage = 'TEST'"
    backend:
      type: "HTTP"
      address: "https://test-env.foo.com"

Mavi-yeşil dağıtım

Trafiği bir beta sunucusu ve bir VPC üretim arka ucu arasında %5/%95 oranında bölün:

---
routes:
  - name: BlueGreenPercent05
    condition: "1 = 1"
    weight: 5
    backend:
      type: "HTTP"
      address: "https://beta-version.api.foo.com"
      path: "/web/cloudapi"
    constant-parameters:
      - name: x-route-blue-green
        location: header
        value: "route-blue-green"
  - name: BlueGreenPercent95
    condition: "1 = 1"
    weight: 95
    backend:
      type: HTTP-VPC
      path: "/web/cloudapi"
      vpcAccessName: testvpc
condition: "1 = 1" her zaman eşleşir. condition: "1 = 0" asla eşleşmez. Eşleşen rotalar arasındaki trafik dağıtımını kontrol etmek için weight kullanın.

Sınırlamalar


Kısıtlama


Limit


Hata kodu


Eklenti meta veri boyutu


16.384 bayt


InvalidPluginData.TooLarge


Eklenti başına rota sayısı


160


InvalidPluginData.TooManyRoutes


Koşullu ifade boyutu


512 bayt


InvalidPluginData.ConditionTooLong


Minimum güncelleme aralığı


45 saniye


InvalidPluginData.UpdateTooBusy