API Gateway:バックエンドルーティングプラグイン

概要

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

1. 設定

1.1 設定テンプレート

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

---
routes:
# Route requests from the same caller to an independent backend service address. In this example, requests from the caller whose AppId is 123456 are routed to an address that belongs to the CIDR block of a virtual private cloud (VPC) whose access authorization name is slbAddressForVip.
- name: Vip
  condition: "$CaAppId = 123456"
  backend:
    type: "HTTP-VPC"
    vpcAccessName: "slbAccessForVip"
# For outdated clients, responses that indicate that the clients are no longer supported are returned. ClientVersion is a custom parameter in the API.
- name: MockForOldClient
  condition: "$ClientVersion < '2.0.5'"
  backend: 
    type: "MOCK"
    statusCode: 400
    body: "This version is not supported!!!"

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

• name: ルーティングルールの名前。 名前は各プラグイン内で一意である必要があり、英数字を使用できます。 APIリクエストがルールにヒットした場合、リクエストがバックエンドにルーティングされる前に、ルールの名前を含むHTTPヘッダーX-Ca-Routing-Nameがリクエストに追加されます。

• condition: ルーティングルールの条件式。 条件式の書き方については、セクション2.2を参照してください。 APIリクエストが条件を満たす場合、リクエストはルーティングルールにヒットします。 ルーティングタイプのプラグインは、設定された順序に基づいてルーティングルールをチェックします。 APIリクエストは、リクエストがヒットした最初のルーティングルールでバックエンドにルーティングされます。 その後、プラグインは残りのルーティングルールをチェックしません。 複数のルーティングルールを設定する場合は、ビジネスの期待に合った順序で設定されていることを確認してください。

• backend: バックエンドに関する情報。 バックエンドの構成は、API GatewayのOpenAPI仕様と一致している必要があります。 Routingタイプのプラグインのバックエンド設定は、プラグインがバインドされているAPIのバックエンド設定を上書きします。 オーバーライド後にバックエンドの設定が完了していない場合は、X-Ca-Error-Code: I504RBというメッセージがクライアントに返されます。 このメッセージを受信した場合は、バックエンド設定が完了しているかどうかを確認します。 詳細については、このトピックのセクション1.3を参照してください。

• constant-parameters: ルーティングルールで設定できるカスタム定数パラメーター。 リクエストがバックエンドにルーティングされる前に、APIリクエストに定数パラメーターがアタッチされます。 これらのパラメーターは、バックエンドのビジネスロジックで使用されます。 locationパラメーターは、headerまたはqueryに設定できます。

1.2 条件式

1.2.1 構文

• Routing型のプラグインの条件式の構文は、SQL文の構文と似ています。 基本フォーマットは、$A = 'A' および '$ B = 'B' である。

• 各パラメーターは $で始まります。 プラグインがバインドされているAPIに定義されているリクエストパラメーターを参照できます。 APIのリクエストモードは、MAPPINGまたはPASSTHROUGHに設定できます。 APIの設定時にquery1という名前のリクエストパラメーターを定義した場合、$query1を使用して条件式のパラメーターを参照できます。

• 次の定数パラメータタイプがサポートされています。

  • STRING: 文字列データ型。 一重引用符 (') または二重引用符 (") を使用して、文字列を囲むことができます。 例: "Hello" 。

  • INTEGER: 1001や-1などの整数データ型。

  • NUMBER: 0.1や100.0などの浮動小数点データ型。

  • BOOLEAN: trueまたはfalse。

• とまたはを使用して、異なる式を接続できます。

• () で条件式の優先度を指定できます。

• $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' および $CaClientIp = '47.47.XX. XX'

• 次の式は、AppIdパラメーターが1001、1098、または2011に設定され、APIリクエストで使用されるプロトコルがHTTPSであることを示しています。

  $CaHttpScheme = 'HTTPS' および ($CaAppId = 1001または $CaAppId = 1098または $CaAppId = 2011)

1.3 バックエンド設定とオーバーライド規則

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

• HTTP

---
backend:
  type: HTTP
  address: "http://10.10.100.2:8000"
  httpTargetHostName: "a.b.com" # Requests are forwarded to a.b.com. This Host header configuration has the highest priority.
  path: "/users/{userId}"
  method: GET
  timeout: 7000

• HTTP-VPC

---
backend:
  type: HTTP-VPC
  vpcAccessName: vpcAccess1
  vpcTargetHostName: "a.b.com" # Requests are forwarded to a.b.com. This Host header configuration has the highest priority.
  vpcScheme: "https"
  path: "/users/{userId}"
  method: GET
  timeout: 10000

• 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
  action: putObject

• モック

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

1.4 サービスの重みとリクエストの配分

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

---
routes:
# Configure two backend services and assign weights to them based on their processing capabilities. The service that has a higher weight is sent more requests.
- name: Backend01
  condition: "1 = 1" # 1 = 1 indicates a condition hit, and 1 = 0 indicates a condition miss.
  weight: 100       # Used to specify the weights of the backend services.
  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 制限事項

• ルーティングタイプの各プラグインに対して、最大16,384バイトのメタデータを設定できます。 この制限を超えると、InvalidPluginData.TooLargeエラーが返されます。

• ルーティングタイプのプラグインは、最大160のルートをサポートします。 この制限を超えると、InvalidPluginData.TooManyRoutesエラーが返されます。 このプラグインが共有インスタンスのAPIにバインドされている場合、最初の16ルートのみが有効になります。 このプラグインが専用インスタンスのAPIにバインドされている場合、すべてのルートが有効になります。

• 各条件式には、最大512バイトのデータを含めることができます。 この制限を超えると、InvalidPluginData.ConditionTooLongエラーが返されます。

• ルーティングタイプのプラグインの構成更新は、プラグインがバインドされているすべてのAPIにリアルタイムで同期されます。 2回の更新の最小間隔は45秒です。 最後の更新から45秒以内にプラグインを更新しようとすると、InvalidPluginData.UpdateTooBusyエラーが返されます。

2. 一般的なシナリオ

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

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

---
routes:
# If the AppId value for an API caller is 10098 or 10099, requests to the API are routed to an independent URL.
# In this example, the VPC access name is set to slbAddressForVip.
- name: Vip
  condition: "$CaAppId = 10098 or $CaAppId = 10099"
  backend:
    type: "HTTP-VPC"
    vpcAccessName: "slbAccessForVip"

2.2 同じ環境にパブリッシュされたAPIのすべてのリクエストを同じサーバーにルーティングする

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

---
routes:
# Route all requests for APIs that are published to the Test environment to the test server on the Internet.
- name: Vip
  condition: "$CaStage = 'TEST'"
  backend:
    type: "HTTP"
    address: "https://test-env.foo.com"

2.3 blue-greenリリースのルーティングの設定

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

---
routes:
# Blue-green release: Route 5% of requests to a blue-green release backend, and 95% of requests to a backend service of the VPC type. 
- 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