定義 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.0zosLocalAdapters-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 一部分的名稱。服務名稱必須是唯一的。以下是範例 server.xml 檔,顯示如果要新增稱為 recordOpsCreate 的 z/OS Connect 服務時,需要提供哪些項目。 請注意,步驟 3 中顯示更完整的範例。
    <!-- z/OS Connect service definitions --> 
    <zosConnectService id="zcs1"  
    	serviceName="recordOpsCreate"  
    	serviceRef="wolaOpsCreate"/> 
    如需 zosConnectService 元素相關聯的可配置屬性定義的相關資訊,請參閱 z/OS Connect 特性的相關說明文件。
  2. (選用)在 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 特性說明文件。
  3. 如果在 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 元素下配置 linkTaskChanIDuseCICSContainer=true 時,一組環境定義儲存器和有效負載儲存器會傳送至目的地程式。 下列清單提供環境定義儲存器的名稱和說明。
    ZCONReqURL
    ZCONRegURL 環境定義儲存器包含 HTTP 要求 URL。比方說,如果您使用 /banking/depositinvokeURI 定義及查詢參數 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 屬性來定義。
    linkTaskChanCtxContHttpHeaders 屬性接受以逗點區隔、區分大小寫的字串清單,所代表的標頭名稱會傳給 ZCONHTTPHeaders 儲存器中的目的地程式。 此環境定義儲存器所包含的資訊採用 JSON 格式,例如,{httpHeaders:{"header1":"header1Value", ...,"headerN":"headerNValue"}}。如果要求含有多個同名的標頭,則使用的值是要求中第一個標頭的值。

    使用者可以使用 localAdaptersConnectService 元素下的 linkTaskChanCtxContEncoding 配置屬性,以修改所有環境定義儲存器所包含之資料的預設編碼 (cp819)。

    localAdaptersConnectService 元素下配置 linkTaskChanIDuseCICSContainer=true 時,您可以使用 linkTaskChanReqContIDlinkTaskChanRespContID 屬性,自訂輸入及輸出儲存器有效負載名稱。 如果未定義些屬性,預設名稱是 ZCONReqDataZCONRespData。下列範例說明適當的配置。
    <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