z/OS Connect サービスの定義

z/OS® Connect サービス定義では、REST 呼び出しを使用して z/OS アプリケーション・アセットに到達するための手段が用意されています。 z/OS Connect サービスを使用可能にするには、Libertyserver.xml ファイルに、エレメント名 zosConnectService に名前とサービス・プロバイダー参照エレメント名を指定して、z/OS Connect サービス定義を追加する必要があります。

このタスクについて

z/OS Connect サービスは、zosConnectService 構成エレメントで定義されます。 このエレメントの属性定義には、対応するグローバル定義がある場合があります。 属性は、zosConnectManager エレメントでグローバルに定義できます。 これらの属性が定義された場合は、すべてのサービスに適用されます。 グローバル・レベルとサービス・レベルの属性が両方構成された場合は、 zosConnectService レベルで定義された値が使用されます。

z/OS Connect では、 z/OS Connect 要求が WebSphere 最適化ローカル・アダプター (WOLA) を通して z/OS アセットと対話可能なサービス実装が提供されています。 zosConnect-1.0 zosLocalAdapters-1.0 の両方のフィーチャーが構成されると、 このサービスは自動的に使用可能になります。このサービスのインスタンスは、 localAdaptersConnectService 構成エレメントにより定義できます。

z/OS Connect では、z/OS Connect 要求がリモート REST エンドポイントに接続することを可能にするサービス実装も提供されています。このサービスは、zosConnect-1.2 フィーチャーが構成されている場合使用可能です。このサービスのインスタンスは、zosConnectServiceRestClient 構成エレメントにより定義できます。詳細情報については、z/OS Connect REST クライアント・サービスの資料を参照してください。

手順

  1. server.xml 構成に、各サービスの zosConnectService 構成エレメントを追加します。 少なくとも serviceRef 属性と serviceName 属性の構成が必要です。 serviceRef エレメントは、サービス・プロバイダーの構成エレメントを指します。 serviceName 属性を使用して、サービス・プロバイダーは z/OS Connect で識別され、 また、その名前が、特定サービスをターゲットにした z/OS Connect 要求の URL の一部として使用されます。 サービス名は固有である必要があります。 以下は、z/OS Connect サービス recordOpsCreate の追加に必要な内容を示したサンプルの server.xml ファイルです。より完全な例がステップ 3 に示されていることに注意してください。
    <!-- z/OS Connect service definitions --> 
    <zosConnectService id="zcs1"  
    	serviceName="recordOpsCreate"  
    	serviceRef="wolaOpsCreate"/> 
    zosConnectService エレメントに関連する構成可能な属性定義について詳しくは、z/OS Connect フィーチャーの資料を参照してください。
  2. (オプション) server.xml ファイルに zosConnectManager 構成エレメントを追加します。

    このエレメントは、server.xml 構成内の singleton で、 サーバーに定義されたすべての z/OS Connect サービスに適用されるグローバル値を含みます。 このエレメントは、サーバー内のすべてのサービスに適用される z/OS Connect インターセプターまたはデータ変換プロバイダー構成エレメントの名前を含むことができます。

    以下の例では、項目 globalOperationsGroup で操作グループ名 Operator1 を定義する zosConnectManager 構成エレメントを記述しています。 これは、z/OS Connect 操作要求 (action=start|stop|status など) が許可される前に要求側クライアント・ユーザー ID が属する必要があるセキュリティー (SAF または LDAP) グループの名前です。 このグループは、z/OS Connect 構成内のすべてのサービスに適用されます。 項目 dataxform は、z/OS Connect がデータ変換プロバイダーを検索するエレメント名を定義します。 zosConnect エレメントの dataxform を指定すると、これが、構成内で独自のデータ変換エレメント参照がないすべてのサービスの変換プロバイダー実装であることになります。 interceptors の項目は、構成内の全サービスに適用される z/OS Connect インターセプターのセットを記述した、 構成内のエレメントの名前です。

    <zosConnectManager id="zosConnectGlobals"  
    	globalOperationsGroup="Operator1"  
    	globalDataxformRef="XformJSON2Byte"  
    	globalInterceptorsRef="GlobalInterceptors"/> 

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

    各属性について詳しくは、Liberty フィーチャーの資料を参照してください。
  3. Liberty で WOLA が構成された場合、要求の構成で server.xml ファイルに localAdaptersConnectService 構成エレメントが必要です。 この構成は、最低限、ターゲット WOLA 接続ファクトリー名、登録名、およびサービス名から構成されます。 z/OS Connect の構成は、最小限のパラメーターの指定だけを必要として、Liberty の規則に従います。z/OS Connect の対話に WOLA 接続ファクトリーを構成する場合、認証メカニズムとしてコンテナーを使用する必要があります。 containerAuthDataRef 属性の指定がない WOLA 接続ファクトリーはサポートされません。 以下に例を示します。
    <!-- Local adapters connection factory definition --> 
    <authData id="cauth1" user="user1" password="{xor}LDo8Ki02KyY="/> 
    <connectionFactory id="wolaCF" jndiName="eis/ola"        
    	containerAuthDataRef="cauth1"  >       
    	<properties.ola/> 
    </connectionFactory>     
    
    <!-- Local adapters config --> 
    <zosLocalAdapters wolaGroup="LIBERTY" wolaName2="LIBERTY"         
    	wolaName3="LIBERTY" /> 
    
    <!-- WOLA Connect service and z/OS Connect service definitions --> 
    <localAdaptersConnectService id="wolaOpsCreate"             
    	registerName="BATCH01"   
    	serviceName="COBLPGM1"   
    	connectionFactoryRef="wolaCF"/> 
    
    <zosConnectService id="zcs1" serviceName="recordOpsCreate"    
    	serviceRef="wolaOpsCreate"   
    	runGlobalInterceptors="true"    
    	interceptorsRef="serviceInterceptorList"
            dataXformRef="zconXform"/> 
    
    <!-- z/OS Connect data transformer --> 
    <zosConnectDataXform id="zconXform"          
    	bindFileLoc="/zosConnect/bind" 
            bindFileSuffix=".bnd"   
    	requestSchemaLoc="/zosConnect/schema"  
    	responseSchemaLoc="/zosConnect/schema"
    	requestSchemaSuffix=".json"
    	responseSchemaSuffix=".json">
    </zosConnectDataXform> 

    z/OS Connect 要求が WebSphere 最適化ローカル・アダプター (WOLA) を通して z/OS アセットと対話可能な z/OS Connect サービス実装には、 データ変換プログラムが必要な場合があります。 グローバルでもサービス・レベルでもデータ変換プログラムが構成された場合、 入出力のペイロードは、構成されたデータ変換プログラムを使用して変換されます。 データ変換プログラムが構成されず、要求に JSON ペイロードが含まれる場合、 サービスは、バックエンド・プログラムがデータ変換を処理することを想定します。 サービスは、要求ヘッダーに指定されたエンコード、またはデフォルト JSON エンコードの UTF-8 を使用して、現状の JSON ペイロードをバイト配列に変換します。 同様に、アセットがペイロードを戻し、データ変換プログラムが構成されていない場合、 WOLA サービス実装は、JSON ペイロードをバイト配列形式で受け取ることを予期します。 これは、JSON 要求ペイロードをバイト配列に変換するために使用されるものと同じエンコード・ルールに従って JSON 応答ペイロードに変換されます。

    localAdaptersConnectService エレメントの下に linkTaskChanIDuseCICSContainer=true と共に構成されている場合、 コンテキスト・コンテナーのセットおよびペイロード・コンテナーが宛先プログラムに送信されます。 以下のリストにコンテキスト・コンテナーの名前と説明を示します。
    ZCONReqURL
    ZCONRegURL コンテキスト・コンテナーには、HTTP 要求 URL が含まれます。例えば、invokeURI 定義 /banking/deposit および照会パラメーター country=USA を使用する場合、URL は https//localhost:port/banking/deposit?country=USA です。
    ZCONReqQParms
    ZCONReqQParms コンテキスト・コンテナーには、HTTP 要求照会パラメーターが含まれます。例えば、 要求 URL が https//localhost:port//banking/deposit?country=USA の場合、照会パラメーターは country=USA です。
    ZCONReqMethod
    ZCONReqMethod コンテキスト・コンテナーには、HTTP 要求メソッドが含まれます。例えば、GET などです。
    ZCONHTTPHeaders
    ZCONHTTPHeaders コンテキスト・コンテナーには、localAdaptersConnectService エレメントの下の linkTaskChanCtxContHttpHeaders 属性を使用して構成される、JSON 形式の HTTP ヘッダー名と値のペアのセットが含まれます。
    linkTaskChanCtxContHttpHeaders 属性は、ZCONHTTPHeaders コンテナー内の、宛先プログラムに渡されるヘッダー名を表す、大/小文字の区別のあるストリングのコンマ区切りリストを受け入れます。このコンテキスト・コンテナーに含まれる情報は、JSON 形式です (例えば、{httpHeaders:{"header1":"header1Value", ...,"headerN":"headerNValue"}})。要求に同じ名前のヘッダーが複数含まれている場合、要求内の最初のヘッダーの値が使用されます。

    ユーザーは、localAdaptersConnectService エレメントの下の linkTaskChanCtxContEncoding 構成属性を使用することによって、 すべてのコンテキスト・コンテナーに含まれるデータのデフォルトのエンコード方式 (cp819) を変更できます。

    localAdaptersConnectService エレメントの下に linkTaskChanIDuseCICSContainer=true と共に構成されている場合、 linkTaskChanReqContID 属性および linkTaskChanRespContID 属性を使用することによって、入力コンテナー・ペイロード名および出力コンテナー・ペイロード名をカスタマイズできます。これらの属性が定義されていない場合のデフォルト名は ZCONReqData および ZCONRespData です。以下の例は、適切な構成を示しています。
    <localAdaptersConnectService id="wolaOpsCreate"             
            registerName="OLASERVER"
            serviceName="ZCONMC5"
            connectionFactoryRef="wolaCF"
            linkTaskChanID="ZCONCHANNEL"
            linkTaskChanType="1"
            useCICSContainer="true"
            linkTaskChanCtxContHttpHeaders="Connection, CustomHeader1, CustomHeader2, CustomHeader3"
            linkTaskChanReqContID="wolaOpsReqData"
            linkTaskChanRespContID="wolaOpsRespData"
            linkTaskChanCtxContEncoding="cp037"/>

    次の表に、localAdaptersConnectService 属性定義とそれぞれの説明をリストします。

    属性定義 説明

    serviceName

    required="true"

    type="String"

    WOLA ターゲット・サービスの名前。 serviceName は、外部アドレス・スペースのアプリケーションが WOLA 受信要求またはホスト・サービス API 呼び出しでサービス名に使用する名前、 または WOLA CICS リンク・サーバーでの SVC に使用されるプログラム名に一致する必要があります。

    registerName

    required="true"

    type="String"

    WOLA ターゲット登録の名前。 この名前は、外部アドレス・スペースのアプリケーションが WOLA 登録 API 呼び出しで登録名に使用している名前、または WOLA CICS リンク・サーバーでの RGN に使用される名前に一致している必要があります。registerName は、1 から 12 文字の任意の英数字ストリングです。

    connectionFactoryRef

    required="true"

    type="String"

    構成された WOLA リソース・アダプター接続ファクトリーへの参照。

    connectionWaitTimeout

    required="false"

    type="Integer"

    min="0"

    max="2147483647"

    登録名に一致する外部アドレス・スペース・アプリケーションが、WOLA 受信要求またはホスト・サービス API を実行してアクティブになるのを待機する時間 (秒単位)。この属性は、最適化されたローカル・アダプター接続ファクトリーの ConnectionWaitTimeout プロパティーを定義します。値が指定されていない場合、プロパティーのデフォルト値が使用されます。詳しくは、『Liberty プロファイルでの最適化されたローカル・アダプターの接続ファクトリー・プロパティー』の資料を参照してください。

    linkTaskTranID

    required="false"

    type="String"

    WOLA CICS リンク・サーバーのリンク呼び出しタスクのトランザクション ID の名前 (4 文字の任意のストリング) を定義します。この属性は、CICS リンク・サーバーを使用している時に使用されます。この属性は、最適化されたローカル・アダプター接続ファクトリーの LinkTaskTranID プロパティーを定義します。 詳しくは、『Liberty プロファイルでの最適化されたローカル・アダプターの接続ファクトリー・プロパティー』の資料を参照してください。

    useCICSContainer

    required="false"

    type="Boolean"

    default="false"

    データ伝搬に使用するメカニズムを定義します。true に設定すると、ペイロードが、CICS コンテナーを使用してターゲットの CICS アプリケーション・プログラムに渡されます。false (デフォルト) に設定すると、ペイロードは COMMAREA を使用してターゲットの CICS アプリケーション・プログラムに渡されます。この属性は、CICS リンク・サーバーを使用している時に使用されます。この属性は、最適化されたローカル・アダプター接続ファクトリーの useCICSContainer プロパティーを定義します。詳しくは、『Liberty プロファイルでの最適化されたローカル・アダプターの接続ファクトリー・プロパティー』の資料を参照してください。

    linkTaskReqContType

    type="Integer"

    min="0"

    default="0"

    要求コンテナーの型を定義します (0=CHAR、1=BIT)。この属性は、CICS リンク・サーバーを使用しており、linkTaskReqContID 属性と useCICSContainer (true) 属性も構成されている時に使用されます。この属性は、最適化されたローカル・アダプター接続ファクトリーの linkTaskReqContType プロパティーを定義します。詳しくは、『Liberty プロファイルでの最適化されたローカル・アダプターの接続ファクトリー・プロパティー』の資料を参照してください。

    linkTaskRspContID

    required="false"

    type="String"

    応答 (出力) コンテナーの名前を定義します (CICS に定義されたコンテナー名と一致する 1 から 16 文字のストリング)。この属性は、CICS リンク・サーバーを使用しており、linkTaskReqContID 属性と useCICSContainer (true) 属性も構成されている時に使用されます。この属性は、最適化されたローカル・アダプター接続ファクトリーの linkTaskRspContID プロパティーを定義します。 詳しくは、『Liberty プロファイルでの最適化されたローカル・アダプターの接続ファクトリー・プロパティー』の資料を参照してください。

    linkTaskRspContType

    type="Integer"

    min="0"

    default="0"

    応答コンテナーの型を定義します (0=CHAR、1=BIT)。この属性は、CICS リンク・サーバーを使用しており、linkTaskRspContID 属性と useCICSContainer (true) 属性も構成されている時に使用されます。この属性は、最適化されたローカル・アダプター接続ファクトリーの linkTaskRspContType プロパティーを定義します。詳しくは、『Liberty プロファイルでの最適化されたローカル・アダプターの接続ファクトリー・プロパティー』の資料を参照してください。

    linkTaskChanID

    required="false"

    type="String"

    CICS コンテナーを使用してペイロードを配信または受信するために使用する CICS チャネル名を定義します (CICS に定義されたチャネル名と一致する 1 から 16 文字のストリング)。この属性は、CICS リンク・サーバーを使用しており、useCICSContainer (true) 属性も構成されている時に使用されます。この属性は、最適化されたローカル・アダプター接続ファクトリーの linkTaskChanID プロパティーを定義します。詳しくは、『Liberty プロファイルでの最適化されたローカル・アダプターの接続ファクトリー・プロパティー』の資料を参照してください。

    linkTaskChanType

    required="false"

    type="Integer"

    min="0"

    default="0"

    構成済みのチャネル ID に関連付けられる CICS コンテナーの型を定義します(0=CHAR、1=BIT)。0=CHAR (デフォルト) に設定されている場合、入出力コンテナー内の文字データのエンコード方式は、ASCII (CCSID 819) で予期/返され、データは、宛先プログラムへ、または宛先プログラムから送信される前/後に EBCDIC (cp037) に、または EBCDIC (cp037) から変換されます。データ型とエンコード方式が予期されないようにするには、BIT 型を使用します。この属性は、CICS リンク・サーバーを使用しており、linkTaskChanID 属性と useCICSContainer (true) 属性も構成されている時に使用されます。この属性は、最適化されたローカル・アダプター接続ファクトリーの linkTaskChanType プロパティーを定義します。詳しくは、『Liberty プロファイルでの最適化されたローカル・アダプターの接続ファクトリー・プロパティー』の資料を参照してください。

    linkTaskChanReqContID

    required="false"

    default="ZCONReqData"

    type="String"

    要求コンテナーの名前を定義します (CICS に定義されたコンテナー名と一致する 1 から 16 文字のストリング)。この属性は、CICS リンク・サーバーを使用しており、linkTaskChanID 属性と useCICSContainer (true) 属性も構成されている時に使用されます。

    linkTaskChanRespContID

    required="false"

    default="ZCONRespData"

    type="String"

    応答コンテナーの名前を定義します (CICS に定義されたコンテナー名と一致する 1 から 16 文字のストリング)。この属性は、CICS リンク・サーバーを使用しており、linkTaskChanID 属性と useCICSContainer (true) 属性も構成されている時に使用されます。

    linkTaskChanCtxContEncoding

    required="false"

    type="String"

    default="cp819"

    宛先プログラムに送信されるすべてのコンテキスト・コンテナー内のデータのエンコード方式を定義します。この属性は、CICS リンク・サーバーを使用しており、linkTaskChanID 属性と useCICSContainer (true) 属性も構成されている時に使用されます。

    linkTaskChanCtxContHttpHeaders

    required="false"

    type="String"

    ZCONHTTPHeaders という名前のコンテキスト・コンテナーを使用して宛先プログラムに渡される、HTTP ヘッダー名、またはコンマ区切りの HTTP ヘッダー名リストを定義します。このコンテキスト・コンテナーに含まれる情報は、{httpHeaders:{"header1":"header1Value", ...,"headerN":"headerNValue"}} のような JSON 形式です。この属性は、CICS リンク・サーバーを使用しており、linkTaskChanID 属性と useCICSContainer (true) 属性も構成されている時に使用されます。


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

ファイル名: twlp_zconnect_srvcdef.html