NGINX Plus と NGINX JavaScript モジュールを使用した API リクエストのバッチ処理

NGINX Plus R15でリリースされたNGINX JavaScript モジュールのバージョンでは、サブリクエストを発行できるようになりました。つまり、リクエストを JavaScript コードで開始できるということです。 これにより、まったく新しい一連のユースケースに対応できるようになります。

これらのユースケースの 1 つは、API リクエストをバッチ処理して、クライアントからの単一の API リクエストを一連のバックエンド サーバーへの複数の API リクエストに変換し、応答をクライアントへの単一の応答に集約することです。 このブログでは、例として e コマース サイトを使用しています。クライアントが特定の製品に関する情報を要求すると、カタログ、在庫、顧客レビューの 3 つのバックエンド サービスに対してサブ要求が行われます。

この投稿は、 NGINX Plus R15 の発表にあるサブリクエストの例に基づいており、サブリクエストを使用して同じリクエストを 2 つのバックエンド サーバーに送信し、最初の応答のみをクライアントに返す方法を示しています。

[編集者– この投稿は、NGINX JavaScript モジュールの使用例を探るいくつかの投稿のうちの 1 つです。 完全なリストについては、 「NGINX JavaScript モジュールの使用例」を参照してください。

投稿は、 js_インポート 指令は、 js_include 指令の NGINX プラス R23 そしてその後。 詳細については、 NGINX JavaScript モジュールのリファレンス ドキュメントを参照してください。構成例のセクションに、NGINX 構成と JavaScript ファイルの正しい構文が示されています。 ]

導入

この投稿の目的は、シンプルでわかりやすい API リクエストのバッチ処理の実例を提供することです。 例は、次の要件をすべて満たしています。

• すべてのリクエストに HTTP GETメソッドが使用されます。
• すべての応答は JSON 形式です。

• 次の 2 つのスタイルの API リクエストがサポートされています。

  • API プログラムへの引数は、URI の最後の要素です。これを最終要素リクエスト スタイルと呼びます。 この例では、 /batch-api/product/14286へのクライアント要求により、 /myapi/catalog/14286 、 /myapi/inventory/14286 、および/myapi/review/14286への要求が生成されます。
  • 引数は URI のクエリ文字列で識別されます。これをクエリ文字列リクエスト スタイルと呼びます。 この例では、 /batch-api2/product?item=14286へのリクエストにより、 /myapi/catalog.php?item=14286 、 /myapi/inventory.php?item=14286 、および/myapi/review.php?item=14286へのリクエストが生成されます。

  どちらのスタイルでも、クエリ文字列に追加の引数が含まれる可能性があることに注意してください。

• クライアント要求によってトリガーされるサブ要求のセットは動的に構成可能であるため、NGINX Plus 構成を手動で編集して再ロードしなくても変更できます。
• バックエンド サーバーへの API リクエストは互いに独立しています。

ソリューションの概要

このソリューションでは、NGINX JavaScript の新しいサブリクエスト機能を使用するだけでなく、NGINX Plus のキー値ストア機能も活用し、 NGINX Plus APIを使用して構成を動的に変更できるようにします。

次の図は、サポートされている 2 つのリクエスト スタイルを示しています。

最終要素のリクエストスタイル:

クエリ文字列リクエストのスタイル:

どちらの例でも、クライアントはカタログ、在庫、レビュー サービスから製品に関する情報を取得する必要があります。 URI の一部として、またはクエリ文字列でアイテム番号を渡して、NGINX Plus に 1 つのリクエストを送信します。 その後、リクエストは 3 つのサービスに送信され、応答はクライアントへの単一の応答に集約されます。

NGINX Plus でこれを動作させるには、 JavaScript プログラムとNGINX Plus 構成という 2 つのコンポーネントが必要です。

JavaScript プログラム

JavaScript 関数batchAPI() は、クライアント要求ごとに呼び出されます。 キー値ストアからカンマ区切りの API URI リストを取得し、それらを反復処理して、それぞれに対してサブリクエストを作成し、各応答を処理するコールバック関数done()を指定します。 最終要素スタイルのリクエストの場合、NGINX 変数$uri_suffixに格納されている URI の最後の要素が、元のクライアント URI 内の他のクエリ文字列引数とともに、各サブリクエストのクエリ文字列として渡されます。クエリ文字列スタイルのリクエストの場合、クライアント リクエストからのクエリ文字列が各サブリクエストのクエリ文字列として渡されます。

呼び出しはキー値ストアにリストされている順序で行われますが、非同期であるため、応答は任意の順序で返される可能性があります。 応答は、受信順にクライアントへの 1 つの応答に集約されます。 以下は JavaScript プログラムの最小バージョンです。

より広範なエラー処理、ログ記録、コメントを備えた JavaScript プログラムのバージョンは、GitHub Gist リポジトリでbatch-api.jsとして入手できます。

最小限のNGINX Plus構成

次の NGINX Plus 構成では、上流サーバーのグループを使用して、上で説明した 2 つのリクエスト スタイルを実装します。 簡単にするために、この構成では、アップストリーム サーバーが/myapi/ service / item# (最終要素スタイル) という形式の呼び出しを/myapi/ service .php/?item= item# (クエリ文字列スタイル) に変換できることを前提としています。これは、サンプル カタログ、インベントリ、およびレビュー サービスの言語である PHP の「ネイティブ」 URI 形式です。

変換自体を実行する、より広範な NGINX Plus 構成については、以下の「URI を変換するための NGINX 構成の拡張」を参照してください。

構成ファイルをセクションごとに見て、各部分の役割を説明しましょう。

• JavaScript ファイルをインポートします:

• URI の最後の要素が API プログラムへの引数を識別する API リクエストのリストを保持するキー値ストアを定義します。 キーは$uri_prefix変数を使用して、最後の/ の前の URI の部分をキャプチャします。

  NGINX Plus R16以降では、次の 2 つの追加のキー値機能を利用できます。

  • keyval_zoneディレクティブにタイムアウトパラメータを追加して、キー値ストア内のエントリの有効期限を設定します。 たとえば、バッチ処理された各 URI を毎日期限切れにするには、 timeout=1dを追加します。
  • syncパラメータをkeyval_zoneディレクティブに追加して、NGINX Plus インスタンスのクラスター全体でキー値ストアを同期します。 この場合、タイムアウトパラメータも含める必要があります。

  キー値ストアの同期を設定する手順については、 NGINX Plus 管理者ガイドを参照してください。

• 引数がクエリ文字列で識別される API 用に別のキー値ストアを定義します。 ここで、キー ( $uri ) はクエリ文字列を含まない URI 全体をキャプチャします。

• 引数が URI の最後の要素であるリクエストを受け入れる API に対して、URI を 2 つの部分に分割する 2 つのマップを定義します。 $uri_prefix変数は最後の / の前の URI 要素をキャプチャし、 $uri_suffix は最後の要素をキャプチャします。

• API サーバーのアップストリーム グループを定義します (ここでは、NGINX Plus とともに localhost 上で実行されています)。

• クライアント要求とサブ要求を処理する仮想サーバーを定義します。

• $batch_api_arg_in_uri変数をonに設定することでbatchAPI関数に指示される、最終要素スタイルを使用するクライアント要求を処理する場所を定義します。

• クエリ文字列スタイルを使用するクライアント要求を処理する場所を定義します。これは、 $batch_api_arg_in_uri変数をoffに設定することでbatchAPI関数に示されます。

• サブリクエストを処理する場所を定義します。

• NGINX Plus API を有効にして、データをキー値ストアで維持できるようにします。

完全な構成は次のとおりです。

バッチAPIリクエストの設定

NGINX Plus のキー値ストア機能を使用して、受信クライアント要求を一連の API 要求にマッピングして実行します。 前のセクションの構成では、2 つのリクエスト スタイルに対して個別のキー値ストアを定義します。

• 最終要素スタイルのキー値ストアはbatch_apiという名前で、キーは$uri_prefix変数です。この変数は、リクエスト URI の最後の/の前の要素をキャプチャします。
• クエリ文字列スタイルのキー値ストアはbatch_api2という名前で、キーは$uri変数です。この変数は、クエリ文字列のない完全なリクエスト URI をキャプチャします。

どちらのキー値ストアでも、各キーに関連付けられた値は、実行時に$batch_apiまたは$batch_api2変数で使用可能になる URI のコンマ区切りリストです。

最終要素スタイルのリクエストでは、 /batch-api/productへのクライアントリクエストを、 3 つのサービス/myapi/catalog 、 /myapi/inventory 、 /myapi/reviewへのリクエストにマッピングします。その結果、 /batch-api/product/14286へのリクエストは、 /myapi/catalog/14286 、 /myapi/product/14286 、 /myapi/review/14286へのリクエストになります。

これらのマッピングをbatch_apiキー値ストアに追加するには、ローカルマシンで実行されている NGINX Plus インスタンスに次のリクエストを送信します。

$ curl -iX POST -d '{"/batch-api/product":"/myapi/catalog,/myapi/inventory,/myapi/review"}' http://localhost/api/3/http/keyvals/batch_api

クエリ文字列スタイルのリクエストでは、 /batch-api2/productへのクライアントリクエストを、 3 つのサービス/myapi/catalog.php 、 /myapi/inventory.php 、 /myapi/review.phpへのリクエストにマッピングします。その結果、 /batch-api2/product?item=14286へのリクエストは、 /myapi/catalog?item=14286 、 /myapi/product?item=14286 、 /myapi/review?item=14286 へのリクエストになります。

これらのマッピングをbatch_api2キー値ストアに追加するには、次のリクエストを送信します。

$ curl -iX POST -d '{"/batch-api2/product":"/myapi/catalog.php,/myapi/inventory.php,/myapi/review.php"}' http://localhost/api/3/http/keyvals/batch_api2

例を実行する

同じ PHP ページが、両方のリクエスト スタイルで行われたリクエストを処理します。 簡単にするために、バックエンド サーバーが最終要素スタイルの URI ( /myapi/ service / item# ) をクエリ文字列スタイルの URI ( /myapi/ service .php?item= item# ) に変換できると想定します。 クエリ文字列スタイルの URI は PHP プログラムの「ネイティブ」な URI 形式であるため、変換する必要はありません。

すべてのサービスは、サービス名と項目引数を含む JSON 形式の応答を返します。 たとえば、 /myapi/catalog.php?item=14286のリクエストに対して、 catalog.phpから次の応答が返されます。

{"サービス":"カタログ","アイテム":"14286"}

これらの例で使用されている PHP プログラムでは応答にサービス名が含まれますが、すべてのサービスに当てはまるとは限りません。 応答を生成したサービスと一致させるために、JavaScript プログラムは集約された応答に URI を含めます。

たとえば、 /batch-api/product/14286のリクエストに対する集約された応答は次のようになります (ただし、3 つのコンポーネント応答の順序は異なる場合があります)。

[["/myapi/review/14286",{"service":"レビュー","item":"14286"}],["/myapi/inventory/14286",{"service":"インベントリ","item":"14286"}],["/myapi/catalog/14286",{"service":"カタログ","item":"14286"}]]

URI を変換するための NGINX Plus 設定の拡張

前述のように、上で説明した最小限の NGINX Plus 構成では、API サーバーが/myapi/ service / item#形式の URI を/myapi/ service .php/?item= item#に変換できることを前提としています。 以下の変更を加えることで、NGINX Plus 構成で翻訳を実装することもできます。

• サブリクエストを受信するための新しいアップストリーム グループを追加します。

• サービスアップストリーム グループによって受信された要求をリッスンするための新しい仮想サーバーを追加します。 クエリ文字列スタイルのリクエストを受信すると、URI にはすでに.php拡張子が付いているため、リクエストは単純にapi_serversアップストリーム グループにプロキシされます。 最終要素スタイルのリクエストを受信すると、URI は書き換えられ、URI の最後の要素が削除され、クエリ文字列引数に変換されます。

• /myapi の場所を変更して、新しいアップストリーム グループにプロキシします。

完全な構成は次のとおりです。

追加コンポーネント

サンプルの JavaScript プログラムと NGINX Plus 構成は他のスタイルの API に適応できますが、このブログ投稿の作成に使用されたすべてのコンポーネントを使用してテストする場合は、PHP ページを提供するための NGINX Unit 構成を含む、GitHub の Gist リポジトリで入手できます。

バッチAPI.js
カタログ.php
在庫.php
レビュー.php
ユニット構成

結論

これらの例は、API リクエストをバッチ処理し、集約された応答をクライアントに提供する方法を示しています。 NGINX Plus のキーバリューストアを使用すると、NGINX Plus APIを使用して API リクエストを動的に構成できます。API システムは正確な操作が非常に多岐にわたるため、この例には特定の API のニーズに合わせて多くの機能強化を加えることができます。

NGINX Open Sourceを使用して NGINX JavaScript サブリクエストのテストを開始できますが、API バッチ処理の例を試したり、キー値ストアやNGINX Plus APIなどの NGINX Plus 機能を活用するその他のユースケースをテストしたりする場合は、 30 日間の無料トライアルをリクエストして実験を開始してください。