使用 z/OS Connect REST API

z/OS® Connect 提供一組 RESTful API,可用來探索服務、檢查服務狀態、啟動或停止服務、取得統計資料,以及執行其他作業。

關於這項作業

您可以從 Web、行動式或雲端環境中執行的用戶端,來使用 z/OS Connect REST API。

程序

  1. 探索 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" 
        } 
      ] 
    } 
  2. 擷取服務的配置資料。 範例 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" 
      } 
    }
  3. 擷取服務狀態。 範例 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"
      }
    }
  4. 擷取要求綱目。 範例 HTTP GET 要求:
    https://host:port/zosConnect/services/recordOpsCreate?action=getRequestSchema

    傳回的範例 JSON 有效負載。

    {
    <資料配置的資料轉換器所傳回的要求綱目>
    }
  5. 擷取回應綱目。 範例 HTTP GET 要求:
    https://host:port/zosConnect/services/recordOpsCreate?action=getResponseSchema

    傳回的範例 JSON 有效負載。

    {
    <資料配置的資料轉換器所傳回的要求綱目>
    }
  6. 擷取統計資料。

    統計資料包含服務(例如 InvokeRequestCountTimeOfRegistrationWithZosConnect)的 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 名稱/值配對,顯示服務傳回的統計資訊>
        }
      }
    }
  7. 擷取服務的統計資料,也可以利用 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:[]
    }
  8. 使用 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.
        }
      }
    }
  9. 使用 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 名稱/值配對,顯示服務傳回的統計資訊>
        }
      }
    }      
  10. 使用含有 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"
      }
    }
  11. 使用 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"
      }
    }
  12. 使用 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