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

早期アクセス

カスタムタブは、すべてのユーザーに対して有効になっているわけではありません。お試しになりたい場合は、早期アクセスについてサポートチームにメールでお問い合わせください。

Qntrl Bridgeのカスタムタブでは、API、DB、SSH、PowerShell、ADなどの事前定義済みタブでは対応できない統合機能を拡張できます。これらの事前定義済みタブは、データベースやアプリケーションなどの標準システムへの接続に役立ちます。一方、カスタムタブでは、特定の業務や統合のニーズに合わせたJavaベースのロジックを作成して実行できます。

これらのタブは、Qntrl組織内で作成、設定、管理でき、他の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クラスについては、カスタムタブの種類セクションを参照してください。

• カスタムタブの実装で使用するメインクラスは、カスタムタブの種類（JAR、REST APIサービス、SOAPサービス）に応じて操作画面を拡張する必要があります。
  

• カスタムタブがレスポンスを返す必要がある場合は、JSONオブジェクトで返す必要があります。

カスタムタブの作成   

1. Qntrlの［カスタムタブ］ページで、［新しいカスタムタブ］をクリックします。
2. 次の詳細を入力します。

• ［サービス］：ドロップダウンからサービスを選択します。
• ［タブ名］：タブを識別する一意の名前を入力します。
• ［リンク名］：タブの識別子を入力します。この名前はBridgeでの参照に使用されます。
• ［種類］：カスタムタブのアプリケーションの種類を選択します。統合や自動化の要件に応じて、Bridgeでは次のカスタムタブの種類がサポートされています。
• JAR
• REST APIサービス
• SOAPサービス
• 認証情報タブ
• ［説明］：タブの目的を簡潔に説明します。
• ［メタ検証］：このチェックボックスを選択すると、JSONペイロード（メッセージを通じてタブを実行する際に使用）を検証できます。
• ［メインクラス名］：パッケージパスを含むクラス名（例：packageName.className）を入力します。
• ［添付ファイル］：SDK操作画面を使用して作成したJARを含むZIPファイルをアップロードします。

3. ［保存］をクリックします。

      

作成すると、カスタムタブがリストビューに表示されます。タブ名をクリックして詳細ページを開き、設定を管理します。

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

Bridgeでのタブの関連付けについて詳しくはこちら。

カスタムタブの設定 

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

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

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

タブの概要 

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

プロパティ

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

ソースファイル

• 必要に応じて、SDKから生成したJARファイルをアップロードします。

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

制限事項

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

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

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

メニュー設定

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

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

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

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

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

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

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

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

3. ［保存］をクリックしてウィジェットを作成します。

​

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

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

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

関連付けられたブリッジ  

このタブに関連付けられているブリッジが表示されます。

• 新しいJARが有効になると、関連付けられているブリッジに自動的にデプロイされます。

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

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

設定 

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

Task Meta   

Task Metaでは、JAR形式のカスタムタブで作成されるタスクのペイロード構造（JSONスキーマ）を定義します。これにより、実行時にBridgeへ渡されるすべての入力が適切に構造化、検証、書式設定されます。

Task Metaには、主に次の2つの用途があります。  

1. ペイロードの検証— 実行前に、受信ペイロードが定義済みのJSONスキーマに準拠しているかを検証します。必須項目がすべて含まれ、正しいデータ型（文字列、オブジェクト、数値など）に従っていることを確認することで、エラーを防ぎます。
2. フォームビルダー（UI生成）— Task Metaスキーマから項目の詳細を抽出して、フォームビルダーを自動的に構築します。これにより、ユーザーはJSONを手動で記述することなく、必要なタスクパラメーターを簡単に入力できます。

1. カスタムタブを開きます。
2. ［Task Meta］セクションに移動します。
3. ［Task Metaを作成］をクリックします。
4. 次の詳細を入力します。
1. 名前：Task Metaの一意の名前。
2. 説明：タスクの内容の簡単な説明。
5. スキーマの作成方法を1つ選択します。
1. ペイロード（自動生成）：サンプルペイロードがすでにある場合に使用します。
   
1. サンプルペイロードのJSONを入力し、［生成］をクリックします。
   
2. 右側のパネルに、構造に基づくJSONスキーマが自動生成されます。スキーマを確認し、［作成］をクリックして保存します。
3. この方法は、ペイロードの構造が分かっており、一貫性が必要な場合に適しています。
   

2. カスタム（手動でのスキーマ作成）：JSONスキーマを完全に制御したい場合や、定義済みのスキーマがすでにある場合に使用します。
   
1. JSONスキーマを直接入力するか、貼り付けます。
   
2. ［作成］をクリックして保存します。
   

Task Metaの管理

任意のTask Metaをクリックして詳細を開きます。

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

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

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

     

バージョンの制限：

1. 最大50件のバージョンを保存できます。
   
2. 51件目のバージョンを追加するには、古いバージョンを削除する必要があります。ただし、最新バージョンは削除できません。
   

Task Metaのサンプル

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

{
    '$schema': 'https://json-schema.org/draft/2020-12/schema#',
    '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の関連付け

カスタムタブを実行する前に、対象の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を拡張し、要求メソッドをオーバーライドする必要があります。

Javaクラスのサンプル

//$Id$
package ジルカー;

インポート org.json.JSONObject;

インポート com.zoho.qntrl.bridge.sdk.taskprocessors.TaskInterface;
インポート com.zoho.qntrl.bridge.service_sdk.util.ModuleInfo;
インポート 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() {
		
}
}

1. getModuleBasePath() -REST API URLの構成に使用するタブのベースパスを返します。
2. getServiceAuthenticatorClassInstance() - 認証クラスのインスタンスを返します。

1. basePath - コントローラーをベースパスにマッピングします。一意である必要があります。URLを使用して、コントローラーのグローバルメタデータを取得する方法を提供します。検証は行われません。同じベースパスが使用されている場合、rest タブ設定ファイルに追加され、先に返されたものが実行されます。
   

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サービス  

仕組み

• Bridgeサーバーにデプロイすると、SOAPサービスエンドポイントはメインクラスのgetEndpoint() メソッドから取得されます。
  

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

SOAPタブ設定ファイル

• SOAPタブの設定詳細は、soap_modules.xml ファイルに保存され、サーバー起動時に読み込まれます。
  

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

• Qntrlでタブが削除されると、対応するタブの詳細が設定ファイルから削除されます。

実装

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

SampleSoapServiceModule.java

インポート com.zoho.qntrl.bridge.sdk.タブ.soap.Endpoint;
インポート com.zoho.qntrl.bridge.sdk.タブ.soap.SoapServiceModule;

インポート java.util.Arrays;
インポート java.util.List;
インポート java.util.logging.Level;
インポート 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 タブ got removed');
}
} 

インポート javax.jws.WebMethod;
インポート javax.jws.WebService;

@WebService
public class SampleSoapService {

@WebMethod(operationName = 'SayHello')
public String sayHello(String name) {
return 'Hello ' + name + '..!';
}
}

4. 認証情報タブ

仕組み  

タスク実行中、Bridgeは認証情報タブを呼び出し、次の情報を渡します。

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

• 認証情報の種類– 想定される認証情報の種類（APIキー、SSH、JDBCなど）

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

実装  

認証情報タブの開発における、メインクラスでのCredentialModule インターフェイスの実装

オーバーライドメソッド

ZIPファイルの生成  

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

1. コンパイル済みのクラスファイルからタブのJARファイルをビルドします。

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

• サービス名

• タブ名

• リンク名

• メインクラス

3. JAR形式のカスタムタブパッケージと同様に、ZIPパッケージを作成します。

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

• 複数の認証情報で同じ認証情報タブを参照できます（例：同じボールトコネクター配下の複数のボールトシークレット）。

• 機密性の高い値（パスワード／トークン）は、ログを通じて公開される可能性があるため、タブコード内でログに出力しないでください。

カスタムタブのプロパティの表示／編集   

カスタムタブのプロパティを表示または更新するには、次の手順を実行します。

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

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

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

4. 必要な変更を行った後、変更を適用するには、［保存］をクリックします。
   

新しく追加したJARファイルがデフォルトでBridgeにデプロイされない場合は、［デプロイ］ボタンをクリックすると、強制的にデプロイして更新できます。

カスタムタブの削除   

Bridgeからカスタムタブを削除するには、次の手順を実行します。

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

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

3. 削除を確定します。