API Gateway：Routing Belakang

Ikhtisar

Plugin routing belakang digunakan untuk merutekan permintaan API ke URL layanan belakang yang berbeda dengan mengubah jenis layanan belakang, URL, jalur, dan parameter dalam permintaan. Plugin ini mendukung routing multi-penyewa, rilis biru-hijau, serta pembedaan antar lingkungan.

1. Konfigurasi

1.1 Template konfigurasi

Anda dapat mengonfigurasi plugin tipe Routing dalam format JSON atau YAML. Kedua format tersebut memiliki skema yang sama dan dapat dikonversi satu sama lain menggunakan alat konversi. Potongan kode berikut adalah template YAML untuk mengonfigurasi plugin tipe Routing:

---
routes:
# Rute permintaan dari pemanggil yang sama ke alamat layanan belakang independen. Dalam contoh ini, permintaan dari pemanggil dengan AppId 123456 dirutekan ke alamat yang termasuk dalam blok CIDR virtual private cloud (VPC) yang nama otorisasi aksesnya adalah slbAddressForVip.
- name: Vip
  condition: "$CaAppId = 123456"
  backend:
    type: "HTTP-VPC"
    vpcAccessName: "slbAccessForVip"
# Untuk klien lama yang sudah tidak didukung, respons yang menunjukkan bahwa klien tidak lagi didukung dikembalikan. ClientVersion adalah parameter kustom dalam API.
- name: MockForOldClient
  condition: "$ClientVersion < '2.0.5'"
  backend: 
    type: "MOCK"
    statusCode: 400
    body: "Versi ini tidak didukung!!!"

Template ini menunjukkan objek routes yang berisi beberapa objek route. Setiap objek route digunakan untuk menentukan aturan routing. Setiap aturan routing terdiri dari bagian-bagian berikut:

• name: Nama aturan routing. Nama harus unik di setiap plugin dan dapat berisi huruf dan angka. Jika permintaan API memenuhi aturan, header HTTP X-Ca-Routing-Name yang berisi nama aturan ditambahkan ke permintaan sebelum dirutekan ke backend.

• condition: Ekspresi kondisional dari aturan routing. Untuk informasi tentang cara menulis ekspresi kondisional, lihat bagian 2.2. Jika permintaan API memenuhi kondisi, permintaan memenuhi aturan routing. Plugin tipe Routing memeriksa aturan routing berdasarkan urutan konfigurasinya. Permintaan API dirutekan ke backend pada aturan routing pertama yang dipenuhi oleh permintaan. Setelah itu, plugin tidak memeriksa aturan routing yang tersisa. Jika Anda mengonfigurasi beberapa aturan routing, pastikan mereka dikonfigurasi dalam urutan yang sesuai dengan harapan bisnis Anda.

• backend: Informasi tentang backend. Konfigurasi backend harus sesuai dengan spesifikasi OpenAPI dari API Gateway. Konfigurasi backend dalam plugin tipe Routing menggantikan konfigurasi backend dalam API yang terikat pada plugin. Jika konfigurasi backend tidak lengkap setelah penggantian, pesan berikut dikembalikan ke klien: X-Ca-Error-Code: I504RB. Jika Anda menerima pesan ini, periksa apakah konfigurasi backend lengkap. Untuk informasi lebih lanjut, lihat bagian 1.3 dari topik ini.

• constant-parameters: Parameter konstan kustom yang dapat Anda konfigurasikan dalam aturan routing. Parameter konstan dilampirkan ke permintaan API sebelum permintaan dirutekan ke backend. Parameter ini digunakan dalam logika bisnis backend. Parameter lokasi dapat diatur ke header atau query.

1.2 Ekspresi kondisional

1.2.1 Sintaksis

• Sintaksis ekspresi kondisional dalam plugin tipe Routing mirip dengan pernyataan SQL. Format dasarnya adalah $A = 'A' and '$B = 'B'.

• Setiap parameter dimulai dengan $. Anda dapat mereferensikan parameter permintaan yang didefinisikan dalam API yang terikat pada plugin. Mode permintaan API dapat diatur ke MAPPING atau PASSTHROUGH. Jika Anda mendefinisikan parameter permintaan bernama query1 saat mengonfigurasi API, Anda dapat menggunakan $query1 untuk mereferensikan parameter dalam ekspresi kondisional.

• Jenis parameter konstan berikut didukung:

  • STRING: Tipe data string. Tanda kutip tunggal (') atau tanda kutip ganda (") dapat digunakan untuk mengapit string. Contoh: "Halo".

  • INTEGER: Tipe data integer, seperti 1001 dan -1.

  • NUMBER: Tipe data floating-point, seperti 0,1 dan 100,0.

  • BOOLEAN: true atau false.

• Anda dapat menggunakan and dan or untuk menghubungkan ekspresi yang berbeda.

• Anda dapat menggunakan tanda kurung () untuk menentukan prioritas ekspresi kondisional.

• Anda dapat menggunakan $CaAppId untuk mereferensikan parameter sistem dari permintaan API. Anda tidak perlu mendefinisikan parameter sistem dalam API. Namun, jika Anda telah mendefinisikan parameter dalam API dengan nama yang sama dengan parameter sistem, nilai parameter sistem akan ditimpa oleh nilai parameter yang didefinisikan dalam API. Parameter sistem berikut dapat direferensikan dalam plugin tipe Routing:

  • CaStage: Lingkungan tempat API yang diminta diterbitkan. Nilai valid: RELEASE, PRE, dan TEST.

  • CaDomain: Nama domain grup API tempat API yang diminta milik.

  • CaRequestHandleTime: Waktu dalam UTC saat permintaan saat ini diterima.

  • CaAppId: Nilai parameter AppId dalam permintaan saat ini.

  • CaAppKey: Nilai parameter AppKey dalam permintaan saat ini.

  • CaClientIp: Alamat IP klien dari mana permintaan saat ini dikirim.

  • CaApiName: Nama API yang diminta.

  • CaHttpScheme: Protokol yang digunakan oleh permintaan saat ini. Nilai valid: HTTP dan HTTPS.

  • CaClientUa: Bidang UserAgent yang diunggah dari klien.

• Jika Anda menggunakan parameter yang tidak ada dalam ekspresi kondisional, seperti $UnknonwParameter = 1, hasil dari ekspresi adalah salah.

1.2.2 Contoh

• Ekspresi berikut menunjukkan bahwa API yang diminta diterbitkan ke lingkungan pengujian:

  $CaStage = 'TEST'

• Ekspresi berikut menunjukkan bahwa parameter kustom UserName harus ditentukan sebagai Admin dan alamat IP klien harus 47.47.XX.XX:

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

• Ekspresi berikut menunjukkan bahwa parameter AppId disetel ke 1001, 1098, atau 2011, dan protokol yang digunakan oleh permintaan API adalah HTTPS:

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

1.3 Konfigurasi backend dan aturan penggantian

Konfigurasi backend harus sesuai dengan file Swagger yang diimpor ke API Gateway. Untuk informasi lebih lanjut, lihat Impor file Swagger untuk membuat API dengan ekstensi API Gateway. Contoh berikut menunjukkan jenis backend yang didukung dan sampel konfigurasi. Konfigurasi backend dalam plugin tipe Routing menggantikan konfigurasi backend dalam API yang terikat pada plugin. Jika Anda tidak perlu mengubah jenis backend, tentukan hanya parameter yang nilainya ingin Anda ubah.

• HTTP

---
backend:
  type: HTTP
  address: "http://10.10.100.2:8000"
  httpTargetHostName: "a.b.com" # Permintaan diteruskan ke a.b.com. Konfigurasi header Host ini memiliki prioritas tertinggi.
  path: "/users/{userId}"
  method: GET
  timeout: 7000 # Timeout minimum yang dapat dikonfigurasi adalah 300 ms. Nilai apa pun yang diatur di bawah ambang batas ini akan default ke 300 ms.

• HTTP-VPC

---
backend:
  type: HTTP-VPC
  vpcAccessName: vpcAccess1
  vpcTargetHostName: "a.b.com" # Permintaan diteruskan ke a.b.com. Konfigurasi header Host ini memiliki prioritas tertinggi.
  vpcScheme: "https"
  path: "/users/{userId}"
  method: GET
  timeout: 10000 # Timeout minimum yang dapat dikonfigurasi adalah 300 ms. Nilai apa pun yang diatur di bawah ambang batas ini akan default ke 300 ms.

• FC

---
backend:
  type: FC
  fcRegion: cn-shanghai
  fcType: FCEvent
  serviceName: fcService
  functionName: fcFunction
  roleArn: "acs:ram::111111111:role/aliyunapigatewayaccessingfcrole"
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 # Timeout minimum yang dapat dikonfigurasi adalah 300 ms. Nilai apa pun yang diatur di bawah ambang batas ini akan default ke 300 ms.
  action: putObject

• MOCK

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

1.4 Bobot layanan dan distribusi permintaan

Plugin routing belakang memungkinkan Anda mengirim permintaan API ke layanan backend berdasarkan bobot layanan. Layanan yang memiliki bobot lebih tinggi dikirim lebih banyak permintaan. Kode berikut menunjukkan contoh konfigurasi:

---
routes:
# Konfigurasikan dua layanan backend dan tetapkan bobot berdasarkan kemampuan pemrosesan mereka. Layanan yang memiliki bobot lebih tinggi dikirim lebih banyak permintaan.
- name: Backend01
  condition: "1 = 1" # 1 = 1 menunjukkan kondisi terpenuhi, dan 1 = 0 menunjukkan kondisi tidak terpenuhi.
  weight: 100       # Digunakan untuk menentukan bobot layanan backend.
  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"

1.5 Batasan

• Untuk setiap plugin tipe Routing, Anda dapat mengonfigurasi maksimum 16,384 byte metadata. Jika batas ini terlampaui, kesalahan InvalidPluginData.TooLarge dikembalikan.

• Plugin tipe Routing mendukung maksimum 160 rute. Jika batas ini terlampaui, kesalahan InvalidPluginData.TooManyRoutes dikembalikan.

• Setiap ekspresi kondisional dapat berisi maksimum 512 bytes data. Jika batas ini terlampaui, kesalahan InvalidPluginData.ConditionTooLong dikembalikan.

• Pembaruan konfigurasi plugin tipe Routing disinkronkan secara real-time ke semua API yang terikat pada plugin. Interval minimum antara dua pembaruan adalah 45 seconds. Jika Anda mencoba memperbarui plugin dalam waktu kurang dari 45 detik setelah pembaruan terakhir, kesalahan InvalidPluginData.UpdateTooBusy dikembalikan.

2. Skenario tipikal

2.1 Rute permintaan API ke URL backend yang berbeda berdasarkan ID aplikasi

Anggaplah Anda menyediakan dua ID aplikasi untuk pemanggil VIP guna digunakan, 10098 dan 10099, dan Anda ingin merutekan permintaan API dari ID aplikasi ini ke kluster server independen. Kode berikut menunjukkan contoh konfigurasi:

---
routes:
# Jika nilai AppId untuk pemanggil API adalah 10098 atau 10099, permintaan ke API dirutekan ke URL independen.
# Dalam contoh ini, nama akses VPC diatur ke slbAddressForVip.
- name: Vip
  condition: "$CaAppId = 10098 or $CaAppId = 10099"
  backend:
    type: "HTTP-VPC"
    vpcAccessName: "slbAccessForVip"

2.2 Rute semua permintaan untuk API yang diterbitkan ke lingkungan yang sama ke server yang sama

Anggaplah Anda ingin semua permintaan untuk API yang diterbitkan ke lingkungan pengujian dialihkan ke server pengujian Anda di Internet. Kode berikut menunjukkan contoh konfigurasi:

---
routes:
# Rute semua permintaan untuk API yang diterbitkan ke Lingkungan Pengujian ke server pengujian di Internet.
- name: Vip
  condition: "$CaStage = 'TEST'"
  backend:
    type: "HTTP"
    address: "https://test-env.foo.com"

2.3 Konfigurasikan routing untuk rilis biru-hijau

Anggaplah Anda ingin mengalihkan 5% permintaan ke sekelompok alamat server beta, dan 95% permintaan ke layanan backend tipe VPC. Kode berikut menunjukkan contoh konfigurasi:

---
routes:
# Rilis biru-hijau: Rute 5% permintaan ke backend rilis biru-hijau, dan 95% permintaan ke layanan backend tipe VPC.
- 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