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 

    出力は 2 つのパートで戻されます。 最初のパートには、z/OS Connect 構成パラメーターが含まれ、2 つ目のパートには、サービス・プロバイダー実装で戻された構成が含まれます。 以下は、戻された 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 ペイロードの例。

    {
    <Request schema as returned by the data configured data transformer>
    }
  5. 応答スキーマを取得します。 HTTP GET 要求の例:
    https://host:port/zosConnect/services/recordOpsCreate?action=getResponseSchema

    戻された JSON ペイロードの例。

    {
    <Request schema as returned by the data configured data transformer>
    }
  6. 統計を取得します。

    統計には、サービスに関する z/OS Connect データ (InvokeRequestCountTimeOfRegistrationWithZosConnect など) と、プロバイダーの 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 name value pairs showing statistical information the service returned>
        }
      }
    }
  7. サービスの統計の取得は、zosConnect/operations/getStatistics REST 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 name value pairs showing statistical information the service returned>
             }
           }
         },
      {
        recordOpsDelete: 
        {  
             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>
             }
           }
         }
      ]
    }

    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 name value pairs showing statistical information the service returned>
        }
      }
    }      
  10. action=stop を指定した HTTP POST 要求または HTTP PUT 要求を使用して z/OS Connect サービスを停止するか、 action=start 照会ストリングを指定した HTTP POST 要求または HTTP PUT 要求を使用してサービスを開始します。

    停止アクションと開始アクションにペイロードは不要です。 指定しても、無視されます。 サービス名と、サービス状況取得のための action=status 照会ストリングを指定した HTTP GET を使用して、 z/OS Connect サービスの状況を取得することができます。 z/OS Connect 提供の許可インターセプターが有効になっている場合、状況または状態変更を要求するユーザーは、 サービスに必要なオペレーター・グループまたは管理者グループに含まれる必要があります。 それぞれについて、これらのアクションが要求されたことを通知するために、サービス・プロバイダー SPI が z/OS Connect によって呼び出されます。 このための SPI 内のメソッド名は、stop()、start()、および status() です。

    注: z/OS Connect は、サービスに関連付けられている状態を永続化せず、サービス・プロバイダーにこれを委任します。

    サービス・プロバイダーは、停止または開始以外の応答を送信することができます。 z/OS Connect は、カスタム状況が戻されることを許容します。

    HTTP POST または HTTP 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 または HTTP 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 に照会パラメーターが含まれる場合、 これらのパラメーターは他の HTTP 要求情報と一緒に、 z/OS Connect 提供の com.ibm.wsspi.zos.connect.HttpZosConnectRequest SPI インターフェースを使用してサービス・プロバイダーに渡されます。 アクションまたは操作に関して処理されるインターセプターも、同じオブジェクトを通じて HTTP 要求情報を受け取ります。

    z/OS Connect がサポートする別の起動方式として、z/OS Connect サービス定義で invokeURI としてユーザー定義の URI を定義する方法があります。 この方式では、HTTP 要求に zosConnect/services が含まれる必要はなく、 代わりにユーザー定義のストリングが可能です。

    この方式を採用した場合、 z/OS Connect で他の HTTP メソッド (GET、PUT、POST、DELETE など) の使用がサポートされます。 この URI で着信した要求は、使用された HTTP メソッドに関係なく、z/OS Connect のインターセプターを通過してサービス・プロバイダーの invoke() メソッドに渡されます。

    HTTP POST または HTTP PUT を使用した例:

    https://host:port/zosConnect/services/recordOpsCreate?action=invoke 
    {
    <JSON object passed in for the service invocation>
    }

    戻された JSON ペイロードの例:

    {
    <JSON object returned from the service invocation>
    }

トピックのタイプを示すアイコン タスク・トピック

ファイル名: twlp_zconnect_rest.html