定義 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 一部分的名稱。服務名稱必須是唯一的。以下是範例 server.xml 檔,顯示如果要新增稱為 recordOpsCreate 的 z/OS Connect 服務時,需要提供哪些項目。
請注意,步驟 3 中顯示更完整的範例。
如需 zosConnectService 元素相關聯的可配置屬性定義的相關資訊,請參閱 z/OS Connect 特性的相關說明文件。<!-- z/OS Connect service definitions --> <zosConnectService id="zcs1" serviceName="recordOpsCreate" serviceRef="wolaOpsCreate"/>
- (選用)在 server.xml 檔中新增 zosConnectManager 配置元素。
這個元素在 server.xml 配置中是單態,所包含的廣域值會套用至定義給伺服器的所有 z/OS Connect 服務。這個元素可以包含 z/OS Connect 攔截程式或資料轉換提供者配置元素的名稱,並且是套用至伺服器中的所有服務。
下列範例說明 zosConnectManager 配置元素,它在 globalOperationsGroup 項目之下定義了作業群組名稱 Operator1。這是安全(SAF 或 LDAP)群組的名稱,要求端用戶端的使用者 ID 必須在這個群組中,才允許其發出 z/OS Connect 作業要求,例如 action=start|stop|status。這個群組會套用至 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 Connection Factory 名稱、登錄名稱和服務名稱組成。配置 z/OS Connect 時,只需要指定最基本的參數,就足以遵循 Liberty 使用慣例。請注意,當您配置 WOLA Connection Factory,以便與 z/OS Connect 互動時,您必須使用儲存器來作為鑑別機制。不支援沒有指定 containerAuthDataRef 屬性的 WOLA Connection Factory。範例如下:
<!-- 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 服務實作容許 z/OS Connect 要求透過「WebSphere 最佳化本端配接器 (WOLA)」,來與 z/OS 資產互動,其可能需要資料轉換器。如果配置了資料轉換器,不論是廣域或是在服務層次,都會使用所配置的資料轉換器,來轉換輸入及輸出有效負載。如果沒有配置資料轉換器,且要求含有 JSON 有效負載,服務會假設後端程式將處理資料轉換。服務會使用要求標頭中指定的編碼,或使用預設 JSON 編碼 UTF-8,將 JSON 有效負載依現狀轉換成位元組陣列。同樣地,如果資產傳回內容,卻沒有配置資料轉換器,WOLA 服務實作會預期將收到位元組陣列格式的 JSON 有效負載,其會遵循將 JSON 要求內容轉換成位元組陣列時所用的相同編碼規則,來轉換成 JSON 回應內容。
當 localAdaptersConnectService 元素下配置 linkTaskChanID 及 useCICSContainer=true 時,一組環境定義儲存器和有效負載儲存器會傳送至目的地程式。 下列清單提供環境定義儲存器的名稱和說明。- ZCONReqURL
- ZCONRegURL 環境定義儲存器包含 HTTP 要求 URL。比方說,如果您使用 /banking/deposit 的 invokeURI 定義及查詢參數 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 環境定義儲存器包含一組 JSON 格式的 HTTP 標頭名稱/值配對,這些配對是使用 localAdaptersConnectService 元素下的 linkTaskChanCtxContHttpHeaders 屬性來定義。
使用者可以使用 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」或「主機服務 API」呼叫中所用的服務名稱,或符合在「WOLA CICS 鏈結伺服器」中使用的 SVC 程式名稱。 registerName
required="true"
type="String"
WOLA 目標登錄的名稱。這個名稱必須符合外部位址空間應用程式在 WOLA 的「登錄 API」呼叫中所用的登錄名稱,或符合在「WOLA CICS 鏈結伺服器」中使用的 RGN 名稱。registerName 可以是 1 到 12 個字元的任何英數字串。 connectionFactoryRef
required="true"
type="String"
參照已配置的 WOLA 資源配接器 Connection Factory。 connectionWaitTimeout
required="false"
type="Integer"
min="0"
max="2147483647"
等待符合登錄名稱的外部位址空間應用程式,發出 WOLA「接收要求 API」或「主機服務 API」並且變成作用中的秒數。這個屬性定義「最佳化本端配接器」Connection Factory 的 ConnectionWaitTimeout 內容。 如果未指定值,則會使用內容的預設值。如需相關資訊,請參閱 Liberty 說明文件中有關最佳化本端配接器的 Connection Factory 內容。 linkTaskTranID
required="false"
type="String"
定義「WOLA CICS 鏈結伺服器」鏈結呼叫作業交易 ID 的名稱(任何 4 個字元的字串)。當使用「CICS 鏈結伺服器」時,會使用這個屬性。這個屬性定義「最佳化本端配接器」Connection Factory 的 LinkTaskTranID 內容。 如需相關資訊,請參閱 Liberty 說明文件中有關最佳化本端配接器的 Connection Factory 內容。 useCICSContainer
required="false"
type="Boolean"
default="false"
定義資料的傳播機制。當設定為 true 時,會使用 CICS 儲存器,將有效負載傳遞給目標 CICS 應用程式。當設定為 false 時,會使用 COMMAREA,將有效負載傳遞給目標 CICS 應用程式。當使用「CICS 鏈結伺服器」時,會使用這個屬性。這個屬性定義「最佳化本端配接器」Connection Factory 的 useCICSContainer 內容。 如需相關資訊,請參閱 Liberty 說明文件中有關最佳化本端配接器的 Connection Factory 內容。 linkTaskReqContType
type="Integer"
min="0"
default="0"
定義要求儲存器的類型 (0=CHAR, 1=BIT)。當使用「CICS 鏈結伺服器」,並且還配置了 linkTaskReqContID 和 useCICSContainer (true) 屬性時,會使用這個屬性。這個屬性定義「最佳化本端配接器」Connection Factory 的 linkTaskReqContType 內容。 如需相關資訊,請參閱 Liberty 說明文件中有關最佳化本端配接器的 Connection Factory 內容。 linkTaskRspContID
required="false"
type="String"
定義回應儲存器或輸出儲存器的名稱(1 到 16 個字元的字串,符合定義給 CICS 的儲存器名稱)。當使用「CICS 鏈結伺服器」,並且還配置了 linkTaskReqContID 和 useCICSContainer (true) 屬性時,會使用這個屬性。這個屬性定義「最佳化本端配接器」Connection Factory 的 linkTaskRspContID 內容。 如需相關資訊,請參閱 Liberty 說明文件中有關最佳化本端配接器的 Connection Factory 內容。 linkTaskRspContType
type="Integer"
min="0"
default="0"
定義回應儲存器的類型 (0=CHAR, 1=BIT)。當使用「CICS 鏈結伺服器」,並且還配置了 linkTaskRspContID 和 useCICSContainer (true) 屬性時,會使用這個屬性。這個屬性定義「最佳化本端配接器」Connection Factory 的 linkTaskRspContType 內容。 如需相關資訊,請參閱 Liberty 說明文件中有關最佳化本端配接器的 Connection Factory 內容。 linkTaskChanID
required="false"
type="String"
使用 1 到 16 個字元的字串(符合定義給 CICS 的通道名稱)來定義 CICS 通道名稱,以便在使用 CICS 儲存器來交付和接收有效負載時使用。當使用「CICS 鏈結伺服器」,並且還配置了 useCICSContainer (true) 屬性時,會使用這個屬性。這個屬性定義「最佳化本端配接器」Connection Factory 的 linkTaskChanID 內容。 如需相關資訊,請參閱 Liberty 說明文件中有關最佳化本端配接器的 Connection Factory 內容。 linkTaskChanType
required="false"
type="Integer"
min="0"
default="0"
定義要與所配置的通道 ID 相關聯的 CICS 儲存器類型 (0=CHAR, 1=BIT)。當設為 0=CHAR(預設值)時,所預期/傳回的輸入/輸出儲存器字元資料編碼方式會是 ASCII (CCSID 819),並且與目的地程式之間往來收發資料之前/之後,會與 EBCDIC (cp037) 之間進行資料轉換。使用 BIT 類型可避免資料類型和編碼期望。當使用「CICS 鏈結伺服器」,並且還配置了 linkTaskChanID 和 useCICSContainer (true) 屬性時,會使用這個屬性。這個屬性定義「最佳化本端配接器」Connection Factory 的 linkTaskChanType 內容。 如需相關資訊,請參閱 Liberty 說明文件中有關最佳化本端配接器的 Connection Factory 內容。 linkTaskChanReqContID
required="false"
default="ZCONReqData"
type="String"
使用 1 到 16 個字元的字串(符合定義給 CICS 的儲存器名稱),定義要求儲存器的名稱。當使用「CICS 鏈結伺服器」,並且還配置了 linkTaskChanID 和 useCICSContainer (true) 屬性時,會使用這個屬性。
linkTaskChanRespContID
required="false"
default="ZCONRespData"
type="String"
使用 1 到 16 個字元的字串(符合定義給 CICS 的儲存器名稱),定義回應儲存器的名稱。當使用「CICS 鏈結伺服器」,並且還配置了 linkTaskChanID 和 useCICSContainer (true) 屬性時,會使用這個屬性。
linkTaskChanCtxContEncoding
required="false"
type="String"
default="cp819"
針對要送往目的地程式的所有環境定義儲存器,定義其資料的編碼。當使用「CICS 鏈結伺服器」,並且還配置了 linkTaskChanID 和 useCICSContainer (true) 屬性時,會使用這個屬性。
linkTaskChanCtxContHttpHeaders
required="false"
type="String"
利用含有 ZCONHTTPHeaders 名稱的環境定義儲存器,定義要傳遞給目的地程式的 HTTP 標頭名稱,或以逗點區隔的 HTTP 標頭名稱清單。此環境定義儲存器所包含的資訊採用 JSON 格式,如下所示:{httpHeaders:{"header1":"header1Value", ...,"headerN":"headerNValue"}}。當使用「CICS 鏈結伺服器」,並且還配置了 linkTaskChanID 和 useCICSContainer (true) 屬性時,會使用這個屬性。

檔名:twlp_zconnect_srvcdef.html