使用 z/OS Connect REST API

z/OS® Connect 提供了一组 RESTful API,可以使用这些 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 有效内容。

    {
    <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. 检索统计信息。

    统计信息包括诸如 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 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 或 PUT 请求来停止 z/OS Connect 服务,或者使用带有 action=start 查询字符串的 HTTP POST 或 PUT 来启动服务。

    停止和启动操作不需要有效内容。如果提供了有效内容,那么会忽略有效内容。用户可以通过对服务名称使用 HTTP GET 以及 action=status 查询字符串来检索服务状态的方法来检索 z/OS Connect 服务的状态。如果启用了由 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 中的请求有效内容转换为字节阵列,且将字节阵列返回到服务提供者。

    如果附带了调用操作请求的 URL 同时包含查询参数,那么会使用 z/OS Connect 所提供的 com.ibm.wsspi.zos.connect.HttpZosConnectRequest SPI 接口将这些参数以及其他 HTTP 请求信息传递到服务提供者。为操作处理的拦截器还会通过同一对象接收 HTTP 请求信息。

    z/OS Connect 支持的另一种调用样式提供了一种方法将用户定义的 URI 定义为 z/OS Connect 服务定义中的 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 object passed in for the service invocation>
    }

    返回的样本 JSON 有效内容:

    {
    <JSON object returned from the service invocation>
    }

用于指示主题类型的图标 任务主题

文件名:twlp_zconnect_rest.html