z/OS Connect REST API 사용

z/OS® Connect는 서비스를 발견하고 서비스 상태를 검사하고 서비스를 시작 또는 중지하고 통계를 가져오고 기타 조작을 수행하는 데 사용할 수 있는 RESTful API 세트를 제공합니다.

이 태스크 정보

웹, 모바일 또는 클라우드 환경에서 실행 중인 클라이언트에서 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을 사용하여 서비스를 시작하십시오.

    중지 및 시작 조치는 페이로드를 요구하지 않습니다. 제공되는 경우, 무시됩니다. 사용자는 서비스 상태를 검색하는 action=status 조회 문자열과 함께 서비스 이름에 대해 HTTP GET을 사용하여 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. 서비스 제공자 SPI 구현의 invoke() 메소드를 실행하는 z/OS Connect 조회 문자열 action=invoke를 사용하여 서비스를 호출하십시오.

    이 단계의 샘플은 recordOpsCreate라는 서비스를 위한 메소드를 호출하고 요청 본문에 JSON 오브젝트 페이로드를 전달합니다.

    z/OS Connect 호출 메소드는 이 요청에 대해 JSON 오브젝트 형식의 입력 페이로드를 지원합니다. 코드 예제에서 z/OS Connect는 서비스 제공자를 검색하고 SAMPLE-1.0이라는 서비스에 대한 서비스 참조를 식별한 것으로 가정합니다. jsonByte-1.0라는 제공자에 대한 z/OS Connect 서비스 정의에는 데이터 변환 참조도 있습니다. 여기에서 서비스 제공자의 메소드를 호출하면 제어를 가져오고 getBytes() 메소드를 호출하며, 데이터 변환 구현은 제어를 가져오고 요청 페이로드를 JSON에서 바이트 배열로 변환한 후 서비스 제공자로 리턴합니다.

    조치 요청을 호출하는 URL에 조회 매개변수가 포함된 경우, 이러한 매개변수와 함께 다른 HTTP 요청 정보가 z/OS Connect에서 제공되는 com.ibm.wsspi.zos.connect.HttpZosConnectRequest SPI 인터페이스를 사용하여 서비스 제공자로 전달됩니다. 조치 또는 조작에 대해 처리된 인터셉터도 동일한 오브젝트를 통해 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 object passed in for the service invocation>
    }

    리턴되는 샘플 JSON 페이로드:

    {
    <JSON object returned from the service invocation>
    }

주제의 유형을 표시하는 아이콘 태스크 주제

파일 이름: twlp_zconnect_rest.html