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
出力は 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" } }
- サービス状況を取得します。 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 ペイロードの例。
{ <Request schema as returned by the data configured data transformer> }
- 応答スキーマを取得します。 HTTP GET 要求の例:
https://host:port/zosConnect/services/recordOpsCreate?action=getResponseSchema
戻された JSON ペイロードの例。
{ <Request schema as returned by the data configured data transformer> }
- 統計を取得します。
統計には、サービスに関する z/OS Connect データ (InvokeRequestCount や TimeOfRegistrationWithZosConnect など) と、プロバイダーの 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> } } }
- サービスの統計の取得は、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:[] }
- 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 name value pairs showing statistical information the service returned> } } }
- 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" } }
- 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" } }
- 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