使用 z/OS Connect REST API
z/OS® Connect 提供一組 RESTful API,可用來探索服務、檢查服務狀態、啟動或停止服務、取得統計資料,以及執行其他作業。
關於這項作業
您可以從 Web、行動式或雲端環境中執行的用戶端,來使用 z/OS Connect REST API。
程序
- 探索 z/OS Connect 配置中的服務。
範例 HTTP GET 要求:
https://host:port/zosConnect/services
傳回的範例 JSON 有效負載:
{ zosConnectServices: [ { ServiceName: "recordOpsCreate" ServiceDescription: "Creates a new record" ServiceProvider: "SAMPLE-1.0" ServiceURL: "https://host:port/zosConnect/services/recordOpsCreate" }, { ServiceName: "recordOpsDelete" ServiceDescription: "Deletes an existing record" ServiceProvider: "SAMPLE-1.0" ServiceURL: "https://host:port/zosConnect/services/recordOpsDelete" } ] }
- 擷取服務的配置資料。 範例 HTTP GET 要求:
https://host:port/zosConnect/services/recordOpsCreate
傳回的輸出分成兩部分:第一部分含有 z/OS Connect 配置參數,第二部分含有服務提供者實作所傳回的配置。以下是傳回的 JSON 有效負載範例:
{ zosConnect: { serviceName: "recordOpsCreate" serviceDescription: "Creates a new record" serviceProvider: "SAMPLE-1.0" serviceURL: "https://host:port/zosConnect/services/recordOpsCreate" serviceInvokeURL: "https://host:port/zosConnect/services/recordOpsCreate?action=invoke" dataXformProvider: "jsonByte-1.0" }, recordOpsCreate: { targetProgram: "CREATREC" timeout: "300ms" } }
- 擷取服務狀態。 範例 HTTP GET 要求:
https://host:port/zosConnect/services/recordOpsCreate?action=status
傳回的範例 JSON 有效負載。
{ zosConnect: { serviceName: "recordOpsCreate" serviceDescription: "Creates a new record" serviceProvider: "SAMPLE-1.0" serviceURL: "https://host:port/zosConnect/services/recordOpsCreate" serviceInvokeURL: "https://host:port/zosConnect/services/recordOpsCreate?action=invoke" dataXformProvider: "jsonByte-1.0" serviceStatus: "Started" } }
- 擷取要求綱目。 範例 HTTP GET 要求:
https://host:port/zosConnect/services/recordOpsCreate?action=getRequestSchema
傳回的範例 JSON 有效負載。
{ <資料配置的資料轉換器所傳回的要求綱目> }
- 擷取回應綱目。 範例 HTTP GET 要求:
https://host:port/zosConnect/services/recordOpsCreate?action=getResponseSchema
傳回的範例 JSON 有效負載。
{ <資料配置的資料轉換器所傳回的要求綱目> }
- 擷取統計資料。
統計資料包含服務(例如 InvokeRequestCount 和 TimeOfRegistrationWithZosConnect)的 z/OS Connect 資料,以及使用服務提供者中的 getStatistics() SPI 實作,而由服務提供者傳回的其他任何統計資料。特定服務的統計資料可以透過 /zosConnect/operation 或 action= request 呼叫來擷取。/zosConnect/operations 要求可提供更大的彈性,因為產品可以擷取所有服務的統計資料。若有啟用授權攔截程式,產品只會傳回使用者可以要求的那些服務的統計資料。如需詳細資料,請參閱 z/OS Connect 安全說明文件。
使用 action=getStatistics 來傳回統計資料的範例 HTTP GET 要求:
https://host:port/zosConnect/services/recordOpsCreate?action=getStatistics
傳回的範例 JSON 有效負載。
{ recordOpsCreate: { ServiceProvider: "SAMPLE-1.0" InvokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx" ServiceStatistics: { <JSON 名稱/值配對,顯示服務傳回的統計資訊> } } }
- 擷取服務的統計資料,也可以利用 zosConnect/operations/getStatisticsREST API 來達成。
傳回的資訊包含現行使用者可以要求之所有服務的統計資料。
使用 /zosConnect/operation/getStatistics 的範例 HTTP GET 要求:
https://host:port/zosConnect/operations/getStatistics
傳回的範例 JSON 有效負載。
{ zosConnectStatistics: [ { recordOpsCreate: { ServiceProvider: "SAMPLE-1.0" InvokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx" ServiceStatistics: { <JSON 名稱/值配對,顯示服務傳回的統計資訊> } } }, { recordOpsDelete: { ServiceProvider: "SAMPLE-1.0" InvokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx" ServiceStatistics: { <JSON 名稱/值配對,顯示服務傳回的統計資訊> } } } ] }
如果沒有向 z/OS Connect 登錄任何服務,則輸出類似如下:
{ zosConnectStatistics:[] }
- 使用 zosConnect/operations/getStatistics REST API,擷取定義給特定服務提供者之所有服務的統計資料。
範例 HTTP GET 要求:
https://host:port/zosConnect/operations/getStatistics?provider=SAMPLE-1.0
範例格式/輸出:
{ recordOpsCreate: { ServiceProvider: "SAMPLE-1.0" InvokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx" ServiceStatistics: { .. JSON name value pairs showing statistical information the service returned. } } }
- 使用 zosConnect/operations/getStatistics?service=<service name> REST API,擷取單一服務的統計資料。 這項作業等同於對服務指定 action=getStatistics。HTTP GET 要求:
https://host:port/zosConnect/operations/getStatistics?service=recordOpsCreate
傳回的範例 JSON 有效負載:
{ recordOpsCreate: { ServiceProvider: "SAMPLE-1.0" InvokeRequestCount: 100 TimeOfRegistrationWithZosConnect: "xxx-xx-xx xx:xx:xx:xxx xxx" ServiceStatistics: { <JSON 名稱/值配對,顯示服務傳回的統計資訊> } } }
- 使用含有 action=stop 的 HTTP POST 或 PUT 要求,來停止 z/OS Connect 服務,或使用含有 action=start 查詢字串的 HTTP POST 或 PUT,來啟動服務。
停止和啟動動作不需要有效負載。若有提供,則會忽略。使用者可以擷取 z/OS Connect 服務的狀態,作法是對服務名稱使用含有 action=status 查詢字串的 HTTP GET,來擷取服務狀態。若有啟用 z/OS Connect 提供的授權攔截程式,要求狀態或狀況變更的使用者,必須位於該服務所需要的操作員或管理者群組中。對於這每一項,z/OS Connect 會呼叫服務提供者 SPI,以告知已要求這些動作。對此,SPI 中的方法名稱是 stop()、start() 和 status()。
註: z/OS Connect 不會持續保存服務的任何相關狀態,而是將此任務委派給服務提供者。服務提供者可以傳送停止或啟動以外的回應。z/OS Connect 容許傳回自訂狀態。
使用 HTTP POST 或 PUT 來停止服務範例:
https://host:port/zosConnect/services/recordOpsCreate?action=stop
傳回的範例 JSON 有效負載:
{ zosConnect: { serviceName: "recordOpsCreate" serviceDescription: "Creates a new record" serviceProvider: "SAMPLE-1.0" serviceURL: "https://host:port/zosConnect/services/recordOpsCreate" serviceInvokeURL: "https://host:port/zosConnect/services/recordOpsCreate?action=invoke" dataXformProvider: "jsonByte-1.0" serviceStatus: "Stopped" } }
- 使用 HTTP POST 或 PUT 來啟動服務範例:
https://host:port/zosConnect/services/recordOpsCreate?action=start
傳回的範例 JSON 有效負載:
{ zosConnect: { serviceName: "recordOpsCreate" serviceDescription: "Creates a new record" serviceProvider: "SAMPLE-1.0" serviceURL: "https://host:port/zosConnect/services/recordOpsCreate" serviceInvokeURL: "https://host:port/zosConnect/services/recordOpsCreate?action=invoke" dataXformProvider: "jsonByte-1.0" serviceStatus: "Started" } }
- 使用 z/OS Connect 查詢字串 action=invoke 來呼叫服務,這會執行服務提供者 SPI 實作的 invoke() 方法。
這個步驟中的範例會針對名稱是 recordOpsCreate 的服務執行 invoke 方法,並在要求內文中傳遞 JSON 物件有效負載。
對於這項要求,z/OS Connect invoke 方法支援 JSON 物件格式的輸入有效負載。在程式碼範例中,假設 z/OS Connect 會查閱服務提供者,並識別稱為 SAMPLE-1.0 之服務的服務參照。z/OS Connect 服務定義 中也會有一項資料轉換參照,且其提供者名稱是 jsonByte-1.0。在這種情況下,當服務提供者的 invoke 方法取得控制權,並呼叫 getBytes() 方法時,資料轉換實作會取得控制權,並將要求有效負載從 JSON 轉換成位元組陣列,然後將它傳回給服務提供者。
如果隨 invoke 動作要求一起送入的 URL 包含查詢參數,會利用 z/OS Connect 提供的 com.ibm.wsspi.zos.connect.HttpZosConnectRequest SPI 介面,將這些參數連同其他的 HTTP 要求資訊,傳遞給服務提供者。針對動作或作業所處理的攔截程式,也會透過相同物件擷取 HTTP 要求資訊。
z/OS Connect 支援另一種呼叫樣式,藉由該樣式,可在 z/OS Connect 服務定義中,將使用者定義的 URI 定義成 invokeURI。利用這種樣式,HTTP 要求不必包含 zosConnect/services,而可以是使用者定義的字串。
當運用這種樣式時,z/OS Connect 支援使用其他 HTTP 方法,例如 GET、PUT、POST 和 DELETE。利用這個 URI 送達的要求,不論運用的 HTTP 方法為何,都會通過 z/OS Connect 攔截程式,並傳遞給服務提供者的 invoke() 方法。
使用 HTTP POST 或 PUT 的範例:
https://host:port/zosConnect/services/recordOpsCreate?action=invoke { <針對服務呼叫所傳入的 JSON 物件> }
傳回的範例 JSON 有效負載:
{ <從服務呼叫傳回的 JSON 物件> }

檔名:twlp_zconnect_rest.html