REST 서비스에 액세스하기 위한 인터페이스 파트 작성

사용자는 서비스의 요청자가 사용할 수 있게 된 파일에 EGL 인터페이스 파트를 정의합니다. 이 인터페이스 파트는 동일한 EGL 패키지 내에 있을 수 있으며 별도의 패키지로부터 가져올 수도 있습니다.

EGL 인터페이스 파트는 특정 서비스 조작에 액세스하는 데 필요한 코드를 작성하는 방법에 대한 설명인 함수 프로토타입을 하나 이상 포함합니다. 함수 프로토타입은 조작 이름, 매개변수(있는 경우) 및 리턴 유형(있는 경우)을 포함합니다. 이 프로토타입은 조작의 로직(서비스에서만 사용 가능)은 포함하지 않습니다.

EGL REST-RPC 서비스의 인터페이스 파트는 써드파티 REST 서비스의 인터페이스 파트보다 단순합니다.

EGL REST-RPC 서비스 액세스를 위한 인터페이스 파트

이 예제에서는 EGL REST-RPC 서비스 액세스를 위한 인터페이스 파트를 보여줍니다. 이 예제에는 하나의 함수 프로토타입이 포함되어 있습니다.
Interface EmployeeService
   Function GetEmployeeDetail(employeeCode STRING IN, 
                              employeeSalary FLOAT OUT, 
                              employeeStatus STRING INOUT) 
            returns(myEmployeeRecordPart);
end

사용자는 다양한 EGL 데이터 유형을 지정할 수 있으며 수정자 IN, OUT 및 INOUT을 사용할 수 있습니다.

인터페이스 파트를 작성하려면 다음 작업을 수행하십시오.
  1. 프로젝트 탐색기 보기에서 서비스를 정의하는 EGL 파일을 마우스 오른쪽 단추로 클릭하십시오.
  2. EGL 서비스 > EGL 인터페이스 추출을 클릭하십시오.
  3. 새 EGL 인터페이스 파트 창에서 적절한 세부사항을 지정하고 완료를 클릭하십시오.

써드파티 REST 서비스 액세스를 위한 인터페이스 파트

이 예제에서는 써드파티 REST 서비스 액세스를 위한 인터페이스 파트를 보여줍니다.
Interface WeatherForecast
   Function GetWeatherByZipCode(zipcode string in) returns(myRecordPart)
      {@GetRest{uriTemplate="/GetWeatherByZipCode?zipCode={zipcode}",
                requestFormat = JSON,
                responseFormat = JSON}};
end
이 인터페이스 파트의 용도는 써드파티 REST 서비스(EGL REST-RPC 서비스가 아님)에서 사용 가능한 조작을 설명하는 것이며, 사용자는 각 함수 프로토타입에 대해 복합 특성을 지정해야 합니다. 특성의 이름은 서비스에 액세스하는 데 사용되는 HTTP verb를 표시합니다.
  • GET 메소드의 경우 특성 이름은 @GetREST입니다.
  • POST 메소드의 경우 특성 이름은 @PostREST입니다.
  • PUT 메소드의 경우 특성 이름은 @PutREST입니다.
  • DELETE 메소드의 경우 특성 이름은 @DeleteREST입니다.
이 주제의 @xREST 특성 절에 설명되어 있는 바와 같이 이러한 복합 특성에는 각각 세 개의 동일한 특성 필드가 있으므로 이들 특성의 이름은 @xREST입니다.
써드파티 REST 서비스에 액세스하는 데 사용되는 서비스 호출 명령문에서 특성 함수 매개변수에 전달되는 인수의 용도는 다음 두 가지 중 하나입니다.
  • 일반적으로 이 인수는 요청자가 URI에 포함시키는 값을 제공합니다. 이 사용법은 이 주제의 뒷부분(@xREST 특성에 대한 설명)에 표시되어 있습니다. 이러한 값은 서비스 로직에 전달되지 않으며 URI에 임베드됩니다. 특히, 특성이 @GetREST인 경우에는 함수 매개변수에 지정된 모든 인수가 URI를 구성하는 데 사용됩니다.
  • 인수가 하나인 경우(대부분의 경우가 이에 해당) 이 인수는 서비스에 의해 처리되는 표현입니다. 데이터베이스 테이블 행을 작성하는 데 사용되는 값을 포함하는 레코드를 예로 들 수 있습니다. 자세한 내용은 다음과 같습니다.
    • 특정 조작의 특성이 @PostREST 또는 @PutREST인 경우에는 추가 인수가 있어야 하며 이 경우 관련 매개변수를 표현 매개변수라 합니다.
    • 특성이 @DeleteREST인 경우에는 이 인수가 필수인 경우도 있습니다. 이러한 인수에 대한 필요성은 서비스 제공자에 따라 달라집니다.
함수 프로토타입에 uriTemplate 특성 필드(@PostREST, @PutREST 또는 @DeleteREST의 경우)에서 식별되지 않은 매개변수가 있는 경우 해당 매개변수는 표현 매개변수입니다. 다음 두 사례는 모두 오류입니다.
  • 둘 이상의 표현 매개변수를 지정함
  • @GetREST를 사용할 때 표현 매개변수를 지정함

서비스에 전송되는 인수에 대한 제한사항은 "서비스 액세스에 사용되는 프로토타입의 제한사항"을 참조하십시오.

인터페이스 파트를 작성할 필요는 없습니다. 대신 사용자를 위해 제공되며 써드파티 REST 서비스에 액세스하는 데 사용되는 변수의 기초가 될 수 있는 인터페이스 파트인 IRest를 사용할 수 있습니다. 이 인터페이스 파트에 대한 자세한 정보는 "써드파티 REST 서비스에 대해 제공된 인터페이스 사용"을 참조하십시오.

써드파티 REST 서비스에 사용되는 @xREST 특성

각 @xREST 복합 특성에는 uriTemplate, requestFormatresponseFormat 필드가 있습니다.

uriTemplate
서비스에 액세스하는 데 사용되는 URI의 마지막 규정자를 식별하는 상대 URI를 나타내는(대부분의 경우) 문자열 또는 템플리트입니다. 배경 정보는 "개발자를 위한 REST"를 참고하십시오.
첫 번째 URI 규정자인 기본 URI는 다음 세 가지 방법 중 하나로 지정됩니다.
  • 인터페이스 파트를 기반으로 하는 변수를 선언할 때 기본 URI를 설정할 수 있습니다. 이 경우 이 기본 URI는 개발 시에 설정되며, 구성 시 또는 런타임 시에는 이를 변경할 수 없습니다. 이 사용법은 빠르고 간단하지만 유연하지 않습니다.
  • 또는, 인터페이스 파트를 기반으로 하는 변수를 선언할 때 배치 디스크립터의 항목을 식별할 수 있습니다. 이 경우 기본 URI의 초기값은 배치 디스크립터에 있으며 구성 시에 코드 설치 프로그램이 이 값을 변경할 수 있습니다.
  • 초기값을 지정한 방법에 관계없이, serviceLib.setServiceLocation 함수를 실행하여 런타임 시에 기본 URI의 값을 변경할 수 있습니다.

기본 URI를 설정하지 않는 경우에는 uriTemplate 특성 필드의 값이 전체 URI를 포함합니다. 대부분의 경우 uriTemplate 특성의 값에는 두 가지 요소가 있습니다.

  • uriTemplate 특성의 값은 상수 값을 포함할 수 있습니다. 이러한 문자는 함수에 액세스하는 데 사용되는 모든 URI의 내부 또는 그 뒤에 있습니다. 앞서 제시된 예제에서 uriTemplate에는 조회 변수가 포함되어 있으며 해당 상수 값은 다음과 같습니다.
       /GetWeatherByZip?zipcode= 
    이 예제가 조회 문자열 대신 경로 변수를 포함하도록 변경되는 경우 해당 상수 값은 다음과 같습니다.
       /GetWeatherByZip/
  • uriTemplate 특성의 값은 경로 변수 및 조회 변수를 포함할 수 있습니다. 앞서 제시된 예제는 하나의 조회 변수가 포함되어 있습니다.
       {zipcode}
    조회 문자열을 사용한 원래 예제의 경우 서비스에 액세스하는 데 사용되는 상대 URI 및 값은 다음과 같습니다.
    /GetWeatherByZip?zipcode=02135
    템플리트에 조회 문자열이 아니라 경로 변수가 포함되어 있는 경우 상대 URI는 다음과 같습니다.
    /GetWeatherByZip/02135

    EGL 런타임 코드는 한 가지 경우를 제외하고 서비스 호출 명령문에 지정된 각 대체 값에 대한 URI 인코딩을 자동으로 완료합니다.

    예를 들어, 서비스 호출 명령문에 특정 대체 변수의 값이 "Jeff Smith"로 되어 있는 경우, EGL 런타임 코드는 URI를 유효하게 하기 위해 이 문자열을 "Jeff%20Smith"로 변환합니다. 그러나 대체 값이 http로 시작하는 경우에는 서비스 호출 명령문에서 전체 URI를 제공하는 인수를 지정하고 있으므로 EGL 런타임 코드가 URI 인코딩을 수행하지 않습니다. 사용자가 URI 인코딩을 수행하는 경우에는 serviceLib.convertToURLEncoded 시스템 함수에 대한 문서를 검토하십시오.

사용자가 기본 URI를 설정하여 전체 URI를 지정할 수 있도록 uriTemplate 필드의 기본값은 빈 문자열입니다.

requestFormat
서비스에 전송되는 표현의 형식을 나타내는 값입니다.
  • XML(형식이 Extensible Markup Language임을 표시함)
  • NONE(표현이 문자열, 또는 문자열과 호환되는 값이며 그대로 전송됨을 표시함)
  • JSON(형식이 JavaScript Object Notation임을 표시함)
  • FORM(형식이 인수-값 쌍으로 구성된 레코드인 양식 데이터임을 표시함). 서비스에 전송되는 컨텐츠에 대한 예제인 다음 예제에서는 각 쌍이 앰퍼센드(&)를 사용하여 다음 쌍과 구분되어 있습니다.
    division=Consumer&dept=Sales
    양식 데이터의 기초인 레코드 파트에 있는 특정 필드에는 FormName 특성을 지정할 수 있습니다. 이 특성을 사용하여 EGL 예약어인 인수 이름 또는 EGL에서 유효하지 않은 인수 이름에 대해 작업할 수 있습니다. FormName 특성의 사용에 대한 예제는 다음과 같습니다.
    record anyRecord
       continue boolean {FormName="continue-content"};
    end
    런타임 코드는 FormName 특성의 값을 서비스에 전송되는 인수의 이름으로 사용합니다. 서비스에 전송되는 표현의 예제는 다음과 같습니다.
    continue-content=yes

    FormName 특성의 기본값은 레코드 필드의 이름입니다. 이 예제에서 기본값은 continue입니다.

    레코드 파트를 기반으로 하는 레코드를 선언할 때는 FormName 특성의 값을 대체할 수 없습니다.

표현이 레코드인 경우에는 다음 내용이 적용됩니다.
  • requestFormat의 기본값이 XML입니다.
  • JSON도 유효합니다.
  • FORM은 레코드에 있는 모든 필드의 유형이 STRING이거나 STRING과 지정 호환되는 유형인 경우에만 유효합니다. 레코드가 다른 레코드를 참조하는 경우에는 FORM이 유효하지 않습니다.
responseFormat
요청자에게 리턴되는 표현의 형식을 나타내는 값입니다.
  • XML(리턴되는 표현이 XML 형식임을 나타냄)
  • NONE(리턴되는 표현이 문자열임을 나타냄)
  • JSON(리턴되는 표현이 JSON 형식임을 나타냄)

인터페이스 파트 함수 프로토타입의 리턴값이 문자열이거나 문자열과 호환되는 값인 경우 responseFormat의 기본값은 이 경우 유일한 유효 형식인 NONE입니다, 리턴값이 레코드인 경우 responseFormat의 기본값은 XML이며 JSON 또한 유효합니다.

특성 필드에 값을 지정하지 않고 @xREST 특성을 지정할 수 있습니다.
Interface IEmployeeService
   Function GetEmployeeDetail() returns(myRecordPart)
      {@GetRest{}};
end
특성 필드에 값이 없는 경우는 다음 동작을 수행해야 함을 의미합니다.
  • 인터페이스 파트에 세부사항을 제공하지 말고 http://www.ibm.com/myservice와 같은 전체 REST 서비스 URI를 제공해야 합니다. 기본 URI를 지정하는 데 대한 세 가지 선택사항의 설명은 이 주제의 uriTemplate를 참조하십시오.
  • 표현 매개변수(또는 @GetREST 특성의 경우 리턴값)가 문자열인 경우에는 EGL 런타임 코드는 변환을 수행하지 않습니다. 사용자가 직접 변환을 처리해야 하며, 사용자는 이를 위해 다음 함수를 사용할 수 있습니다.
    • serviceLib.convertFromJSON
    • serviceLib.convertToJSON
    • XMLLib.convertFromXML
    • XMLLib.convertToXML
  • 표현 매개변수가 레코드인 경우 EGL 런타임 코드는 관련 인수를 XML(Extensible Markup Language) 형식으로 변환합니다.
  • @GetREST 특성의 경우, 리턴값이 레코드인 경우에는 EGL 런타임 코드가 이 레코드를 XML 형식으로부터 변환합니다.
.