z/OS Connect サービスの定義
z/OS® Connect サービス定義では、REST 呼び出しを使用して z/OS アプリケーション・アセットに到達するための手段が用意されています。 z/OS Connect サービスを使用可能にするには、Liberty の server.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 クライアント・サービスの資料を参照してください。
手順
- server.xml 構成に、各サービスの zosConnectService 構成エレメントを追加します。 少なくとも serviceRef 属性と serviceName 属性の構成が必要です。
serviceRef エレメントは、サービス・プロバイダーの構成エレメントを指します。
serviceName 属性を使用して、サービス・プロバイダーは z/OS Connect で識別され、
また、その名前が、特定サービスをターゲットにした z/OS Connect 要求の URL の一部として使用されます。
サービス名は固有である必要があります。
以下は、z/OS Connect サービス recordOpsCreate の追加に必要な内容を示したサンプルの
server.xml ファイルです。より完全な例がステップ 3 に示されていることに注意してください。
zosConnectService エレメントに関連する構成可能な属性定義について詳しくは、z/OS Connect フィーチャーの資料を参照してください。<!-- z/OS Connect service definitions --> <zosConnectService id="zcs1" serviceName="recordOpsCreate" serviceRef="wolaOpsCreate"/>
- (オプション) 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 フィーチャーの資料を参照してください。 - 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 エレメントの下に linkTaskChanID が useCICSContainer=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 ヘッダー名と値のペアのセットが含まれます。
ユーザーは、localAdaptersConnectService エレメントの下の linkTaskChanCtxContEncoding 構成属性を使用することによって、 すべてのコンテキスト・コンテナーに含まれるデータのデフォルトのエンコード方式 (cp819) を変更できます。
localAdaptersConnectService エレメントの下に linkTaskChanID が useCICSContainer=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