z/OS Connect メッセージ・ペイロード変換の定義

IBM® z/OS® Connect には、z/OS オペレーティング・システム上のビジネス・アセットの呼び出しに使用される要求および応答のペイロードをオプションで変換する機能があります。 z/OS Connect に含まれる com.ibm.wsspi.zos.connect.DataXform サービス・プロバイダー・インターフェース (SPI) を実装することで、特定のニーズを満たすメッセージ・ペイロード変換プログラムを作成することができます。

このタスクについて

要求および応答のメッセージ・フォーマットが JSON であることを要求する実装を z/OS Connect は提供します。 このフィーチャーは、ネイティブ言語の COBOL、PL/I、または C の構造によってマップ可能なバイト配列への要求の変換をサポートします。 ターゲット・プログラムのこの言語構造またはコピーブック (in パラメーターと out パラメーターの記述を含む) を使用して、z/OS Connect 提供のユーティリティーにより、バインディング・ファイルと、JSON 要求および応答スキーマ・ファイルを生成します。 z/OS Connect は、このユーティリティーで生成されるバインディング・ファイルを使用して、 要求が到着したときや応答が戻されるときに、JSON とネイティブ・データ形式の間で相互にデータ変換を行います。 要求および応答メッセージの JSON スキーマは、z/OS Connect 提供の REST API 呼び出しで取得できます。

z/OS Connect では、 特定サービスに適用される属性のセットを管理者が構成するための zosConnectService 構成エレメントが用意されています。 これらの属性の 1 つとして、dataXformRef があります。 これは、特定サービスに対して使用されるデータ変換構成を指します。 このタスクでは、z/OS Connect 提供のデータ変換プログラムを使用するように要求する方法について説明します。

手順

  1. server.xml ファイル内に zosConnectDataXform エレメントを定義します。
    <!-- z/OS Connect data transformation provider --> 
    <zosConnectDataXform id="zosConnectXform"
    	bindFileLoc="/zosConnect/banking/bind/"
            bindFileSuffix=".bnd"   
            requestSchemaLoc="/zosConnect/banking/reqSchema"
            requestSchemaSuffix=".json"
    	responseSchemaLoc="/zosConnect/banking/respSchema" 
            responseSchemaSuffix=".json"/>  

    この例では完全性のために、bindFileLocrequestSchemaLoc、および responseSchemaLoc など、ファイル・ロケーションに関するすべての属性定義が指定されています。必須の属性定義は、bindFileLocrequestSchemaLoc のみです。responseSchemaLoc 属性が構成されていない場合は requestSchemaLoc 属性の値が使用されます。

    同じ例では完全性のために、<bindFileSuffix><requestSchemaSuffix>、および <responseSchemaSuffix> など、サフィックスに関する属性定義もすべて指定されています。これらはすべてオプションです。 これらが指定されていない場合、z/OS Connect によってロードされるバインド・ファイルおよびスキーマ・ファイルにはサフィックスが付いていないと想定されます。

    z/OS Connect は、データ変換に関連するファイルは、構成に基づいた特定のフォーマットであると予期します。
    • バインド・ファイル: <serviceName><bindFileSuffix>
    • 要求スキーマ・ファイル: <serviceName>_request<requestSchemaSuffix>
    • 応答スキーマ・ファイル: <serviceName>_response<requestSchemaSuffix>
    以下の zosConnectService サンプル構成および前の zosConnectDataXform サンプル構成を使用するとします。
    <!-- z/OS Connect service definition --> 
    <zosConnectService id="zosConnectCustomer" 
    	serviceName="customer" 
    	serviceRef="wolaCustomerCreate" 
    	dataXformRef="zosConnectXform"/> 
    データ変換ファイルの名前は次のようになります。
    • バインド・ファイル: customer.bnd
    • 要求スキーマ・ファイル: customer_request.json
    • 応答スキーマ・ファイル: customer_response.json

    zosConnectDataXform エレメントに関連する構成可能な属性定義について詳しくは、z/OS Connect フィーチャーの資料を参照してください。

  2. z/OS Connect 提供のデータ変換を可能にする、server.xml 構成内の各サービスについて、 zosConnectService エレメントを更新します。
    <!-- z/OS Connect service definition --> 
    <zosConnectService id="zosConnectCustomer" 
    	serviceName="customer" 
    	serviceRef="wolaCustomerCreate" 
    	dataXformRef="zosConnectXform"/> 
  3. オプション: すべてのサービスに適用されるデータ変換プログラムを構成します。 zosConnectManager エレメントの globaDataXformRef をグローバル使用のための構成済みデータ変換プログラム ID に設定します。 グローバルとサービスの両方のデータ変換プログラムが定義され、 データ変換プログラムが構成されたサービスについて要求が着信した場合、 z/OS Connect は、そのサービス用に特に構成されたデータ変換プログラムを使用します。
    <zosConnectManager id="zosConnectGlobalDefinitions
            globalDataXformRef="zosConnectGlobalDataXform"/>   
    
    <!-- z/OS Connect data transformation provider --> 
    <zosConnectDataXform id="globalDataXform" 
    	bindFileLoc="/zosConnect/banking/bind/"
            bindFileSuffix=".bnd"   
            requestSchemaLoc="/zosConnect/banking/reqSchema"
            requestSchemaSuffix=".json"
            responseSchemaLoc="/zosConnect/banking/respSchema"
            responseSchemaSuffix=".json"/>      
  4. オプション: pollingRate および updateTrigger などの設定を構成してモニタリング・アクションを微調整します。 デフォルトで、データ変換定義に関連付けられたディレクトリーは、新規ファイルおよびファイル更新についてモニターされます。これらの構成属性について詳しくは、z/OS Connect 1.0 および z/OS Connect 1.2 の下の zosConnectDataXform エレメント・セクションを参照してください。
    <zosConnectDataXform id="globalDataXform" 
            bindFileLoc="/zosConnect/banking/bind/"
            bindFileSuffix=".bnd"   
            requestSchemaLoc="/zosConnect/banking/reqSchema"
            requestSchemaSuffix=".json"
            responseSchemaLoc="/zosConnect/banking/respSchema"
            responseSchemaSuffix=".json"
            pollingRate="500ms"> 
    </zosConnectDataForm>      

    この例では、500 ミリ秒ごとにファイル更新について /zosConnect/banking/bind,/zosConnect/banking/reqSchema ディレクトリーと /zosConnect/banking/respSchema ディレクトリーがポーリングされます。pollingRate 構成属性と updateTrigger 構成属性が構成されていない場合は、polled および 2 seconds のデフォルト値がそれぞれ使用されます。ファイルのモニタリングが必要ない場合は、updateTrigger 属性を disabled に設定することにより使用不可にできます。特定のファイルの手動最新表示をトリガーしたい場合は、updateTrigger属性を mbean に設定し、ファイル通知 mbean: com.ibm.ws.kernel.filemonitor.FileNotificationMBean を使用して更新をトリガーしてください。例えば、次のように指定します。

    String[] MBEAN_METHOD_SIGNATURE = new String[] {Collection.class.getName(),Collection.class.getName(),Collection.class.getName() };        
    JMXConnector jmxConnector = ...;        
    MBeanServerConnection mbsc = jmxConnector.getMBeanServerConnection();        
    ObjectName fileMonitorMBeanName = new ObjectName("WebSphere:service=com.ibm.ws.kernel.filemonitor.FileNotificationMBean");        
    
    List<String> paths = new ArrayList<String>();        
    paths.add("/zosConnect/banking/bind/customer.bnd");        
    paths.add("/zosConnect/banking/reqSchema/customer_request.json");       
    paths.add("/zosConnect/banking/respSchema/customer_response.json");        
    
    Object[] params = new Object[] { null, paths, null };        
    mbsc.invoke(fileMonitorMBeanName, "notifyFileChanges", params, MBEAN_METHOD_SIGNATURE);

    この例では、restConnector-1.0 フィーチャーを使用して customer.bndcustomer_request.json、および customer_response.json の各ファイルの更新をトリガーしています。セキュア JMX 接続の作成方法について詳しくは、Liberty へのセキュア JMX 接続の構成の資料を参照してください。


トピックのタイプを示すアイコン タスク・トピック

ファイル名: twlp_zconnect_msg_payload_conv.html