사용자 정의 정책(User-defined policy) 생성하기

IBM API Management v4.0
사용자 정의 정책(User-defined policy) 생성하기

1) 사용자 정의 정책(User-defined policy) 생성하기

0. 참고 링크 :
Creating a new user-defined policy
http://www-01.ibm.com/support/knowledgecenter/SSWHYP_4.0.0/com.ibm.apimgmt.policy.doc/capim_define_custpolicies.html?lang=ko

이번 강좌는 지난 강좌에 의해서 사용자 정의 정책 생성하기에 대해서 다루도록 하겠습니다. 가급적 이번 강좌는 지난 강좌인 사용자 정의 정책 사용하기 부터 읽고 나서 읽기를 권장드립니다.
(http://www.websphere.pe.kr/xe/new_lecture/54987)

1. Datapower 로 로그인 한 후에 APIM 도메인이 아닌 비어있는 도메인으로 들어가서 Processing Rule 메뉴를 선택한 후에 Add 버튼을 클릭합니다. (또는 새로운 도메인을 하나 생성해도 됩니다.)

 
2. 새로운 Processing Rule 의 이름을 설정하고 (이름의 마지막은 반드시 main 으로 끝나야 합니다.) JSON 처리를 위해서 Non-XML Processing 을 on 으로 변경한 후 Rule Action 을 추가하기 위하여 ‘+’ 버튼을 클릭합니다.

3. Processing Action 을 하나 만듭니다. 이때 Input/Output 은 변경하는 것이 없기 때문에 그냥 다 NULL 을 입력하면 됩니다. Transform File 에는 실제 프로세스에서 사용될 XSLT 파일의 경로를 넣어둡니다. 예를들어 local:///policy/param-validata/payload.xsl 과 같은 형태로 입력하고 Apply 하면 됩니다. (참고적으로 해당 xsl 파일의 위치는 반드시 local:///policy/정책이름폴더/ 하위여야 합니다.) 

4. 해당 Processing Rule 에 정상적으로 Rule Action 이 추가된 것을 확인하면 Apply 를 클릭하여 저장하면 됩니다. (참고로 하나의 Action 이 아니라 여러 Action 이 수행되어야 하는 경우 방금 전에 했던 형태로 추가적인 Rule Action 을 더 넣을 수 있으며 순서지정도 가능합니다.)

5. URL parameter 의 정규식 비교를 위한 xsl 을 하나 작성하고 그 이름을 payload.xsl 로 저장해둡니다.
(xsl 에 대한 설명은 주석을 참고하시기 바라며 xslt 표준형태만 준수하면 원하는 어떤 형태의 프로그래밍도 가능합니다.)

payload.xsl
<!-- xmlns:regexp 는 정규식을 사용하기 위한 name space -->
<xsl:stylesheet version="1.0"
     xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
     xmlns:apim="http://www.ibm.com/apimanagement"
     xmlns:dp="http://www.datapower.com/extensions"
     extension-element-prefixes="dp"
     exclude-result-prefixes="dp apim"
     xmlns:regexp="http://exslt.org/regular-expressions"
>
  <!-- Contains the APIM functions -->
  <xsl:include href="local:///isp/policy/apim.custom.xsl" />
 
  <xsl:template match="/">
   
    <!-- Retrieves node-set containing all Policy properties - APIM 의 설정 정보들을 가지고 오는 부분 -->
    <xsl:variable name="properties" select="apim:policyProperties()" />

    <!-- parameter 정보 error log 로 출력 (향후 정상이면 지워도 상관없음) -->
     <xsl:message dp:priority="error">
        The value of my input property is
        <xsl:value-of select="$properties/parameterURL" />, <xsl:value-of select="$properties/regularExp" />
      </xsl:message>
         
    <!-- URL 정보 가지고 오기 -->
    <xsl:variable name="inurl" select="dp:variable('var://service/URL-in')"/>
   
    <!-- URL 정보에서 APIM 에서 설정한 parameter parsing -->
      <xsl:variable name="parameters" select="substring-after($inurl, '?')" />
      <xsl:variable name="parameter1" select="substring-after($parameters, concat($properties/parameterURL, '='))" />
 
      <xsl:variable name="parameter">
      <!-- parameter 에서 뒤에 & 가 있으면 그 앞까지 자르기 없다면 그냥 반환 -->
      <xsl:choose>
        <xsl:when test="contains($parameter1,'&amp;')">
           <xsl:value-of select="substring-before($parameter1, '&amp;')"/>
        </xsl:when>
        <xsl:otherwise>
           <xsl:value-of select="$parameter1"/>
        </xsl:otherwise>
      </xsl:choose>
      </xsl:variable>
     
      <!-- 비교 구문 -->
      <xsl:choose>
          <!-- 정규식 비교시 true 면 아무런 action 을 취하지 않음(서비스 지속) -->
          <xsl:when test="regexp:test($parameter, $properties/regularExp)">
          </xsl:when>
          <!-- 정규식 비교시 false 면 error 를 call 함 -->
          <xsl:otherwise>
              <!-- now that we've collected the reason, tell the framework -->
              <xsl:call-template name="apim:error">
                <xsl:with-param name="httpCode" select="'500'" />
                <xsl:with-param name="httpReasonPhrase" select="'Invalid parameter'" />
                <xsl:with-param name="errorMessage" select="concat('parameter validation failed with ', $properties/parameterURL, '=', $parameter, ' and ', $properties/regularExp)" />
              </xsl:call-template>
          </xsl:otherwise>
     </xsl:choose>  
 
  </xsl:template>
</xsl:stylesheet>

6. 방금 만든 payload.xsl 파일을 Process Action 을 만들때 지정한 위치에 폴더를 새로 생성하여 넣어줍니다. Datapower 시작화면의 File Management 를 클릭하여 파일 관리자가 나오면 local 폴더는 기본으로 있으며 Action 에서 Create Subdirectory 를 클릭하여 폴더를 만들고 해당 파일을 업데이트 해 둡니다.

7. 이제 사용자 정의 정책에 대한 준비가 완료되었으니 Datapower 의 관리콘솔 맨 처음 화면에서 Export 를 클릭한 후 Process Rule 을 선택하여 방금 작성한 정책을 다운로드 받습니다. 만약 show content 메뉴를 클릭해서 내부를 보면 하단과 유사하게 나와야 합니다.

8. 향후 APIM 메뉴에 추가될 기능을 yaml 파일 형태로 param-validate.yaml 로 만듭니다. yaml 파일 양식은 온라인 메뉴얼을 참고하시면 됩니다. (yaml 파일은 워낙 직관적이라 그냥 읽어보셔도 의미를 알 수 있으며 샘플은 메뉴에서 간단하게 파라미터 두개를 받는 yaml 파일입니다.)

Describing your policy
http://www-01.ibm.com/support/knowledgecenter/SSWHYP_4.0.0/com.ibm.apimgmt.policy.doc/tapim_creating_policy.html?lang=ko

param-validate.yaml
policy: 1.0.0

info:
  title: Param Validation
  name: param-validate
  version: 1.0
  description: Validate message using a JSON schema.
  contact:
    name: IBM DataPower Samples
    url: https://github.com/ibm-datapower/
    email: steve-product-manager@ibm.com

attach:
  - rest

properties:
  $schema: "http://json-schema.org/draft-04/schema#"
  type: object
  properties:
    parameterURL:
      label: "parameter URL"
      description: "The name of the URL parameter which will be validated by Regular Expression"
      type: string
    regularExp:
      label: "regular Express"
      description: "The regular expression to validate the URL parameter"
      type: string
  required:
    - parameterURL
    - regularExp

9. 만들어둔 파일을 다 모으고 param-validate-policy 폴더를 하나 만듭니다. (기존에 다운로드 받은 export.zip 파일의 이름을 param-validate.zip 으로 변경합니다.)

10. param-validte-policy 폴더의 하위에 validator 폴더와 implementation 폴더를 만들어 둡니다. 그리고 param-validate.yaml 파일은 param-validte-policy 폴더 밑에 두고 Datapower 에서 다운받은 Processing rule 관련 param-validate.zip 파일은 implementation 폴더 하위에 둡니다. (validator 폴더는 비어 있으면 되며 payload.xsl 은 param-validate.zip 에 이미 들어가 있으므로 여기서 사용하지 않습니다.)

11. 해당 폴더구조가 완성되면 하단과 같이 param-validte-policy 폴더를 param-validte-policy.zip 파일로 압축합니다.

이렇게 하면 사용자 정의 정책을 추가하기 위한 기본 사용자 정의 정책 패키지 정보가 완성된 것입니다.

12. APIM 콘솔 화면으로 접속하여 Environment 메뉴를 클릭후에 policies 를 선택하여 지금 만든 사용자 정책을 추가합니다.

13. 정상적으로 추가되면 하단과 같이 사용자 정의 정책이 추가된 것을 확인할 수 있습니다. 

2) 사용자 정의 정책(User-defined policy) 테스트 하기

테스트를 위해서는 아무 API 나 사용하셔도 무방하며 여기서는 이전 첫번째 강좌에서 사용했던 단순한 JSON GET 호출 API 를 활용해서 진행하도록 하겠습니다. 잘 기억이 안나시는 분들은 하단의 링크를 참고하시기 바라겠습니다.

[APIM]IBM API Management 를 활용하여 API 작성(등록) 하기
http://www.websphere.pe.kr/xe/new_lecture/51374

1. 구현되어 있는 API 로 가서 Implementation 을 다 지우고 ‘+’ 버튼을 클릭한 후 이번에 추가한 사용자 정의 정책인 Param Validation 을 선택합니다. 

2. 파라미터가 두 개 나오는데 parameter URL 에는 보고자 하는 URL parameter 를 넣어주면 되며 두 번째의 regular Express 에는 해당 파라미터를 검증할 정규식을 하단과 같이 넣어주면 됩니다.

(예: “^([1-9]|[1-9][0-9]|[1-9][0-9][0-9])$” - 0 에서 999 까지의 숫자)

3. 다음으로 ‘+’ 버튼을 클릭하여 Proxy 를 선택하고 실제 호출될 URL 을 선언합니다. 해당 작업이 완료되면 해당 API 를 저장하고 배포하면 됩니다. 

4. API 에서 테스트를 선택하고 파라미터를 입력합니다. 이때 loanAmount 는 이전에 넣어둔 정규식에 적합하도록 3자리 숫자를 넣어줍니다.

5. 해당 API 를 테스트 호출하면 하단과 같이 200 OK 정상적인 결과를 얻을 수 있습니다. 

6. 이번에는 loanAmunt 파라미터가 정규식을 어긋나도록 3자리가 아닌 4자리의 숫자를 넣어놓고 테스트를 진행해 봅니다.

7. 위와 같이 입력한 상태에서 테스트 호출을 수행하면 파라미터가 주어진 정규식에 어긋나므로 실제 서비스가 이루어지지 않고 하단과 같이 ‘500 Invalid parameter’ 라는 Exception 이 발생하는 것을 확인할 수 있습니다.

이렇게 하시면 APIM 의 사용자 정의 정책을 처음부터 생성하시고 적용한 후에 테스트까지 성공적으로 마치신 것입니다.


팁 #1: 강좌에서 만들어서 사용하는 URL Parameter 에 대한 정규식 검증에 대한 사용자 정의 정책은 원하신다면 중복 선언을 통해서 여러 파라미터를 동시에 검증 가능합니다. 

팁 #2: 변환에 관련된 xslt 를 계속 수정해야 할 경우 매번 사용자 정의 정책을 재배포 할 필요없이 해당 APIM 도메인의 지정된 폴더(local:///policy/지정된 이름) 에 보면 배포된 해당 xsl 파일을 하단과 같이 확인할 수 있고 edit 버튼을 클릭하여 바로 수정할 수 있습니다. 이를 이용해서 수정 및 테스트 하는 것이 보다 효율적입니다.

팁 #3: 여러개의 Processing Action 을 포함하는 경우에는 dummy processing policy 를 하나 만들어서 Multi-Protocol Gateway 로 확인하면 GUI 형태로 조금은 더 손쉽게 Action 수정/추가가 가능합니다. 

APIM40_guide_UserDefinePolicy2_juwlee201602.pdf