外部サーバ接続の管理

このセクションでは、外部サーバの起動および停止方法と、現在のサーバ・アクティビティについての情報の取得方法について説明します。これには、管理ポータルを介してインタラクティブに実行する方法と、ObjectScript $system.external インタフェースを使用してプログラムによって実行する方法の 2 つがあります。

管理ポータルを使用した接続の制御

InterSystems 外部サーバの定義とは、構成設定の名前付きコレクションです。これらの設定を使用して、外部サーバ・プロセスを開始するコマンドが構築されます。例えば、定義には TCP/IP アドレス、ポート番号、およびクラスまたは実行可能ファイルへのパスなどの情報が含まれます。

管理ポータルには、定義済みのすべての外部サーバの現在のステータスを表示するページがあります。これにより、外部サーバを起動または停止したり、ゲートウェイ接続を制御および監視することが可能になります。以下にリストするすべての定義には、インストール時に構成された既定の設定が含まれています。これらの定義の変更または新しい定義の作成については、“外部サーバの定義のカスタマイズ” を参照してください。

Note:

既定では、すべてのサーバにゲートウェイ・リソースOpens in a new tabが必要です。これにより、サーバはパスフレーズでセキュリティ保護された接続で使用できるようになります。セキュリティが無効になっている場合を除き、ゲートウェイを開始および停止したり、ゲートウェイに接続するには、適切なリソースに対する USE 特権が必要です。Java、.NET、Python サーバには、%Gateway_Object リソースが必要です。詳細は、"承認ガイド" を参照してください。

[External Servers] ページ ([システム管理]→[構成]→[接続性])

List of currently defined external servers

[InterSystems External Servers] ページを開くには、システム管理 > 構成 > 接続性 > External Servers に移動します。この例で、すべての名前は、既定の外部サーバ構成であることを示す % で始まります (InterSystems IRIS インストール時に自動的に定義されます)。%Java Server、%Python Server、および %DotNet Server の定義は、このドキュメントで取り上げる言語の既定の外部サーバ構成です。その他のリストされている定義は、その他の InterSystems インタフェースによって内部で使用される特殊な構成です (関連するドキュメントで説明しています)。

Note:

%Java Server を %JDBC Server と混同しないでください。これは、その他の InterSystems インタフェースによって内部で使用される特殊な構成です。

表示されている各行は 1 つの一意の構成を識別するもので、それを使用する外部サーバを監視および制御することを可能にします。例えば、この行は既定の .NET 外部サーバ構成をリストします。

%DotNet_Server .NET 4115 Activity Log Start Stop Delete

この行には以下のフィールドが含まれます。

[Name] はこの構成設定のコレクションの一意の識別子です。それによって表される構成を使用できるのは、一度に 1 つの外部サーバ・インスタンスのみです。[Name] フィールドをクリックすると、構成のほとんどの値を変更できるエディタが表示されます (詳細は “外部サーバの定義のカスタマイズ” を参照してください)。
[Type] は、外部サーバが実行される言語を示しています。
[Port] は、この構成によって使用されるポート番号を表示します。2 つの異なる定義で同じポート番号を指定できますが、同時には使用できません。2 つのゲートウェイ接続で同じポートを同時に使用することはできません。
[Activity Log] は、InterSystems IRIS が開始されてから起動または停止されたこのサーバ定義のすべてのインスタンスについての詳細な情報を表示するページへのリンクです。$system.external インタフェースを使用して同じ情報を表示する方法は、次のセクションの “Activity Log の表示” を参照してください。
Start/Stop では、外部サーバ・プロセスが現在実行中であるかどうかを制御できます。[Start] は、外部サーバのインスタンスを作成し、そのプロセスについての詳細な起動情報を表示します。外部サーバが既に実行中である場合は、[Stop] コマンドが代わりに表示されます。$system.external インタフェースを使用してこれを実行する方法は、次のセクションの “外部サーバの起動および停止” を参照してください。
[Delete] では、外部サーバ定義を削除できます。$system.external インタフェースを使用して定義を作成および削除する方法は、“外部サーバ定義の作成と変更” を参照してください。

ほとんどの目的には既定の構成で十分ですが、追加の構成を定義すると便利な場合もあります。既存の定義を変更する方法または新しい定義を作成する方法は、“外部サーバの定義のカスタマイズ” を参照してください。

$system.external インタフェースを使用した接続の制御

このセクションでは、$system.external インタフェースを使用したゲートウェイ・プロセスの開始および停止、ゲートウェイ・サーバへの接続の管理、ゲートウェイのステータスに関する情報の取得の方法を説明します。

外部サーバの起動および停止

$system.external startServer() および stopServer() メソッドを使用すると、指定した外部サーバのインスタンスを開始または停止できます。 isServerRunning() は、指定した外部サーバが現在実行中であるかどうかを示すブーリアン値を返します。メソッド・シグニチャは以下のとおりです。

   startServer(serverName As %String) as %Boolean

   stopServer(serverName As %String, verbose As %Boolean = 0) as %Boolean

   isServerRunning(serverName As %String) as %Boolean

InterSystems 外部サーバは自動的に動作するよう設計されています。外部サーバは接続要求が受信されると起動し (既に実行中でない場合)、そのサーバを起動した InterSystems IRIS インスタンスがシャットダウンされると停止します。

Note:

通常、サーバはゲートウェイ・オブジェクトのインスタンスが作成されると起動されます。しかし、startServer() および stopServer() メソッドを使用すれば、ゲートウェイ・オブジェクトが存在しない場合でも外部サーバを制御できます (これは、以前のセクションの “管理ポータルを使用した接続の制御” で説明したように、管理ポータルの [開始]/[停止] リンクと同じように動作します)。

以下の例は、%Java Server のインスタンスが実行中であるかどうかをテストします。実行中でない場合は、外部サーバが起動され、返り値がチェックされて、起動が成功したことが確認されます。最後に、外部サーバが停止され、関連するアクティビティ・ログ・メッセージが表示されます。

サーバの起動および停止

この例は、既定の Java 構成である %Java Server を使用する外部サーバ・インスタンスを起動および停止します。isServerRunning() メソッドは、開始前にサーバが期待される状態であることを確認するために使用されます。

set serverName = "%Java Server"
set isRunning = $system.external.isServerRunning(serverName)
write isRunning

startServer() メソッドは、外部サーバの起動が成功した場合に (1) を返します。

if '(isRunning) set isRunning = $system.external.startServer(serverName)
write isRunning

stopServer() メソッドも、成功または失敗を示すブーリアン値を返します。verbose 引数が true に設定されている場合、コンソールには Activity Log メッセージも表示されます。

set isRunning = $system.external.stopServer(serverName,1)

   2020-06-24 13:09:39  Stopping Java Gateway Server '%Java Server'
   2020-06-24 13:09:39  Stopping process '89381' that is monitoring the Gateway 
   Server '%Java Server' on port '53180'
   2020-06-24 13:09:39  Shutting down the Gateway Server
   2020-06-24 13:09:39  Invoking %Connect with Server='127.0.0.1', Port='53180', 
   Namespace='USER', Timeout='5'
   2020-06-24 13:09:39  Shutting down Java Gateway Server '%Java Server'
   2020-06-24 13:09:39  Return from %Shutdown: OK
   2020-06-24 13:09:39  Gateway Server stopped

write isRunning

Activity Log のエントリは、次のセクションで説明するように後で取得することができます。

Activity Log の表示

getActivity() メソッドは、指定した InterSystems 外部サーバに対する一連の Activity Log エントリを返します。メソッド・シグニチャは以下のとおりです。

   getActivity(serverName As %String, entryCount As %Integer = 10, verbose As
   %Boolean = 0) as %Library.DynamicArray

管理ポータルの Activity Log インタフェースについては、“外部サーバの定義のトラブルシューティング” を参照してください。

各サーバは、サーバの状態についてのメッセージをログに記録します。getActivity() は、このログから指定された entryCount のメッセージ数を動的配列として返します。verbose が true である場合、現在のデバイスについてのメッセージも表示されます。

ダイナミック・オブジェクト・メソッド %ToJSON() を使用して、一度に設定のリスト全体を表示することができます。

Note:

%DynamicArrayOpens in a new tab クラスは、JSON 文字列およびデータ構造を直接操作できるようにする、いくつかの関連する ObjectScript 機能の 1 つです。詳細は、"JSON の使用" を参照してください。

JSON での getActivity()

以下の例では、最初の 3 つの Activity Log のエントリを取得し、%ToJSON() を使用してそれらを表示します (わかりやすくするために改行を追加しています)。

set activity = $system.external.getActivity("%Java Server",3)
write activity.%ToJSON()

   [{"DateTime":"2021-05-08 17:19:28","Job":"15037","Port":4013,"Server":"%Java Server",
   "Text":"Starting Java Gateway Server '%Java Server'","Type":"Info"},
   {"DateTime":"2021-05-08 17:19:28","Job":"15037","Port":4013,"Server":"%Java Server",
   "Text":"Return from RunStartCmd: ERROR #5001: Java executable not found in the given 
   directory: /nethome/bad/java/path/bin/","Type":"Error"},
   {"DateTime":"2021-05-08 17:19:28","Job":"15037","Port":4013,"Server":"%Java Server",
   "Text":"An error occurred while trying to start the Gateway Server","Type":"Info"}]

オプションで、verbose を true (1) に設定することで、ログの項目を現在のデバイス上に表示できます。

形式設定された表示での getActivity()

以下に、同じセットのログ・エントリを画面表示として示します。

set activity = $system.external.getActivity("%Java Server",3,1)

+--------------+-------+---------------------+--------+-------+-----------------------------+
| Server       | Port  | DateTime            | Type   | Job   | Text                        |
+--------------+-------+---------------------+--------+-------+-----------------------------+
| %Java Server | 4013  | 2021-05-08 17:19:28 | Info   | 15037 | Starting Java Gateway Serve |
|              |       |                     |        |       | r '%Java Server'            |
| %Java Server | 4013  | 2021-05-08 17:19:28 | Error  | 15037 | Return from RunStartCmd: ER |
|              |       |                     |        |       | ROR #5001: Java executable  |
|              |       |                     |        |       | not found in the given dire |
|              |       |                     |        |       | ctory: /nethome/bad/java/pa |
|              |       |                     |        |       | th/bin/                     |
| %Java Server | 4013  | 2021-05-08 17:19:28 | Info   | 15037 | An error occurred while try |
|              |       |                     |        |       | ing to start the Gateway Se |
|              |       |                     |        |       | rver                        |
+--------------+-------+---------------------+--------+-------+-----------------------------+

外部サーバの定義のカスタマイズ

外部言語の操作