[APIC]본격적으로 살펴보는 IBM API Connect 04 - API 어셈블 2

안녕하세요 이정운 입니다.

지난 강좌에서 API 어셈블에 대해서 살펴봤는데 테스트 해보시면서 느끼셨겠지만 API 어셈블을 위한 디자이너의 왼쪽 팔레트에는 이전 강좌에서 사용된 컴포넌트 이외에 미리 만들어진 다양한 컴포넌트가 추가로 많다는 것을 확인하셨을 것 입니다.

- 현재 버전(APIC v5.0.1) 의 API 어셈블 디자이너에서 제공하는 컴포넌트 리스트 -

기본 정책 - IBM API Connect 5.0 온라인 메뉴얼
https://www.ibm.com/support/knowledgecenter/ko/SSMNED_5.0.0/com.ibm.apic.toolkit.doc/rapim_ref_ootb_policies.html

이번 강좌에서는 지난번에 사용된 컴포넌트를 제외하고 간단하게 자주 사용되고 쓸 만한 컴포넌트 몇가지를 추가로 설명 및 테스트해볼 수 있는 시간을 가지도록 하겠습니다.

그럼 백문이 불여일타! API 어셈블2 에 대한 강좌를 진행하도록 하겠습니다.

1) if 컴포넌트와 gatewayscript 컴포넌트

If 컴포넌트는 말그대로 if 문의 역할을 수행하는 컴포넌트로 ‘조건’ 을 입력할 수 있고 그 조건이 true 인 경우 내부 flow 를 순서대로 수행하게끔 설정할 수 있습니다.

예 를 들어 위와 같은 조건(“request.parameters.loanAmount <= 0”)이라면 들어오는 요청(request) 의 파라미터(parameters) 중에 loanAmount 라는 파라미터의 값이 0 보다 작으면 true 이고 해당 flow 를 수행하게 됩니다. 이때 수행을 위해서 하단과 같이 gatewayscript 를 수행하도록 할 수 있습니다.

gatewayscript 컴포넌트는 손쉽게 javascript 를 수행할 수 있는 컴포넌트로 보시면 됩니다. 이 안에는 다양한 javascript 를 작성할 수 있으며 IBM API Connect 를 위해 미리 정의된 apim.custom.js 를 바로 불러서 사용할 수도 있습니다. 간단하게 위의 if 컴포넌트와 엮어서 파라미터에서 0 보다 작은 값이 왔을때 Error 를 발생하는 하나의 예제를 작성해보면 하단과 같습니다.

// Require API Connect Functions
var apic = require('local:///isp/policy/apim.custom.js');

// Throw Error
apic.error('Parameter Error', 500, 'Parameter Error', 'Parameter have to be grater than 0');

이제 테스트를 다시 수행해보는데 loanAmount 파라미터를 0 보다 작게 입력해서 테스트해보면 하단과 같은 결과를 얻을 수 있습니다.

이외에도 다양하게 javascript 코드를 작성하여 커스텀 동작을 수행하게 할 수 있습니다.

참 고 : javascript 에 주석이나 내용으로 한글을 입력하고자 할 경우에는 해당 컴포넌트에서 직접 타이핑하시는 것보다는 notepad 와 같은 text editro 에서 한글입력 후 Ctrl+C, Ctrl+V 로 붙여넣기 하시면 깔끔하게 한글을 입력할 수 있습니다.

GatewayScript code examples
https://www.ibm.com/support/knowledgecenter/en/SSMNED_5.0.0/com.ibm.apic.toolkit.doc/rapim_gwscript_codesnip.html

Implementation code examples
https://www.ibm.com/support/knowledgecenter/en/SSMNED_5.0.0/com.ibm.apic.policy.doc/rapim_imp_codesnip.html

2) gatewayscript 컴포넌트 2

이 전 파트에서 if 컴포넌트와 gatewayscript 컴포넌트를 사용해서 간단하게 해당 파라미터가 0보다 작으면 Error 를 발생하도록 테스트 해봤는데 조금 더 깊게 들어가서 gatewayscript 컴포넌트를 사용하여 응답 값을 변경하는 작업을 수행해보도록 하겠습니다.

지금까지 만들어진 flow 에 invoke 수행 후에 응답을 변경하기 위해서 gatewayscript 컴포넌트를 하단과 같이 추가합니다.

응답을 수정하기 위해서 기존에 있는 invoke 컴포넌트에 ‘Response object variable’ 에 응답으로 사용할 변수명을 입력합니다.

이 제 간단하게 invoke 컴포넌트를 통한 호출 후에 응답을 받아서 monthlyPaymentAmount 의 값만 소수점 이상으로 반올림(javascript 의 Math.rount() 함수 사용) 하도록 javascript 를 작성해보면 하단과 같습니다.

---------------------------------------------------------------------------------------------------
// API Connect 기능을 사용하기 위해서 정의
var apic = require('local:///isp/policy/apim.custom.js');

// 응답의 body 를 변수로 저장
var apiRsp = apic.getvariable('invokeRes02.body');

// 응답에 사용할 임시 데이터 객체 작성
var rspObj = {
  "loanAmount": apiRsp.loanAmount,
  "annualInterestRate": apiRsp.annualInterestRate,
  "termInMonths": apiRsp.termInMonths,
  "monthlyPaymentAmount": Math.round(apiRsp.monthlyPaymentAmount)
};

// 응답의 결과를 임시 데이터 객체로 변경해서 저장
apic.setvariable('message.body', rspObj);
---------------------------------------------------------------------------------------------------

이제 저장을 수행하고 테스트를 하게되면 하단과 같이 monthlyPaymentAmount 결과를 소수점에서 반올림하여 정수로 나오는 것을 확인할 수 있습니다.

3) validate 컴포넌트

validate 컴포넌트는 이름 그대로 스키마를 통해서 해당 값에 대한 검증을 수행할 수 있는 컴포넌트 입니다. 예를 들어 웹 서비스에는 wsdl 이라는 스키마가 있어서 요청(request) 가 들어올 때 해당 요청이  정상적인지 악의적인 수정이 없었는지에 대한 기본 검증이 가능합니다. 이와 마찬가지로 name:value 쌍인 json 에 대해서도 기업에서 사용하기 위해 Swagger 표준을 이용하여 스키마를 지정할 수 있고 그 스키마를 통해서 요청의 body 에 대한 json 데이터를 사전 검증할 수 있습니다. (당연히 문제가 있는 요청 자체를 legacy 로 보내지 않고 안정적으로 보호하는데 그 목적이 있습니다.)

좀 더 보강해서 예를 들면 요청의 body 에 loanAmount 라는 값은 대출 금액이라 양의 정수의 값이 들어와야 합니다. 이를 어떤 사용자들이 or 악의적이거나 잘못된 요청에 의해서 음수로 들어오는 것을 json 형태라고 해도 Swagger 2.0 표준을 이용해서 스키마를 정의하고 사전에 검증할 수 있습니다.

APIC 관리콘솔에 해당 API 로 들어가서 하단과 같이 요청에 대한 정의를 작성합니다. (이전 강좌에서 파라미터로 받는 3개의 변수를 json 요청의 body 에 들어온다고 가정하고 정의를 만든 것입니다.)

추 가 특성 허용을 on 한 후에 loanAmount 라는 특성의 조치의 <> 아이콘을 클릭하면 Swagger 2.0 표준에서 정의된 yaml 형태의 텍스트를 확인할 수 있습니다. 해당 정의에 양의 정수를 검증하기 위해 minimum:0 을 하단과 같이 추가합니다.

참고 : Swagger 표준을 확인해보면 스키마의 정의에 넣을 수 있는 minimum, maximum 과 같은 다양한 제한 조건을 하단과 같이 확인할 수 있습니다.

http://swagger.io/specification/

정 의를 통해서 요청에 대한 스키마를 작성했으면 이제 해당 테스트를 위해서 새로운 API 경로를 하단과 같이 생성합니다. 이전 강좌의 내용과 동일하게 경로를 ‘+’ 아이콘으로 추가하면 되며 요청의 유형만 방금전에 작성한 정의로 선택하시면 됩니다.

API 어셈블의 flow 에 operation-switch 에 방금 작성한 경로를 추가하고 스키마 검증을 위한 validate 컴포넌트와 호출을 위한 invoke 컴포넌트를 추가합니다.

여기서는 요청을 사전 검증할 것이므로 validate 컴포넌트를 클릭하여 정의를 request 로 선택합니다.

호출을 위한 invoke 컴포넌트를 클릭하여 하단의 내용을 URL 정보로 넣어줍니다. 이전 강좌와 다른 점은 json body 로 요청을 주기 때문에 파라미터를 request.body 변수 형태로 넣었다는 것입니다.
http://192.168.225.10:9071/loans/v1/quote?loanAmount=$(request.body.loanAmount)&annualInterestRate=$(request.body.annualInterestRate)&termInMonths=$(request.body.termInMonths)

이 제 이전과 같이 테스트를 수행해봅니다. 참고로 put 의 경우에는 스키마가 있으니 테스트시에 ‘생성’ 을 통해서 요청을 스키마에 맞추어서 자동 생성할 수 있으며 값만 변경해주면 됩니다. 이때 loanAmount 를 0보다 작은 음수로 넣고 테스트합니다.

해당 테스트를 정상적으로 수행하면 하단과 같이 validate 컴포넌트의 스키마 정의를 통해서 사전 검증에 걸려 400 Invalid Error 가 발생한 것을 확인 가능합니다.

validate
https://www.ibm.com/support/knowledgecenter/en/SSMNED_5.0.0/com.ibm.apic.toolkit.doc/rapim_ref_ootb_policyschemaval.html

 
4) json-to-xml 컴포넌트

json to xml 컴포넌트도 역시 이름 그대로 단순하게 json 응답을 xml 형태로 변경하는 컴포넌트를 의미합니다.

API 어셈블 디자이너에서 json-to-xml 컴포넌트를 invoke 컴포넌트 뒤에 추가합니다.

기존에 있던 invoke 컴포넌트의 ‘Response object value’ 항목의 지정된 변수명을 삭제하여 그대로 응답으로 반환하게 합니다.

 
다음으로 json-to-xml 컴포넌트는 수정없이 기본값으로 설정합니다.

위와 같이 하고 테스트를 수행하면 하단과 같이 동일 요청에 대한 동일 응답을 json 형태가 아닌 xml 형태로 받는 것을 확인할 수 있습니다.

 
json-to-xml
https://www.ibm.com/support/knowledgecenter/en/SSMNED_5.0.0/com.ibm.apic.toolkit.doc/rapim_ref_ootb_policyjson2xml.html

 
5) redact 컴포넌트

redact 컴포넌트는 API Connect 입장에서는 쓰임새가 많은 컴포넌트인데 해당 컴포넌트는 손쉽게 요청이나 응답의 특정 필드를 제거하거나 수정하는 역할을 수행합니다. 예를 들어 법적, 보안 또는 기타 이유로 인해 민감한 데이터(예: 신용카드 세부사항)를 제거하거나 차단하는 데 이 정책이 유용할 수 있습니다.

예를 들어 이전까지 테스트한 내용에서 보안상의 이슈로 이자율인 annualInterestRate 정보가 응답으로 나가야 하지 않는다면 redact 컴포넌트 추가로 해당 기능을 바로 구현할 수 있습니다.

redact 컴포넌트를 클릭하여 XPath 형태로 Path( “//*[@name='annualInterestRate']” : name 이 annualInterestRate 인 위치)를 넣은후에 Action 으로 ‘제거’를 선택합니다. 마지막으로 개정 위치를 ‘response’ 를 선택하면 됩니다.

이렇게 redact 컴포넌트를 추가한 후 테스트를 해보면 하단과 같이 기존 응답에서 annualInterestRate 가 제외된 채 응답으로 나오는 것을 확인할 수 있습니다.

redact
https://www.ibm.com/support/knowledgecenter/en/SSMNED_5.0.0/com.ibm.apic.toolkit.doc/rapim_ref_ootb_policyredaction.html

APIC5_guide_04_Assemble2_juwlee201606_v1.pdf

 
9) 참고 자료

1.    IBM API Connect 5.0 온라인 메뉴얼(Knowledge Center) – 한글 제공
https://www.ibm.com/support/knowledgecenter/ko/SSMNED_5.0.0/mapfiles/ic_home.html

2.    The Assemble view - IBM API Connect 5.0 온라인 메뉴얼
https://www.ibm.com/support/knowledgecenter/en/SSMNED_5.0.0/com.ibm.apic.toolkit.doc/capim_assembly_ui.html