메시지 템플릿

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

이 주제에서는 API 프록시에서 메시지 템플릿을 사용하는 방법과 함수 참조를 제공합니다.

메시지 템플릿이란 무엇인가요?

메시지 템플릿을 사용하면 특정 정책 및 <TargetEndpoint> 요소에서 변수 문자열 대체를 수행할 수 있습니다. 이 기능이 지원되는 경우 프록시가 실행될 때 문자열을 동적으로 채울 수 있습니다.

메시지 템플릿에 흐름 변수 참조와 리터럴 텍스트의 모든 조합을 포함할 수 있습니다. 흐름 변수 이름은 중괄호로 묶어야 하며, 중괄호로 묶이지 않은 텍스트는 리터럴 텍스트로 출력됩니다.

메시지 템플릿을 사용할 수 있는 위치도 참조하세요.

예시

예를 들어 AssignMessage 정책을 사용하면 <Payload> 요소 내에 메시지 템플릿을 사용할 수 있습니다.

<AssignMessage name="set-dynamic-content">
  <AssignTo createNew="false" type="response"></AssignTo>
  <Set>
    <Payload contentType="application/json">
      {"name":"Alert", "message":"You entered an invalid username: {user.name}"}
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

위의 예시에서 흐름 변수 user.name의 값(중괄호)이 평가되어 런타임 시 페이로드 문자열로 대체됩니다. 예를 들어 user.name=jdoe이면 페이로드의 결과 메시지 출력은 You entered an invalid username: jdoe입니다. 변수를 확인할 수 없는 경우에는 빈 문자열이 출력됩니다.

예시

할당량을 초과하면 호출자에게 유의미한 메시지를 반환하는 것이 좋습니다. 이 패턴은 일반적으로 '오류 규칙'과 함께 사용되어 호출자에게 할당량 위반에 대한 정보를 제공하는 출력을 제공합니다. 다음 AssignMessage 정책의 메시지 템플릿은 여러 XML 요소에 할당량 정보를 동적으로 채우는 데 사용됩니다.

<AssignMessage name='AM-QuotaViolationMessage'>
  <Description>message for quota exceeded</Description>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <Set>
    <Headers>
      <Header name='X-Quota-Reset'>{ratelimit.Quota-1.expiry.time}</Header>
      <Header name='X-Quota-Allowed'>{ratelimit.Quota-1.allowed.count}</Header>
      <Header name='X-Quota-Available'>{ratelimit.Quota-1.available.count}</Header>
    </Headers>
    <Payload contentType='application/json'>{
  "error" : {
    "message" : "you have exceeded your quota",
    "clientId" : "{request.queryparam.apikey}"
  }
}
    </Payload>
    <StatusCode>429</StatusCode>
  </Set>
</AssignMessage>

AssignMessage 정책에서 <Set> 요소의 다음 요소는 메시지 템플릿을 지원합니다.

  • <Header>
  • <QueryParam>
  • <FormParam>
  • <PayLoad>
  • <Version>
  • <Verb>
  • <Path>
  • <StatusCode>

다시 말하지만 메시지 템플릿의 흐름 변수는 중괄호로 묶어야 합니다.

이 정책이 실행되면 다음이 수행됩니다.

  • <Header> 요소가 지정된 흐름 변수의 값을 수신합니다.
  • 페이로드에 리터럴 텍스트와 변수의 혼합이 포함됩니다(client_id가 동적으로 채워짐).
  • <StatusCode>에는 리터럴 텍스트만 포함됩니다. 그러나 이 요소는 사용하려는 경우 메시지 템플릿도 지원합니다.

예시

프록시 <TargetEndpoint> 정의에서 <SSLInfo>의 하위 요소는 메시지 템플릿을 지원합니다. 정책에 사용된 것과 동일한 패턴을 따라 프록시가 실행될 때 중괄호 안의 흐름 변수가 대체됩니다.

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <SSLInfo>
        <Enabled>{myvars.ssl.enabled}</Enabled>
        <ClientAuthEnabled>{myvars.ssl.client.auth.enabled}</ClientAuthEnabled>
        <KeyStore>{myvars.ssl.keystore}</KeyStore>
        <KeyAlias>{myvars.ssl.keyAlias}</KeyAlias>
        <TrustStore>{myvars.ssl.trustStore}</TrustStore>
    </SSLInfo>
  </HTTPTargetConnection>
  ...
</TargetEndpoint>

메시지 템플릿을 사용할 수 있는 위치

메시지 템플릿은 여러 정책과 TargetEndpoint 구성에서 사용되는 특정 요소에서 지원됩니다.

메시지 템플릿을 허용하는 정책

다음 표에는 정책과 지원되는 요소/하위 요소가 나와 있습니다.

정책 요소/하위 요소
AccessControl 정책 mask 속성 및 IP 주소의 경우 <SourceAddress>.
AssignMessage 정책 <Set> 하위 요소: Payload, ContentType, Verb, Version, Path, StatusCode, Headers, QueryParams, FormParams

<Add> 하위 요소: Headers, QueryParams, FormParams

<AssignVariable> 하위 요소: <Template>

CORS 정책

<AllowHeaders>

<AllowMethods>

<AllowOrigins>

<ExposeHeaders>
ExtractVariables 정책 <JsonPath>
GenerateJWS 정책
VerifyJWS 정책

<Payload>(GenerateJWS 정책만 해당)

<AdditionalHeaders><Claim>

* 이 요소는 type=map인 경우에만 메시지 템플릿을 지원합니다.
GenerateJWT 정책
VerifyJWT 정책		 <AdditionalClaims><Claim>

<AdditionalHeaders><Claim>

* 이 요소는 type=map인 경우에만 메시지 템플릿을 지원합니다.
HTTPModifier 정책 <Set> 하위 요소:
  • <ContentType>
  • <Verb>
  • <Version>
  • <Path>
  • <StatusCode>
  • <Headers>
  • <QueryParams>
  • <FormParams>

<Add> 하위 요소:

  • <Headers>
  • <QueryParams>
  • <FormParams>
MessageLogging 정책

<CloudLogging><Message>

<Syslog><Message>

<File><Message>
OASValidation 정책 <OASResource> 요소
RaiseFault 정책

<Set> 요소:

  • <ContentType>
  • <FormParams>
  • <Headers>
  • <QueryParams>
  • <StatusCode>
  • <Path>
  • <Payload>
  • <Verb>
  • <Version>

<Add> 요소:

  • <FormParams>
  • <Headers>
  • <QueryParams>
SAMLAssertion 정책 <Template>

* 정책 서명이 <GenerateSAMLAssertion>인 경우에만
ServiceCallout 정책

<Set> 요소:

  • <ContentType>
  • <FormParams>
  • <Headers>
  • <QueryParams>
  • <StatusCode>
  • <Path>
  • <Payload>
  • <Verb>
  • <Version>

<Add> 요소:

  • <FormParams>
  • <Headers>
  • <QueryParams>

<HTTPTargetConnection>/<URL>: URL 템플릿을 참조하세요.

메시지 템플릿을 허용하는 <TargetEndpoint> 요소

<HTTPTargetConnection> 요소 메시지 템플릿을 지원하는 하위 요소
<SSLInfo> <Enabled>, <KeyAlias>, <KeyStore>, <TrustStore>, <ClientAuthEnabled>, <CLRStore>
<LocalTargetConnection> <ApiProxy>, <ProxyEndpoint>, <Path>
<Path> 해당 사항 없음
<URL> 하위 요소가 없습니다. 사용법은 URL 템플릿을 참조하세요.

메시지 템플릿 구문

이 섹션에서는 메시지 템플릿을 사용하기 위해 따라야 하는 규칙을 설명합니다.

중괄호를 사용하여 변수 나타내기

변수 이름을 중괄호({ })로 묶습니다. 변수가 없으면 출력에 빈 문자열이 반환됩니다. 하지만 메시지 템플릿에 기본값을 지정할 수 있습니다(변수가 확인되지 않은 경우 대체되는 값). 메시지 템플릿의 기본값 설정을 참조하세요.

전체 메시지 템플릿 문자열을 따옴표로 묶는 것은 허용되지만 선택사항입니다. 예를 들어 다음 메시지 템플릿 두 개는 동일합니다.

<Set>
  <Headers>
    <Header name="x-h1">"Hello {user.name}"</Header>
    <Header name="x-h1">Hello {user.name}</Header>
  </Headers>
</Set>

함수 표현식에 공백이 허용되지 않음

메시지 템플릿 함수 표현식에는 공백이 허용되지 않습니다. 예를 들면 다음과 같습니다.

허용되는 유형:

{substring(alpha,0,4)}
{createUuid()}
{randomLong(10)}

허용되지 않는 유형: 

{substring( alpha, 0, 4 )}
{ createUuid( ) }
{randomLong( 10 )}

중첩 함수는 지원되지 않습니다.

템플릿에서 다른 함수 내의 함수 호출은 지원되지 않습니다. 예를 들어 다음을 사용할 수 없습니다. 

{substring({timeFormat('yyyy-MM-dd','1494390266')},0,4)}

템플릿 함수에서 문자열 리터럴을 작은따옴표로 묶기

함수에 문자열 리터럴을 제공할 때는 큰따옴표 대신 작은따옴표로 묶습니다.

예를 들면 다음과 같습니다. 
{replaceAll('BEARER: 1234','^Bearer ','TOKEN:')}

문자열 리터럴에 특수 문자 사용 방지

문자열 리터럴에 ':', '/', '\', '<', '>'과 같은 특수 문자를 사용하지 마세요. 이러한 문자는 오류를 일으킬 수 있습니다. 문자열 리터럴에 특수 문자가 필요하면 Python 또는 JavaScript 정책을 사용해서 변수에 값을 할당한 후 템플릿에 변수를 사용합니다.

메시지 템플릿의 기본값 설정

템플릿 변수를 확인할 수 없는 경우 Apigee는 빈 문자열을 대체합니다. 그러나 다음과 같이 기본값을 지정할 수 있습니다.

<Header name="x-h1">Test message. id = {request.header.id:Unknown}</Header>

위 샘플에서 request.header.id 변수를 확인할 수 없는 경우 해당 값은 Unknown으로 대체됩니다. 예를 들면 다음과 같습니다.

Test message. id = Unknown

URL 템플릿

URL 요소는 다른 요소와 동일한 구문을 따르는 템플릿 지정을 지원합니다.

이 예시는 변수를 사용하여 구성된 URL을 보여줍니다.

<URL>{targeturl}</URL>

이 예시는 프로토콜의 기본값을 보여줍니다.

<URL>{protocol:https}://{site:google.com}/path</URL>

JSON 페이로드의 기존 구문

Cloud 출시 버전 16.08.17 이전에는 Apigee 버전에서 중괄호를 사용하여 JSON 페이로드 내에서 변수 참조를 나타낼 수 없었습니다. 이전 버전에서는 다음과 같이 구분 기호 문자를 지정하고 변수 이름을 래핑하기 위해 variablePrefix 및 variableSuffix 속성을 사용해야 했습니다.

<Set>
  <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
    {"name":"foo","type":"@variable_name#"}
  </Payload>
</Set>

Apigee에서는 최신 중괄호 구문을 사용하도록 권장하지만 이전 구문은 계속 작동합니다.

메시지 템플릿 함수 사용

Apigee는 아래에 설명된 것처럼 메시지 템플릿 내에서 문자열 변수의 이스케이프, 인코딩, 해시, 형식 지정에 사용할 수 있는 함수 모음을 제공합니다.

예: toLowerCase()

기본 제공 toLowerCase() 함수를 사용하여 문자열 변수를 소문자로 변환합니다.

<AssignMessage name="AM-Set-Custom-Response">
  <AssignTo createNew="false" type="response"/>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Set>
    <Headers>
      <Header name="x-h1">Test header: {toLowerCase(foo.bar:FOO)}</Header>
    </Headers>
  </Set>
</AssignMessage>

foo.bar 흐름 변수가 확인될 경우 해당 문자는 모두 소문자입니다. foo.bar가 확인되지 않을 경우 기본값 FOO이 대체되고 소문자로 변환됩니다. 예를 들면 다음과 같습니다.

Test header: foo

예: escapeJSON()

흥미로운 사용 사례는 다음과 같습니다. 백엔드 앱이 유효한 이스케이프 문자를 포함하는 JSON 응답을 반환한다고 가정해 보겠습니다. 예를 들면 다음과 같습니다.

{
  "code": "INVALID",
  "user_message": "Invalid value for \"logonId\" check your input."
}

그런 다음 이 메시지를 커스텀 페이로드의 클라이언트 호출자에게 반환한다고 가정해 보겠습니다. 일반적인 방법은 대상 응답 페이로드에서 메시지를 추출하고 AssignMessage를 사용하여 커스텀 프록시 응답에 추가하는 것입니다(즉, 클라이언트로 다시 전송).

user_message 정보를 standard.systemMessage라는 변수로 추출하는 ExtractVariables 정책은 다음과 같습니다.

<ExtractVariables name="EV-BackendErrorResponse">
  <DisplayName>EV-BackendErrorResponse</DisplayName>
  <JSONPayload>
    <Variable name="standard.systemMessage">
      <JSONPath>$.user_message</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

다음은 추출된 변수를 응답 페이로드(프록시 응답)에 추가하는 완전히 유효한 AssignMessage 정책입니다.

<AssignMessage name="AM-SetStandardFaultResponse">
  <DisplayName>AM-SetStandardFaultResponse</DisplayName>
  <Set>
    <Payload contentType="application/json">
     {
       "systemMessage": "{standard.systemMessage}"
     }
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

그러나 문제가 있습니다. ExtractVariables 정책은 메시지의 일부에서 이스케이프 처리된 따옴표를 삭제했습니다. 즉, 클라이언트에 반환된 응답은 유효하지 않은 JSON입니다. 이는 의도한 결과가 아닙니다.

{
  "systemMessage": "Invalid value for "logonId" check your input."
}

이 문제를 해결하기 위해 AssignMessage 정책을 수정하여 JSON 내에서 따옴표를 이스케이프 처리하는 메시지 템플릿 함수를 사용할 수 있습니다. 이 함수 escapeJSON()은 JSON 표현식 내에서 발생하는 따옴표 또는 기타 특수문자를 이스케이프 처리합니다. 

<AssignMessage name="AM-SetStandardFaultResponse">
  <DisplayName>AM-SetStandardFaultResponse</DisplayName>
  <Set>
    <Payload contentType="application/json">
     {
       "systemMessage": "{escapeJSON(standard.systemMessage)}"
     }
    </Payload>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

이 함수는 삽입된 따옴표를 이스케이프 처리하여 유효한 JSON을 생성하므로 원하는 결과를 제공합니다.

{
  "systemMessage": "Invalid value for \"logonId\" check your input.",
}

메시지 템플릿은 특정 정책 및 <TargetEndpoint> 정의에서 사용할 수 있는 동적 문자열 대체 기능입니다. 메시지 템플릿 함수를 사용하면 메시지 템플릿 내에서 해싱, 문자열 조작, 문자 이스케이프 처리 등의 유용한 작업을 수행할 수 있습니다.

예를 들어 다음 AssignMessage 정책에서는 toLowerCase() 함수가 메시지 템플릿에 사용됩니다.

<AssignMessage name="AM-Set-Custom-Response">
  <AssignTo createNew="false" type="response"/>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <Set>
   <Headers>
     <Header name="x-h1">Test header: {Hello,toLowerCase(user.name)}</Header>
   </Headers>
  </Set>
</AssignMessage>

이 섹션에서는 메시지 템플릿 함수, 인수, 출력을 설명합니다. 이 주제에서는 메시지 템플릿과 메시지 템플릿이 사용되는 컨텍스트에 익숙하다고 가정합니다.

해시 함수

해시 값을 계산하고 해당 해시의 문자열 표현을 반환합니다.

16진수 해시 함수

해시 값을 계산하고 해당 해시의 문자열 표현을 16진수로 반환합니다.

구문

함수 설명
md5Hex(string) 16진수로 표현된 MD5 해시를 계산합니다.
sha1Hex(string) 16진수로 표현된 SHA1 해시를 계산합니다.
sha256Hex(string) 16진수로 표현된 SHA256 해시를 계산합니다.
sha384Hex(string) 16진수로 표현된 SHA384 해시를 계산합니다.
sha512Hex(string) 16진수로 표현된 SHA512 해시를 계산합니다.

인수

string: 해시 함수는 해시 알고리즘이 계산되는 단일 문자열 인수를 사용합니다. 인수는 리터럴 문자열(작은따옴표로 묶음) 또는 문자열 흐름 변수일 수 있습니다.

예시

함수 호출:

sha256Hex('abc')

결과:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

함수 호출:

var str = 'abc';
sha256Hex(str)

결과:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Base64 해시 함수

해시 값을 계산하고 해당 해시의 문자열 표현을 Base64로 인코딩된 값으로 반환합니다.

구문

함수 설명
md5Base64(string) Base64로 인코딩된 값으로 표현된 MD5 해시를 계산합니다.
sha1Base64(string) Base64로 인코딩된 값으로 표현된 SHA1 해시를 계산합니다.
sha256Base64(string) Base64로 인코딩된 값으로 표현된 SHA256 해시를 계산합니다.
sha384Base64(string) Base64로 인코딩된 값으로 표시된 SHA384 해시를 계산합니다.
sha512Base64(string) Base64로 인코딩된 값으로 표현된 SHA512 해시를 계산합니다.

인수

string: 해시 함수는 해시 알고리즘이 계산되는 단일 문자열 인수를 사용합니다. 인수는 리터럴 문자열(작은따옴표로 묶음) 또는 문자열 흐름 변수일 수 있습니다.

예시

함수 호출: 

sha256Base64('abc')

결과:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

함수 호출: 

var str = 'abc';
sha256Base64(str)

결과:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

문자열 함수

메시지 템플릿 내에서 문자열에 대한 작업을 수행합니다.

Base64 인코딩 함수

Base64 인코딩 스키마를 사용하여 문자열을 인코딩하고 디코딩합니다.

구문

함수 설명
encodeBase64(string) Base64 인코딩을 사용하여 문자열을 인코딩합니다. 예를 들면 encodeBase64(value)입니다. value에 abc가 있으면 함수는 YWJj 문자열을 반환합니다.
decodeBase64(string) Base64로 인코딩된 문자열을 디코딩합니다. 예를 들면 decodeBase64(value)입니다. value에 aGVsbG8sIHdvcmxk가 있으면 함수는 hello, world 문자열을 반환합니다.

인수

string: 인코딩하거나 디코딩하는 문자열입니다. 리터럴 문자열(작은따옴표로 묶음) 또는 문자열 흐름 변수일 수 있습니다.

예시

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
       <Headers>
         <Header name="x-h1">Hello, {decodeBase64('d29ybGQK')}</Header>
       </Headers>
    </Set>
</AssignMessage>

대소문자 변환 함수

문자열을 모두 대문자 또는 모두 소문자로 변환합니다.

구문

함수 설명
toUpperCase(string) 문자열을 대문자로 변환합니다.
toLowerCase(string) 문자열을 소문자로 변환합니다.

인수

string: 변환할 문자열입니다. 리터럴 문자열(작은따옴표로 묶음) 또는 문자열 흐름 변수일 수 있습니다.

예시

<AssignMessage name="AM-Set-Custom-Response">
    <AssignTo createNew="false" type="response"/>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <Set>
       <Headers>
         <Header name="x-h1">Hello, {toLowerCase(user.name)}</Header>
       </Headers>
    </Set>
</AssignMessage>

Substring 함수

지정된 문자열의 시작 색인과 끝 색인 사이에 있는 문자를 반환합니다.

구문

substring(str,start_index,end_index)

인수

  • str: 리터럴 문자열(작은따옴표로 묶음) 또는 문자열 흐름 변수입니다.
  • start_index: 문자열의 시작 색인입니다.
  • end_index: (선택사항) 문자열의 끝 색인입니다. 제공되지 않으면 끝 색인은 문자열의 끝입니다.

예시

다음 예시에서는 이러한 흐름 변수가 있다고 가정합니다.

변수 이름 값
alpha ABCDEFGHIJKLMNOPQRSTUVWXYZ
seven 7


이러한 변수를 사용하는 함수 호출의 결과는 다음과 같습니다.

메시지 템플릿 표현식 결과
{substring(alpha,22)} WXYZ
hello {substring(alpha,22)} hello WXYZ
{substring(alpha,-4)} WXYZ
{substring(alpha,-8,-4)} STUV
{substring(alpha,0,10)} ABCDEFGHIJ
{substring(alpha,0,seven)} ABCDEFG

모든 함수 대체

문자열에 정규 표현식을 적용하고 일치 항목의 경우 일치 항목을 대체 값으로 바꿉니다.

구문

replaceAll(string,regex,value)

인수

  • string - 대체할 리터럴 문자열(작은따옴표로 묶음) 또는 문자열 흐름 변수입니다.
  • regex - 정규 표현식입니다.
  • value - 문자열 내의 모든 정규식 일치 항목을 대체할 값입니다.

예시

다음 예에서는 이러한 흐름 변수가 있다고 가정합니다.

변수 이름 값
header Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
regex1 "^Bearer "
replacement "TOKEN: "

이러한 변수를 사용하는 함수 호출의 결과는 다음과 같습니다.

메시지 템플릿 표현식 결과
{replaceAll(header,'9993','')} Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZ-
{replaceAll(header,regex1,'')} ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993
{replaceAll(header,regex1,replacement)} TOKEN: ABCDEFGHIJKLMNOPQRSTUVWXYZ-9993

첫 번째 함수 대체

문자열에서 지정된 정규 표현식 일치 항목의 첫 번째 항목만 대체합니다.

구문

replaceFirst(string,regex,value)

인수

  • string: 대체할 리터럴 문자열(작은따옴표로 묶음) 또는 문자열 흐름 변수입니다.
  • regex: 정규 표현식입니다.
  • value: 문자열 내의 정규식 일치 항목을 대체할 값입니다.

문자 이스케이프 처리 및 인코딩 함수

문자열에서 특수문자를 이스케이프 처리하거나 인코딩하는 함수입니다.

구문

함수 설명
escapeJSON(string) 큰따옴표를 백슬래시로 이스케이프 처리합니다.
escapeXML(string) 꺾쇠 괄호, 아포스트로피, 큰따옴표, 앰퍼샌드를 해당 XML 항목으로 대체합니다. XML 1.0 문서에 사용합니다.
escapeXML11(string) escapeXML과 동일한 방식으로 작동하지만 XML v1.1 항목에 적용됩니다. 아래 사용 참고사항을 확인하세요.
encodeHTML(string) 아포스트로피, 꺾쇠 괄호, 앰퍼샌드를 인코딩합니다.

인수

string: 이스케이프 처리할 문자열입니다. 리터럴 문자열(작은따옴표로 묶음) 또는 문자열 흐름 변수일 수 있습니다.

사용 참고사항

XML 1.1은 특정 제어 문자를 나타낼 수 있지만 이스케이프 처리된 후 null 바이트 또는 페어링이 해제된 유니코드 서로게이트 코드 포인트를 나타낼 수 없습니다. escapeXML11() 함수는 다음 범위에 맞지 않는 문자를 삭제합니다.

[#x1-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]

escapeXML11() 함수는 다음 범위의 문자를 이스케이프 처리합니다.

[#x1-#x8] | [#xB-#xC] | [#xE-#x1F] | [#x7F-#x84] | [#x86-#x9F]

예시

값이 "bread" & "butter"인 food라는 흐름 변수가 있다고 가정합니다. 그런 다음 함수를 호출합니다.

{escapeHTML(food)}

결과:

&quot;bread&quot; &amp; &quot;butter&quot;

시간 형식 함수

UTC 형식의 시간 문자열 표현을 반환합니다.

구문

함수 설명
timeFormat(format,str)

UTC 형식의 날짜를 반환합니다.

DEPRECATED: 현지 시간대 형식의 날짜를 반환합니다.
timeFormatMs(format,str)

UTC 형식의 날짜를 반환합니다.

DEPRECATED: 현지 시간대 형식의 날짜를 반환합니다.
timeFormatUTC(format,str) UTC 형식의 날짜를 반환합니다.
timeFormatUTCMs(format,str) UTC 형식의 날짜를 반환합니다.

인수

  • format: 날짜/시간 형식 문자열입니다. 리터럴 문자열(작은따옴표로 묶음) 또는 문자열 변수일 수 있습니다. 형식에 콜론이 포함된 경우 리터럴 대신 변수를 사용합니다. 이 섹션의 이전 참고를 참조하세요.
  • str: 시간 값을 포함하는 문자열 또는 문자열 흐름 변수입니다. timeFormatMs의 값은 에포크 이후의 초 단위 또는 에포크 이후 밀리초 단위일 수 있습니다.

예시

다음 값을 가정하고 현지 시간대가 태평양 표준시라고 가정합니다.

  • epoch_time_ms = 1494390266000
  • epoch_time = 1494390266
  • fmt1 = yyyy-MM-dd
  • fmt2 = yyyy-MM-dd HH-mm-ss
  • fmt3 = yyyyMMddHHmmss

함수는 다음 결과를 반환합니다.

함수 출력
timeFormatMs(fmt1,epoch_time_ms) 2017-05-09
timeFormat(fmt1,epoch_time) 2017-05-09
timeFormat(fmt2,epoch_time) 2017-05-09 21:24:26
timeFormat(fmt3,epoch_time) 20170509212426
timeFormatUTC(fmt1,epoch_time) 2017-05-10
timeFormatUTC(fmt2,epoch_time) 2017-05-10 04:24:26
timeFormatUTC(fmt3,epoch_time) 20170510042426

HMAC 계산 함수

HMAC 계산 함수는 HMAC를 계산하는 데 HMAC 정책 대신 사용할 수 있습니다. HMAC 중 하나의 출력이 두 번째 HMAC의 키로 사용되는 것처럼, 이 함수는 단계식 HMAC 계산을 수행할 때 유용하게 사용됩니다.

구문

함수 설명
hmacSha224(key,valueToSign[,keyencoding[,outputencoding]]) SHA-224 해시 함수로 HMAC를 계산합니다.
hmacSha256(key,valueToSign[,keyencoding[,outputencoding]]) SHA-256 해시 함수로 HMAC를 인코딩합니다.
hmacSha384(key,valueToSign[,keyencoding[,outputencoding]]) SHA-384 해시 함수로 HMAC를 인코딩합니다.
hmacSha512(key,valueToSign[,keyencoding[,outputencoding]]) SHA-512 해시 함수로 HMAC를 인코딩합니다.
hmacMd5(key,valueToSign[,keyencoding[,outputencoding]]) MD5 해시 함수로 HMAC를 인코딩합니다.
hmacSha1(key,valueToSign[,keyencoding[,outputencoding]]) SHA-1 암호화 알고리즘으로 HMAC를 인코딩합니다.

인수

  • key - (필수) HMAC를 계산하는 데 사용되는 문자열로 인코딩된 보안 비밀 키를 지정합니다.
  • valueToSign - (필수) 서명할 메시지를 지정합니다. 문자열이어야 합니다.
  • keyencoding - (선택사항) 지정된 인코딩에 따라 보안 비밀 키 문자열이 디코딩됩니다. 유효한 값: hex, base16, base64, utf-8. 기본값: utf-8
  • outputencoding - (선택사항) 출력에 사용할 인코딩 알고리즘을 지정합니다. 유효한 값: hex, base16, base64. 값은 대소문자를 구분하지 않습니다. hex 및 base16은 동의어입니다. 기본값: base64

예시

이 예시에서는 AssignMessage 정책을 사용하여 HMAC-256을 계산하고 흐름 변수에 할당합니다. 

<AssignMessage name='AM-HMAC-1'>
  <AssignVariable>
    <Name>valueToSign</Name>
    <Template>{request.header.apikey}.{request.header.date}</Template>
  </AssignVariable>
  <AssignVariable>
    <Name>hmac_value</Name>
    <Template>{hmacSha256(private.secretkey,valueToSign)}</Template>
  </AssignVariable>
</AssignMessage>

이 예시에서는 AWS Signature v4 서명 프로세스에 사용할 수 있는 단계식 HMAC를 생성하는 방법을 보여줍니다. 이 예시에서는 AssignMessage 정책을 사용하여 AWS Signature v4의 서명을 계산하는 데 사용되는 5개 수준의 단계식 HMAC를 생성합니다. 

<AssignMessage name='AM-HMAC-AWS-1'>
  <!-- 1 -->
  <AssignVariable>
    <Name>DateValue</Name>
    <Template>{timeFormatUTCMs('yyyyMMdd',system.timestamp)}</Template>
  </AssignVariable>
  <!-- 2 -->
  <AssignVariable>
    <Name>FirstKey</Name>
    <Template>AWS4{private.secret_aws_access_key}</Template>
  </AssignVariable>
  <!-- 3 -->
  <AssignVariable>
    <Name>DateKey</Name>
    <Template>{hmacSha256(FirstKey,DateValue,'utf-8','base16')}</Template>
  </AssignVariable>
  <!-- 4 -->
  <AssignVariable>
    <Name>DateRegionKey</Name>
    <Template>{hmacSha256(DateKey,aws_region,'base16','base16')}</Template>
  </AssignVariable>
  <!-- 5 -->
  <AssignVariable>
    <Name>DateRegionServiceKey</Name>
    <Template>{hmacSha256(DateRegionKey,aws_service,'base16','base16')}</Template>
  </AssignVariable>
  <!-- 6 -->
  <AssignVariable>
    <Name>SigningKey</Name>
    <Template>{hmacSha256(DateRegionServiceKey,'aws4_request','base16','base16')}</Template>
  </AssignVariable>
  <!-- 7 -->
  <AssignVariable>
    <Name>aws4_hmac_value</Name>
    <Template>{hmacSha256(SigningKey,stringToSign,'base16','base16')}</Template>
  </AssignVariable>
</AssignMessage>

기타 함수

UUID 만들기 함수

UUID를 생성하고 반환합니다.

구문

createUuid()

인수

없음

예시

{createUuid()}

샘플 결과:

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

임의의 긴 값 생성기 함수

임의의 긴 정수를 반환합니다.

구문

randomLong(args)

인수

  • 인수를 지정하지 않으면 함수는 자바 SecureRandom 클래스로 계산된 임의의 긴 정수를 반환합니다.
  • 인수 중 하나가 있는 경우 계산의 최솟값으로 처리됩니다.
  • 두 번째 인수가 있는 경우 계산의 최댓값으로 처리됩니다.

예시

{randomLong()}

결과는 다음과 같습니다.

5211338197474042880

정규식 텍스트 생성기

지정된 정규 표현식과 일치하는 텍스트 문자열을 생성합니다.

구문

xeger(regex)

인수

regex: 정규 표현식입니다.

예시

이 예시에서는 0이 없는 7자리 문자열을 생성합니다.

xeger( '[1-9]{7}' )

결과 예시:

9857253

Null 병합 함수

firstnonnull() 함수는 null이 아닌 가장 왼쪽 인수의 값을 반환합니다.

구문

firstnonnull(var1,varn)

인수

var1: 컨텍스트 변수입니다.

varn: 하나 이상의 컨텍스트 변수입니다. 가장 오른쪽 인수를 문자열로 설정하여 대체 값을 제공할 수 있습니다. 왼쪽 인수가 설정되지 않을 경우 설정되는 값입니다.

예시

다음 표에서는 함수 사용 방법을 보여줍니다.

템플릿 Var1 Var2 Var3 결과
{firstnonnull(var1,var2)} 설정되지 않음 foo 해당 없음 foo
{firstnonnull(var1,var2)} foo bar 해당 없음 foo
{firstnonnull(var1,var2)} foo 설정되지 않음 해당 없음 foo
{firstnonnull(var1,var2,var3)} foo bar baz foo
{firstnonnull(var1,var2,var3)} 설정되지 않음 bar baz bar
{firstnonnull(var1,var2,var3)} 설정되지 않음 설정되지 않음 baz baz
{firstnonnull(var1,var2,var3)} 설정되지 않음 설정되지 않음 설정되지 않음 null
{firstnonnull(var1)} 설정되지 않음 해당 없음 해당 사항 없음 null
{firstnonnull(var1)} foo 해당 사항 없음 해당 사항 없음 foo
{firstnonnull(var1,var2)} "" bar 해당 없음 ""
{firstnonnull(var1,var2,'fallback value')} null null fallback value fallback value

XPath 함수

XML 변수에 XPath 표현식을 적용합니다.

구문

xpath(xpath_expression,xml_string[,datatype])

인수

xpath_expression: XPath 표현식입니다.

xml_string: XML을 포함하는 흐름 변수 또는 문자열입니다.

datatype: (선택사항) 원하는 쿼리 반환 유형을 지정합니다. 유효한 값은 nodeset, node, number, boolean, string입니다. 기본값은 nodeset입니다. 기본값은 일반적으로 적합합니다.

예시 1

다음 컨텍스트 변수가 XML 문자열과 XPath 표현식을 정의한다고 가정합니다.

xml = "<tag><tagid>250397</tagid><readerid>1</readerid><rssi>74</rssi><date>2019/06/15</date></tag>"
xpath = "/tag/tagid"

xpath() 함수는 다음과 같이 AssignMessage 정책에서 사용됩니다.

<AssignMessage>
  <AssignVariable>
    <Name>extracted_tag</Name>
    <Template>{xpath(xpath,xml)}</Template>
  </AssignVariable>
</AssignMessage>

이 함수는 <tagid>250397</tagid> 값을 반환합니다. 이 값은 extracted_tag라는 컨텍스트 변수에 배치됩니다.

예시 2: XML 네임스페이스

네임스페이스를 지정하려면 각각 prefix:namespaceuri와 같은 문자열인 매개변수를 추가합니다. 예를 들어 SOAP 본문의 하위 요소를 선택하는 xpath() 함수는 다음과 같습니다.

<AssignMessage>
  <AssignVariable>
    <Name>soapns</Name>
    <Value>soap:http://schemas.xmlsoap.org/soap/envelope/</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>xpathexpression</Name>
    <Value>/soap:Envelope/soap:Body/*</Value>
  </AssignVariable>
  <AssignVariable>
    <Name>extracted_element</Name>
    <Template>{xpath(xpathexpression,xml,soapns)}</Template>
  </AssignVariable>
</AssignMessage>

추가 네임스페이스의 경우 xpath() 함수에 최대 10개의 매개변수를 추가할 수 있습니다.

특수 문자가 포함된 XPath 표현식을 문자열 리터럴로 지정하는 대신 변수를 사용해서 함수에 문자열을 포함합니다. 자세한 내용은 문자열 리터럴에 특수 문자 사용 방지를 참조하세요.

{xpath(xpathexpression,xml,ns1)}

예시 3: 원하는 반환 유형 지정

xpath() 함수에 전달되는 세 번째 선택적 매개변수는 원하는 쿼리 반환 유형을 지정합니다.

일부 XPath 쿼리는 숫자 또는 부울 값을 반환할 수 있습니다. 예를 들어 count() 함수는 숫자를 반환합니다. 이는 유효한 XPath 쿼리입니다.

count(//Record/Fields/Pair)

이 유효한 쿼리는 부울을 반환합니다.

count(//Record/Fields/Pair)>0

이러한 경우 해당 유형을 지정하는 세 번째 매개변수를 사용하여 xpath() 함수를 호출합니다.

{xpath(expression,xml,'number')}
{xpath(expression,xml,'boolean')}

세 번째 매개변수에 콜론이 포함된 경우 네임스페이스 인수로 해석됩니다. 그렇지 않은 경우 원하는 반환 유형으로 처리됩니다. 이 경우 세 번째 매개변수가 유효한 값(대소문자 무시)이 아니면 xpath() 함수는 기본적으로 nodeset를 반환합니다.

JSON 경로 함수

JSON 경로 표현식을 JSON 변수에 적용합니다.

구문

jsonPath(json-path,json-var,want-array)

인수

  • (필수) json-path: (문자열) JSON 경로 표현식입니다.
  • (필수) json-var: (문자열) JSON을 포함하는 흐름 변수 또는 문자열입니다.
  • (선택사항) want-array: (문자열) 이 매개변수가 'true'로 설정되고 결과 집합이 배열이면 모든 배열 요소가 반환됩니다. 다른 값으로 설정하거나 이 매개변수를 생략하면 결과 집합 배열의 0번째 요소만 반환됩니다. 결과 집합이 배열이 아니면 이 세 번째 매개변수가 있는 경우 무시됩니다.

예시 1

메시지 템플릿이 다음과 같으며

The address is {jsonPath($.results[?(@.name == 'Mae West')].address.line1,the_json_variable)}

the_json_variable에 다음이 포함된 경우

{
  "results" : [
    {
      "address" : {
        "line1" : "18250 142ND AV NE",
        "city" : "Woodinville",
        "state" : "Washington",
        "zip" : "98072"
      },
      "name" : "Fred Meyer"
    },
    {
      "address" : {
        "line1" : "1060 West Addison Street",
        "city" : "Chicago",
        "state" : "Illinois",
        "zip" : "60613"
      },
      "name" : "Mae West"
    }
  ]
}

이 함수의 결과는 다음과 같습니다.

The address is 1060 West Addison Street

이 경우 결과 집합은 요소 배열이 아닌 단일 요소입니다. 결과 집합이 배열이면 배열의 0번째 요소만 반환됩니다. 전체 배열을 반환하려면 다음 예시와 같이 'true'를 세 번째 매개변수로 사용하여 함수를 호출합니다.

예 2

메시지 템플릿이 다음과 같으며

{jsonPath($.config.quota[?(@.operation=='ManageOrder')].appname,the_json_variable,'true')}

the_json_variable에 다음이 포함된 경우

{
  "results" : [
     {
      "config": {
        "quota": [
          {
            "appname": "A",
            "operation": "ManageOrder",
            "value": "900"
          },
          {
            "appname": "B",
            "operation": "ManageOrder",
            "value": "1000"
          },
          {
            "appname": "B",
            "operation": "SubmitOrder",
            "value": "800"
          }
        ]
      }
    }
  ]
}

이 함수의 결과는 다음과 같습니다.

['A','B']