バックエンドルーティングプラグインを設定する方法 - API Gateway

ルーティングタイプのプラグイン (バックエンドルーティングプラグインとも呼ばれます) は、リクエスト内のバックエンドサービスタイプ、URL、パス、およびパラメーターを変更することにより、API リクエストを異なるバックエンドサービス URL にルーティングするために使用されます。これらのプラグインは、マルチテナントルーティングおよびブルーグリーンリリースに使用できます。また、異なる環境を区別するためにも使用できます。

概要

バックエンドルーティングプラグインは、リクエスト内のバックエンドサービスタイプ、URL、パス、およびパラメーターを変更することにより、API リクエストを異なるバックエンドサービス URL にルーティングするために使用されます。これらのプラグインは、マルチテナントルーティングおよびブルーグリーンリリースに使用できます。また、異なる環境を区別するためにも使用できます。

1. 構成

1.1 構成テンプレート

JSON または YAML 形式でルーティングタイプのプラグインを構成できます。2 つの形式は同じスキーマを持ち、変換ツールを使用して相互に変換できます。次のコードスニペットは、ルーティングタイプのプラグインを構成するための YAML テンプレートです。

---
routes:
# 同じ呼び出し元からのリクエストを独立したバックエンドサービスアドレスにルーティングします。この例では、AppId が 123456 の呼び出し元からのリクエストは、アクセス承認名が slbAddressForVip である仮想プライベートクラウド (VPC) の CIDR ブロックに属するアドレスにルーティングされます。
- name: Vip
  condition: "$CaAppId = 123456"
  backend:
    type: "HTTP-VPC"
    vpcAccessName: "slbAccessForVip"
# 古いクライアントの場合、クライアントがサポートされなくなったことを示すレスポンスが返されます。ClientVersion は、API のカスタムパラメーターです。
- name: MockForOldClient
  condition: "$ClientVersion < '2.0.5'"
  backend: 
    type: "MOCK"
    statusCode: 400
    body: "This version is not supported!!!"

このテンプレートは、複数の route オブジェクトを含む routes オブジェクトを示しています。各 route オブジェクトは、ルーティングルールを指定するために使用されます。各ルーティングルールは、次の部分で構成されています。

名前: ルーティングルール名。名前は各プラグイン内で一意である必要があり、文字と数字を含めることができます。API リクエストがルールにヒットした場合、ルールの名前を含む HTTP ヘッダー X-Ca-Routing-Name が、リクエストがバックエンドにルーティングされる前にリクエストに追加されます。
条件: ルーティングルールの条件式。条件式の記述方法については、セクション 2.2 を参照してください。API リクエストが条件を満たす場合、リクエストはルーティングルールにヒットします。ルーティングタイプのプラグインは、構成されている順序に基づいてルーティングルールをチェックします。API リクエストは、リクエストがヒットした最初のルーティングルールのバックエンドにルーティングされます。その後、プラグインは残りのルーティングルールをチェックしません。複数のルーティングルールを構成する場合は、ビジネスの期待に沿った順序で構成されていることを確認してください。
バックエンド: バックエンドに関する情報。バックエンドの構成は、API Gateway の OpenAPI 仕様と一致している必要があります。ルーティングタイプのプラグインのバックエンド構成は、プラグインがバインドされている API のバックエンド構成をオーバーライドします。オーバーライド後にバックエンド構成が不完全な場合、次のメッセージがクライアントに返されます: X-Ca-Error-Code: I504RB。このメッセージが表示された場合は、バックエンド構成が完全かどうかを確認してください。詳細については、このトピックのセクション 1.3 を参照してください。
constant-parameters: ルーティングルールで構成できるカスタム定数パラメーター。定数パラメーターは、リクエストがバックエンドにルーティングされる前に API リクエストに添付されます。これらのパラメーターは、バックエンドのビジネスロジックで使用されます。location パラメーターは、header または query に設定できます。

1.2 条件式

1.2.1 構文

ルーティングタイプのプラグインの条件式の構文は、SQL 文の構文に似ています。基本的な形式は、$A = 'A' and '$B = 'B' です。
各パラメーターは $ で始まります。プラグインがバインドされている API で定義されているリクエストパラメーターを参照できます。API のリクエストモードは、MAPPING または PASSTHROUGH に設定できます。API を構成したときに query1 という名前のリクエストパラメーターを定義した場合、条件式でパラメーターを参照するために $query1 を使用できます。
次の定数パラメータータイプがサポートされています:
- STRING: 文字列データ型。一重引用符 (') または二重引用符 (") を使用して文字列を囲むことができます。例: "Hello"。
- INTEGER: 整数データ型。例: 1001 および -1。
- NUMBER: 浮動小数点データ型。例: 0.1 および 100.0。
- BOOLEAN: true または false。
and および or を使用して異なる式を接続できます。
括弧 () を使用して、条件式の優先順位を指定できます。
$CaAppId を使用して、API リクエストからシステムパラメーターを参照できます。API でシステムパラメーターを定義する必要はありません。ただし、システムパラメーターと同じ名前のパラメーターを API で定義している場合、システムパラメーターの値は API で定義されているパラメーターの値によって上書きされます。ルーティングタイプのプラグインでは、次のシステムパラメーターを参照できます:
- CaStage: リクエストされた API が公開される環境。有効な値: RELEASE、PRE、および TEST。
- CaDomain: リクエストされた API が属する API グループのドメイン名。
- CaRequestHandleTime: 現在のリクエストが受信された UTC 時刻。
- CaAppId: 現在のリクエストの AppId パラメーターの値。
- CaAppKey: 現在のリクエストの AppKey パラメーターの値。
- CaClientIp: 現在のリクエストが送信されたクライアントの IP アドレス。
- CaApiName: リクエストされた API の名前。
- CaHttpScheme: 現在のリクエストで使用されるプロトコル。有効な値: HTTP および HTTPS。
- CaClientUa: クライアントからアップロードされた UserAgent フィールド。
存在しないパラメーター (例: $UnknonwParameter = 1) を条件式で使用すると、式の結果は false になります。

1.2.2 例

次の式は、リクエストされた API がテスト環境に公開されていることを示しています。
$CaStage = 'TEST'
次の式は、カスタムパラメーター UserName を Admin として指定する必要があり、クライアントの IP アドレスは 47.47.XX.XX である必要があることを示しています。
$UserName = 'Admin' and $CaClientIp = '47.47.XX.XX'
次の式は、AppId パラメーターが 1001、1098、または 2011 に設定されており、API リクエストで使用されるプロトコルが HTTPS であることを示しています。
$CaHttpScheme = 'HTTPS' and ($CaAppId = 1001 or $CaAppId = 1098 or $CaAppId = 2011)

1.3 バックエンドの構成とオーバーライドルール

バックエンドの構成は、API Gateway にインポートされた Swagger ファイルと一致している必要があります。詳細については、「Swagger ファイルをインポートして API Gateway 拡張機能を使用して API を作成する」をご参照ください。次の例は、サポートされているバックエンドタイプと構成サンプルを示しています。ルーティングタイプのプラグインのバックエンド構成は、プラグインがバインドされている API のバックエンド構成をオーバーライドします。バックエンドタイプを変更する必要がない場合は、値を変更するパラメーターのみを指定します。

重要

バックエンドサービスの重み付けに基づいて API リクエストを分散する場合は、すべてのパラメーターを指定する必要があります。
Host ヘッダー構成の優先順位の詳細については、「Host ヘッダーを構成する」をご参照ください。
構成可能な最小タイムアウトは 300 ミリ秒です。このしきい値未満に設定された値は、デフォルトで 300 ミリ秒になります。

HTTP

---
backend:
  type: HTTP
  address: "http://10.10.100.2:8000"
  httpTargetHostName: "a.b.com" # リクエストは a.b.com に転送されます。この Host ヘッダー構成は、最も優先順位が高くなります。
  path: "/users/{userId}"
  method: GET
  timeout: 7000 # 構成可能な最小タイムアウトは 300 ミリ秒です。このしきい値未満に設定された値は、デフォルトで 300 ミリ秒になります。

HTTP-VPC

---
backend:
  type: HTTP-VPC
  vpcAccessName: vpcAccess1
  vpcTargetHostName: "a.b.com" # リクエストは a.b.com に転送されます。この Host ヘッダー構成は、最も優先順位が高くなります。
  vpcScheme: "https"
  path: "/users/{userId}"
  method: GET
  timeout: 10000 # 構成可能な最小タイムアウトは 300 ミリ秒です。このしきい値未満に設定された値は、デフォルトで 300 ミリ秒になります。

---
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

---
backend:
  type: OSS
  ossRegionId: cn-hangzhou
  bucketName: bucketName
  key: /objectName
  timeout: 10000 # 構成可能な最小タイムアウトは 300 ミリ秒です。このしきい値未満に設定された値は、デフォルトで 300 ミリ秒になります。
  action: putObject

MOCK

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

1.4 サービスの重み付けとリクエストの分散

バックエンドルーティングプラグインを使用すると、サービスの重み付けに基づいて API リクエストをバックエンドサービスに送信できます。重み付けが高いサービスには、より多くのリクエストが送信されます。次のコードは、構成例を示しています。

---
routes:
# 2 つのバックエンドサービスを構成し、処理能力に基づいて重み付けを割り当てます。重み付けが高いサービスには、より多くのリクエストが送信されます。
- name: Backend01
  condition: "1 = 1" # 1 = 1 は条件ヒットを示し、1 = 0 は条件ミスを示します。
  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"

重要

1 つの条件がヒットした場合、すべてのリクエストは条件にヒットしたサービスに送信されます。
複数の条件がヒットした場合、リクエストはサービスの重み付けに基づいて分散されます。
条件がヒットしない場合、すべてのリクエストは API で定義されているバックエンドサービスに送信されます。

1.5 制限

ルーティングタイプの各プラグインでは、最大 16,384 バイトのメタデータを構成できます。この制限を超えると、InvalidPluginData.TooLarge エラーが返されます。
ルーティングタイプのプラグインは、最大 160 のルートをサポートしています。この制限を超えると、InvalidPluginData.TooManyRoutes エラーが返されます。
各条件式には、最大 512 バイトのデータを含めることができます。この制限を超えると、InvalidPluginData.ConditionTooLong エラーが返されます。
ルーティングタイプのプラグインの構成更新は、プラグインがバインドされているすべての API にリアルタイムで同期されます。2 つの更新間の最小間隔は、45 秒です。最後の更新から 45 秒未満でプラグインを更新しようとすると、InvalidPluginData.UpdateTooBusy エラーが返されます。

2. 典型的なシナリオ

2.1 アプリケーション ID に基づいて API リクエストを異なるバックエンド URL にルーティングする

VIP 呼び出し元が使用する 2 つのアプリケーション ID (10098 と 10099) を提供し、これらのアプリケーション ID からの API リクエストを独立したサーバークラスターにルーティングするとします。次のコードは、構成例を示しています。

---
routes:
# API 呼び出し元の AppId 値が 10098 または 10099 の場合、API へのリクエストは独立した URL にルーティングされます。
# この例では、VPC アクセス名は slbAddressForVip に設定されています。
- name: Vip
  condition: "$CaAppId = 10098 or $CaAppId = 10099"
  backend:
    type: "HTTP-VPC"
    vpcAccessName: "slbAccessForVip"

2.2 同じ環境に公開されている API のすべてのリクエストを同じサーバーにルーティングする

テスト環境に公開されている API のすべてのリクエストをインターネット上のテストサーバーに転送するとします。次のコードは、構成例を示しています。

---
routes:
# テスト環境に公開されている API のすべてのリクエストをインターネット上のテストサーバーにルーティングします。
- name: Vip
  condition: "$CaStage = 'TEST'"
  backend:
    type: "HTTP"
    address: "https://test-env.foo.com"

2.3 ブルーグリーンリリースのルーティングを構成する

リクエストの 5% をベータサーバーアドレスのグループに転送し、リクエストの 95% を VPC タイプのバックエンドサービスに転送するとします。次のコードは、構成例を示しています。

---
routes:
# ブルーグリーンリリース: リクエストの 5% をブルーグリーンリリースバックエンドにルーティングし、リクエストの 95% を 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

説明

condition: 1 = 1 は条件ヒットを示し、1 = 0 は条件ミスを示します。
weight: バックエンドサービスの重み付けを指定するために使用されます。リクエストは、重み付けに基づいてサービスに送信されます。

2.4 一貫したハッシュベースのルーティング

一貫したハッシュアルゴリズムは、異なるハッシュファクターに基づいてリクエストをバックエンドサービスに均等に分散します。同じハッシュファクターを持つリクエストは、同じバックエンドサービスに分散されます。

バックエンドルーティングプラグインは、次のハッシュファクターをサポートしています。

送信元 IP アドレス: 送信元 IP アドレスに基づくハッシュ。同じ送信元 IP アドレスを持つリクエストは、同じバックエンドサーバーに分散されます。
パラメーター: リクエストパラメーターに基づくハッシュ。同じパラメーター構成を持つリクエストは、同じバックエンドサーバーに分散されます。

次のコードは、送信元 IP アドレスハッシュの例を示しています。

---
parameters:
  clientIp: "System:CaClientIp"  
routeByHash: clientIp # ハッシュファクターを指定します。
routes:
- name: route1
  condition: "1 = 1" # 1 = 1 は条件ヒットを示し、1 = 0 は条件ミスを示します。
  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"
  backend:
    type: "HTTP"
    address: "https://test.com"
  constant-parameters:
  - name: x-route-by-hash
    location: header
    value: "route-by-hash"