カスタムモジュール

カスタムモジュール

お知らせ：当社は、お客様により充実したサポート情報を迅速に提供するため、本ページのコンテンツは機械翻訳を用いて日本語に翻訳しています。正確かつ最新のサポート情報をご覧いただくには、本内容の英語版を参照してください。

Alertエンタープライズ機能
カスタムモジュールはエンタープライズのお客さまのみ利用でき、要求に応じて提供されます。有効にするには、サポートチームにメールでお問い合わせください。

Qntrl Bridgeのカスタムモジュールを使用すると、API、DB、SSH、PowerShell、ADなどの定義済みモジュールを超えて連携機能を拡張できます。定義済みモジュールはデータベースやアプリケーションなどの標準システムへの接続に使用しますが、カスタムモジュールでは、特定のビジネス要件や連携要件に合わせたJavaベースのロジックを構築して実行できます。

これらのモジュールはQntrl組織内で作成、設定、管理でき、他のBridgeモジュールと同様にメッセージで実行できます。

これらは組織固有のモジュールであり、外部とは共有できません。同じ組織に関連付けられたBridgeからのみアクセスできます。

主な機能   

  • モジュール単位のプロパティ保存–クラウドとエージェントの両方のレベルで設定データを保存できます。

  • ウィジェットのサポート–クラウド環境とエージェント環境の両方で、ウィジェットを使用してクライアント固有の設定を収集できます。

  • タスクのメタデータと検証–ペイロードの構造を定義し、実行前にタスクの入力パラメーターを検証できます。


環境の設定   

  1. Qntrlの左パネルにある［設定］の歯車アイコン（⚙）をクリックします。
  2. ［詳細設定］→［Bridge］に移動し、［カスタムモジュール］を選択します。
  3. 画面右上の［SDKをダウンロード］をクリックし、カスタムモジュールの開発に使用するカスタムモジュールSDKをダウンロードしてインストールします。SDKにはJava 11が必要で、モジュールの開発を支援するライブラリーが含まれています。
  4. SDKをプロジェクトに組み込むには、SDKからダウンロードしたすべてのJARファイルをプロジェクトのクラスパスまたは参照ライブラリーに追加します。
  5. モジュールを開発してコードをコンパイルし、JARファイルを生成します。
  6. コンパイル済みのJARと依存するすべてのJAR（SDKのJARを除く）を、/libフォルダーを含むZIPファイルにまとめます。data-dictionary.xmlなどの設定ファイルも含めることができます。開発時に使用したSDKのJARは含めないでください。
このZIPファイルは、新しいカスタムモジュールの設定時に［ソースファイル］項目へ添付し、カスタムモジュールを作成する際に使用します。

Javaクラスのサンプルについては、カスタムモジュールの種類のセクションを参照してください。

Notes

  • カスタムモジュールの実装で使用するメインクラスは、カスタムモジュールの種類（JAR、REST APIサービス、SOAPサービス）に応じたインターフェースを拡張する必要があります。

  • カスタムモジュールから応答を返す場合は、JSONオブジェクトで返す必要があります。

カスタムモジュールの作成   

  1. Qntrlの［カスタムモジュール］ページで、［新しいカスタムモジュール］をクリックします。
  2. 次の詳細を入力します。
    • ［サービス］：ドロップダウンからサービスを選択します。
    • ［モジュール名］：モジュールを識別するための一意の名前を入力します。
    • ［リンク名］：モジュールの識別子を入力します。この名前はBridgeでの参照に使用されます。
    • ［種類］：カスタムモジュールのアプリケーションの種類を選択します。連携または自動化の要件に応じて、Bridgeでは次の種類のカスタムモジュールを利用できます。
      • JAR
      • REST APIサービス
      • SOAPサービス
      • 認証情報モジュール
    • ［説明］：モジュールの用途を簡潔に入力します。
    • ［メタデータの検証］：メッセージを通じてモジュールを実行する際に使用するJSONペイロードを検証するには、このチェックボックスを選択します。
    • ［メインクラス名］：パッケージパスを含むクラス名を入力します（例：packageName.className）。
    • ［添付ファイル］：SDKインターフェースを使用して作成したJARを含むZIPファイルをアップロードします。
  1. ［保存］をクリックします。
      
作成したカスタムモジュールは一覧表示に表示されます。モジュール名をクリックして詳細ページを開き、設定を管理できます。

Notesモジュールは、［Bridge］ページの［関連付けられたモジュール］セクションに、作成時に［メインクラス名］とJAR ZIPファイルの両方を指定した場合にのみ表示されます。




カスタムモジュールの設定 

モジュールのページには、主に次の3つのセクションがあります。

  • ［モジュールの概要］：モジュールの詳細とプロパティを表示、設定します。
  • ［設定］：モジュールに関連付けられた設定ウィジェットが表示されます。必要に応じて表示または更新できます。
  • ［タスクメタ］： JAR形式のモジュールで使用できます。受信したペイロードの検証やフォームビルダーの生成に使用するペイロードJSONを定義します。詳細については、タスクメタセクションを参照してください。

Notesタスクメタセクションは、モジュールの種類がJARに設定されている場合にのみ、カスタムモジュールのページに表示されます。

モジュールの概要 

選択したモジュールの［モジュールの概要］セクションをクリックします。選択したカスタムモジュールの詳細がこちらに表示され、プロパティを設定、管理できます。  

プロパティ

このセクションには、作成したモジュールの詳細とデプロイ済みのバージョンが表示されます。バージョンは必要に応じて更新できます。 

ソースファイル

  • 該当する場合は、SDKから生成したJARファイルをアップロードします。

  • アップロードしたJARは自動的に有効になります。

Notes

制限事項

  • 添付できるのは最大3件のZIPファイルです。

  • 一度に有効にできるのは1件のJARファイルのみです。

  • 新しいJARを有効にすると、それまで有効だったファイルは無効になり、新しいファイルが自動的にデプロイされます。


カスタムフォームを使用して、モジュール固有のプロパティを収集するウィジェットを作成します。これらのウィジェットは、Bridge AgentまたはQntrl Cloudの画面に設定可能なメニューとして表示されます。

新しいメニューウィジェットを作成するには、次の手順を実行します。

  1. ［新しい設定メニュー］をクリックします。

  2. 次の詳細を入力します。

    1. ［名前］：メニューの名前を入力します。

    2. ［場所］：メニューを表示する場所を選択します。

      1. ［Bridge Agent］– Bridge Agentの［設定］セクションに表示されます。

      2. ［Bridge Cloud］ – カスタムモジュールの［設定］タブに表示されます。

  1. ［保存］をクリックしてウィジェットを作成します。
作成したウィジェットが一覧に表示されます。名前をクリックしてエディターで開き、項目を設定または変更します。変更後、［公開］をクリックして変更を適用します。

Notes［公開］ボタンは、未公開の変更がある場合に緑色になります。

ウィジェットを管理するには、ウィジェット名にカーソルを合わせ、操作メニュー（⋮）をクリックし、［無効にする］または［削除］を選択します。

関連付けられているBridge  

このモジュールに関連付けられているBridgeが表示されます。

  • 新しいJARを有効にすると、関連付けられているBridgeに自動的にデプロイされます。

  • 自動的にデプロイされない場合は、［デプロイ］をクリックして、Bridgeを手動でデプロイ、更新します。


すべてのプロパティを設定した後、［保存］をクリックして変更を適用します。


設定 

［メニュー設定］セクションで［場所］として［Qntrl Cloud］を選択して作成したウィジェットが、設定用にこちらに表示されます。

タスクメタ   

タスクメタでは、JAR形式のカスタムモジュールで作成されたタスクのペイロード構造（JSONスキーマ）を定義します。これにより、実行時にBridgeへ渡されるすべての入力が適切に構造化、検証、書式設定されます。
タスクメタには、主に次の2つの目的があります。  
  1. ペイロードの検証—受信したペイロードが、実行前に定義済みのJSONスキーマに準拠しているかを検証します。すべての必須項目が含まれ、正しいデータ型（文字列、オブジェクト、数値など）であることを確認し、エラーを防止します。
  2. フォームビルダー（UI生成）—タスクメタのスキーマから項目の詳細を抽出し、フォームビルダーを自動生成します。これにより、JSONを手動で記述しなくても、必要なタスクパラメーターを簡単に入力できます。

各カスタムモジュールには複数のタスクを含めることができ、各タスクに個別のタスクメタ定義を設定できます。
タスクメタを作成するには。
  1. カスタムモジュールを開きます。
  2. ［タスクメタ］セクションに移動します。
  3. ［タスクメタを作成］をクリックします。
  4. 次の詳細を入力します。
    1. ［名前］：タスクメタを識別する一意の名前です。
    2. ［説明］：タスクの処理内容に関する簡単な説明です。
  5. 次のスキーマ作成方法のいずれかを選択します。
    1. ペイロード（自動生成）：サンプルのペイロードがすでにある場合は、この方法を使用します。
      1. サンプルのペイロードJSONを入力し、［生成］をクリックします。
      2. 右側のパネルに、ペイロードの構造に基づくJSONスキーマが自動生成されます。スキーマを確認し、［作成］をクリックして保存します。
      3. この方法は、ペイロードの構造が決まっており、一貫性を保つ必要がある場合に適しています。
    1. カスタム（スキーマの手動作成）：JSONスキーマを完全に制御する場合や、定義済みのスキーマがある場合は、この方法を使用します。
      1. JSONスキーマを直接入力するか、貼り付けます。
      2. ［作成］をクリックして保存します。


作成したすべてのタスクメタは、一覧に表示されます。

タスクメタの管理

任意のタスクメタをクリックして、詳細を開きます。

次の操作を実行できます。

  • 説明の編集：編集アイコンを使用して説明を変更します。
  • タスクメタの削除：上部の削除アイコンをクリックして、タスクメタ全体を削除します。

  • スキーマの編集：エディターセクションで、必要に応じてJSONスキーマを更新します。
  • バージョン：各タスクメタにはバージョン履歴が保持されます。更新するたびに新しいバージョンが作成されます。［バージョン］ドロップダウンを使用して、バージョンを切り替えます。
  • 現在のバージョンをダウンロード：現在のバージョンをダウンロードします。
  • 現在のバージョンを削除：現在選択されているバージョンを削除します。最新バージョンは検証に使用されるため、削除できません。
  • サンプルペイロード：［サンプルペイロード］ドロップダウンを使用して、スキーマから生成されたサンプルペイロードを表示します。これにより、Bridgeタスクに入力を送信する際の正しい形式を確認できます。
  • 変更が完了したら、［新しいバージョンとして保存］をクリックします。
     
Notes
バージョンには次の制限があります。
  1. 保存できるのは最大50件のバージョンです。
  2. 51件目のバージョンを追加するには、古いバージョンを削除する必要があります。ただし、最新バージョンは削除できません。

タスクメタのサンプル

以下は、SSHタスクのペイロードを定義するタスクメタのサンプルスキーマです。

{
    'type': 'object',
    'properties': {
          'task_name': {
              'type': 'string',
              'default' : 'ssh_task'
          },
          'credential': {
              'type': 'object',
              'properties': {
                    'name': {
                           'type': 'string'
                    }
             }
          },
          'task_details': {
              'type': 'object',
              'properties': {
                    'host': {
                        'type': 'string'
                    },
                    'command': {
                        'type': 'string'
                    }
              }
          }
        }
}

カスタムモジュールを実行するには 

1. カスタムモジュールとブリッジの関連付け

カスタムモジュールを実行する前に、対象のBridgeに関連付ける必要があります。関連付けると、カスタムモジュールのJARファイルが対象のBridgeに自動的にアップロードされます。

 
作成したカスタムモジュールをBridgeに関連付けるには
  1. Qntrlの左パネルで、［設定の歯車アイコン］（⚙）をクリックします。
  2. ［詳細設定］→［Bridge］に移動し、Bridgeを選択します。
  3. Bridgeの一覧ページで、カスタムモジュールを関連付けるBridgeの名前をクリックします。
  4. 選択したBridgeの詳細が表示されます。［モジュール］タブで、［モジュールを関連付ける］をクリックし、表示されたモジュールの一覧からBridgeに関連付けるカスタムモジュールの名前を選択します。
  5. ［保存］をクリックします。

これでカスタムモジュールがBridgeに関連付けられ、Bridge設定のモジュールセクションに表示されます。このBridge設定の更新を確定するには、もう一度［保存］をクリックします 。



2. カスタムモジュールの実行 

カスタムモジュールは、Bridgeのメッセージモジュールから実行します。

カスタムモジュールのタスクを実行するには

  1. Bridgeでメッセージを作成して実行する方法については、メッセージセクションを参照してください。
  2. 新しいメッセージの作成時に、［カスタムモジュール］を選択し、タスク一覧から適切なタスクを選択して実行します。
メッセージが正常に実行されると、次の処理が行われます。
  • 同期メッセージの場合、応答がすぐに表示されます。
  • Bridge Agent内のメッセージ一覧に、サーバー呼び出しエントリーが表示されます。

カスタムモジュールの種類  

1.  JAR 

カスタムモジュールのメインクラスでは、JarModuleインターフェイスを拡張し、requestメソッドをオーバーライドする必要があります。

Javaクラスのサンプル
 

//$Id$
package zylker;

import org.json.JSONObject;

import com.zoho.qntrl.bridge.sdk.taskprocessors.TaskInterface;
import com.zoho.qntrl.bridge.service_sdk.util.ModuleInfo;
import com.zoho.qntrl.bridge.service_sdk.util.TaskInfo;

public class SupplyMonitor implements TaskInterface {

@Override
public void executeTask(ModuleInfo moduleInfo, TaskInfo taskInfo) throws Exception {
JSONObject payload = taskInfo.getPayLoad();
int units = payload.getInt('units'), byteCount = payload.getInt('byteCount');
		
JSONObject result = new JSONObject();
result.put('load', byteCount * units);
taskInfo.setResponse(result);
}

@Override
public void clear() {
		
}
}


2.  REST APIサービス 

カスタムモジュールのREST APIサービス機能を使用すると、任意の形式で独自のREST APIモジュールを開発できます。展開すると、REST APIエンドポイントがBridgeサーバーで公開されます。

仕組み

  • Bridgeサーバーに展開すると、RestControllerおよびRequestDetailsアノテーションを使用してREST APIエンドポイントが取得されます。

  • URLは次の形式で構成されます。rest/{module_name}/{controller_path}/{request_path}。

  • URLの構成要素
    • モジュール名：メインクラスのgetModuleBasePath()関数から取得されます。
    • コントローラーのパス：RestControllerアノテーションから取得されるパスです。
    • リクエストパス：RestControllerアノテーションから取得されるパスです。
    • URLメソッド：RequestDetailsアノテーションから取得されます。
RESTモジュールの設定ファイル
  1. メソッドとパスの詳細は、サーバーの起動時に読み込まれるrest_modules.xmlファイルに追加されます。
  2. Qntrlで新しいバージョンに更新すると、設定ファイル内のURLが削除され、新しいバージョンから取得したURLに置き換えられます。
  3. Qntrlでモジュールを削除すると、そのモジュールの詳細が設定ファイルから削除されます。


実装

設定クラス
モジュールのベースパスと認証クラスのインスタンスを定義します。

実装するインターフェイス
com.zoho.qntrl.bridge.sdk.module.rest.RestServiceModule

オーバーライドするメソッド
  1. getModuleBasePath() -REST API URLの構成に使用するモジュールのベースパスを返します。
  2. getServiceAuthenticatorClassInstance() - 認証クラスのインスタンスを返します。

認証クラス

モジュールの認証方式を実装します。

実装するインターフェイス
com.zoho.qntrl.bridge.sdk.module.rest.RestServiceAuthenticator

オーバーライドするメソッド
  1. authenticate (HttpServletRequest, HttpServletResponse) - 実行されたAPIのリクエストインスタンスとレスポンスインスタンスを受け取ります。リクエストが認証済みで有効な場合は、対応するメソッドの実装が呼び出されます。それ以外の場合は、「ユーザーは承認されていません」というエラーメッセージを返します。
コントローラークラス


アクションロジックを実装します。次のアノテーションがサポートされています。

i) @RESTController（クラスアノテーション）：クラスをREST APIコントローラーとして指定します。エンティティとして指定することもできます。今後、OAuth 2ではスコープがコントローラーにマッピングされます。
フィールド
  1. basePath - コントローラーをベースパスにマッピングします。一意である必要があります。URLを使用してコントローラーのグローバルメタデータを取得できます。検証は行われません。同じベースパスが使用された場合はRESTモジュールの設定ファイルに追加され、先に返されたものが実行されます。
ii）@RequestDetails（メソッドアノテーション）。URLに対して呼び出すメソッドを識別します。URLのメソッドとパスは、これを使用して取得されます。
項目。
  1. method - 要求メソッド名を指定する必要があります（必須）。
  2. path- パスURLを指定します。コントローラーでベースパスが指定され、基本的なCRUD操作にはそれで十分なため、必須ではありません。
 

ZIPファイルの生成

ZIPファイルを生成するには、次の手順を実行します。

  1. 保存されたパラメーター名を含むクラスファイルを生成します。パラメーター名は、要求のパラメーターまたはヘッダーから値を取得するために使用されます。
  2. これらのクラスファイルを使用してJARファイルを作成し、そのJARファイルをZIP形式で圧縮します。
 

グローバル情報

次のエンドポイントを使用して、モジュールとコントローラーのグローバル情報を取得できます。

  1. モジュールの場合。
    1. エンドポイント：rest/{module_name}/_global_info
    2. モジュール内のすべてのパスとメソッドの詳細を返します。
  2. コントローラーの場合。
    1. エンドポイント：rest/{module_name}/{controller_path}/_global_info
    2. 対象のコントローラー内にあるすべてのパスとメソッドの詳細を返します。

   

3. SOAPサービス  

カスタムモジュールでSOAPサービスがサポートされているため、エンドユーザーは希望する形式で独自のSOAPサービス用カスタムモジュールを作成できます。導入すると、これらのSOAPサービスエンドポイントがBridgeサーバーで利用可能になります。

仕組み

  • Bridgeサーバーへの導入時に、SOAPサービスエンドポイントがメインクラスのgetEndpoint()メソッドから取得されます。

  • エンドポイントURLは/soapで始まる必要があります。

SOAPモジュールの設定ファイル。

    • SOAPモジュールの設定情報はsoap_modules.xmlファイルに保存され、サーバーの起動時に読み込まれます。

    • Qntrlで新しいバージョンに更新すると、設定ファイル内にあるモジュール関連の既存URLが削除され、新しいバージョンから取得したエンドポイントに置き換えられます。

    • Qntrlでモジュールを削除すると、対応するモジュールの詳細が設定ファイルから削除されます。


実装

SOAPサービスモジュールを作成するには、メインクラスにSoapServiceModuleインターフェースを実装する必要があります。以下は、メインクラスとSOAPエンドポイントの例です。

SampleSoapServiceModule.java

import com.zoho.qntrl.bridge.sdk.module.soap.Endpoint;
import com.zoho.qntrl.bridge.sdk.module.soap.SoapServiceModule;

import java.util.Arrays;
import java.util.List;
import java.util.logging.Level;
import java.util.logging.Logger;

public class SampleSoapServiceModule implements SoapServiceModule {

private static final Logger LOGGER = Logger.getLogger(SampleSoapServiceModule.class.getName());

@Override
public void serviceStarted(Endpoint endpoint) {
LOGGER.log(
Level.INFO,
'service {0} - {1} is started',
new Object[]{endpoint.getName(), endpoint.getUrlPattern()}
);
}

@Override
public List<Endpoint> getEndpoints() {
return Arrays.asList(
new Endpoint(
'SampleSoapService',
SampleSoapService.class.getName(),
'/soap/sample'
)
);
}

@Override
public void serviceStopped(Endpoint endpoint) {
LOGGER.log(
Level.INFO,
'service {0} - {1} is stopped',
new Object[]{endpoint.getName(), endpoint.getUrlPattern()}
);
}

@Override
public void moduleUnregistered() {
LOGGER.log(Level.INFO, 'sample soap service module got removed');
}
}

SampleSoapService.java
 
import javax.jws.WebMethod;
import javax.jws.WebService;

@WebService
public class SampleSoapService {

@WebMethod(operationName = 'SayHello')
public String sayHello(String name) {
return 'Hello ' + name + '..!';
}
}
SOAPサービスへのアクセス。
これらのクラスをコンパイルした後、JARファイルを作成してZIP形式で圧縮します。ZIPファイルをQntrlのカスタムモジュールにアップロードします。その後、BridgeでURL http[s]://{your_domain}/soap/sample?wsdlを使用してアクセスすると、このSOAPサービスのWSDLを確認できます。

4. 認証情報モジュール

認証情報モジュールを使用すると、実際のシークレットをQntrlやBridge内に保存することなく、タスクの実行時に外部の保管庫やシークレットストア（PAM360、Zoho Vault、社内保管庫など）から認証情報を動的かつ安全に取得できます。

導入後、このモジュールは認証情報モジュール内の次の項目で選択できます。
［アクセスタイプ］→［認証情報モジュール］。

仕組み  

タスクの実行時に、Bridgeは認証情報モジュールを呼び出し、次の情報を渡します。

  • 認証情報ID– 外部システムから取得するシークレット／レコードの識別子

  • 認証情報の種類– 必要な認証情報の種類（APIキー、SSH、JDBCなど）

モジュールが外部の保管庫に接続してシークレットを取得し、認証情報の詳細をBridgeに返します。その後、Bridgeは取得した認証情報を実行時に使用してタスクを実行します。

実装  

認証情報モジュールを開発するには、メインクラスにCredentialModuleインターフェースを実装します。

実装対象。
com.zoho.qntrl.bridge.sdk.module.credential.CredentialModule

オーバーライドするメソッド。

getCredential() - この関数は実行時に実行されます。Bridgeは、認証情報ID、認証情報の種類、ペイロードを引数として渡します。開発者はこれらの入力を処理し、外部システムから必要なシークレットを取得して、想定される形式で認証情報の詳細を返す必要があります。

ZIPファイルの生成  

デプロイ用のZIPファイルを生成するには。

  1. コンパイル済みのクラスファイルから、モジュールのJARファイルをビルドします。

  2. 次のような必要な設定情報を含めます。

    • サービス名

    • モジュール名

    • リンク名

    • メインクラス

  1. JAR形式のカスタムモジュールのパッケージ化と同様に、ZIPパッケージを作成します。

Notes

  • 外部ボールトから取得した認証情報の値は実行時にのみ使用され、Qntrlには保存されません。

  • 複数の認証情報で同じ認証情報モジュールを参照できます（例：同じボールトコネクターにある複数のボールトシークレット）。

  • ログから漏えいする可能性があるため、モジュールのコード内に機密情報（パスワードやトークン）を記録しないでください。

カスタムモジュールのプロパティの表示／編集

カスタムモジュールのプロパティを表示または更新するには。

  1. ［設定］（⚙）→［詳細設定］→［Bridge］に移動し、［カスタムモジュール］を選択します。

  2. モジュールの一覧ページで、編集するモジュールの名前をクリックします。

  3. モジュールの詳細ページが開き、プロパティを表示または変更できます。

  4. 必要な変更を行った後、変更内容を適用するには、［保存］をクリックします。
    Notes新しく追加したJARファイルが初期設定でBridgeにデプロイされない場合は、［デプロイ］ボタンをクリックすると、強制的にデプロイして更新できます。

    カスタムモジュールの削除

    Bridgeからカスタムモジュールを削除するには、

    1. ［設定］（⚙）→［詳細設定］→［Bridge］に移動し、［カスタムモジュール］を選択します。

    2. 削除するモジュールの名前にカーソルを合わせ、操作メニューをクリックして、［削除］を選択します。

    3. 削除操作を確定します。