메시지 템플릿

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보

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

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

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

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

메시지 템플릿은 어디에서 사용할 수 있나요?도 참고하세요.

예

예를 들어 메시지 할당 정책을 사용하면 <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가 됩니다. 변수를 확인할 수 없는 경우에는 빈 문자열이 출력됩니다.

예

할당량을 초과하면 호출자에게 유의미한 메시지를 반환하는 것이 좋습니다. 이 패턴은 일반적으로 '결함 규칙'과 함께 호출자에게 할당량 위반에 대한 정보를 제공하는 출력을 제공합니다. 다음 메시지 할당 정책에서 메시지 템플릿은 여러 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>
    <ReasonPhrase>Quota Exceeded</ReasonPhrase>
  </Set>
</AssignMessage>

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

• 헤더
• QueryParam
• FormParam
• PayLoad
• 버전
• 동사
• 경로
• StatusCode
• ReasonPhrase

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

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

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

예

프록시 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> 하위 요소: pay, ContentType, Verb, Version, Path, StatusCode, Reasonphrase, Headers, QueryParams, FormParams <Add> 하위 요소: Headers, QueryParams, FormParams <AssignVariable> 하위 요소: <Template>
ExtensionCallout 정책	<Input>
ExtractVariables 정책	<JsonPath>
GenerateJWS 정책 VerifyJWS 정책	<Payload>(GenerateJWS 정책만 해당) <AdditionalHeaders><Claim> * 이 요소는 type=map인 경우에만 메시지 템플릿을 지원합니다.
GenerateJWT 정책 VerifyJWT 정책	<AdditionalClaims><Claim> <AdditionalHeaders><Claim> * 이 요소는 type=map인 경우에만 메시지 템플릿을 지원합니다.
LDAP 정책	<SearchQuery>
MessageLogging 정책	<Syslog><Message> <File><Message>
OASValidation 정책	<OASResource> 요소
RaiseFault 정책	<Set> 요소: pay, ContentType, Verb, Version, Path, StatusCode, Reasonphrase, Headers, QueryParams, FormParams <Add> 요소: Headers, QueryParams, FormParams
SAMLAssertion 정책	<Template> * 정책 서명이 <GenerateSAMLAssertion>인 경우에만
ServiceCallout 정책	<Set> 요소: PAY, ContentType, Verb, Version, Path, StatusCode, Reasonphrase, /Headers, QueryParams, FormParams <Add> 요소: Headers, QueryParams, FormParams <HTTPTargetConnection>/<URL>: 문자열의 첫 번째 부분은 http 또는 https여야 합니다.

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

HTTPTargetConnection 요소	메시지 템플릿을 지원하는 하위 요소
SSLInfo	사용 설정됨, KeyAlias, 키 저장소, TrustStore, ClientAuthEnabled, CLRStore
LocalTargetConnection	ApiProxy, ProxyEndpoint
경로	N/A

메시지 템플릿 구문

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

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

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

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

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

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

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

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

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

Test message. id = Unknown

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

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

허용되는 유형:

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

허용되지 않는 유형:

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

JSON 페이로드의 기존 구문

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

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

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

메시지 템플릿 함수 사용

Edge는 메시지 템플릿 내에서 문자열 변수를 이스케이프, 인코딩, 해싱, 형식 지정하기 위해 사용할 수 있는 함수 집합을 제공합니다.

메시지 템플릿 함수는 메시지 템플릿 함수 참조에서 자세히 설명합니다.

예: 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."
}

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

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

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

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

<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>

안타깝게도 문제가 있습니다. 변수 추출 정책에서 메일 일부 주변의 이스케이프 처리된 따옴표를 삭제했습니다. 즉, 클라이언트에 반환된 응답이 잘못된 JSON입니다. 이는 의도한 결과가 아닙니다.

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

이 문제를 해결하려면 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 해시를 계산합니다.

인수

문자열 - 해시 함수는 해시 알고리즘이 계산되는 단일 문자열 인수를 사용합니다. 인수는 리터럴 문자열 또는 문자열 흐름 변수일 수 있습니다.

예

함수 호출:

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로 인코딩된 valuer로 표현된 SHA384 해시를 계산합니다.
sha512Base64(string)	Base64로 인코딩된 값으로 표시된 SHA512 해시를 계산합니다.

인수

문자열 - 해시 함수는 해시 알고리즘이 계산되는 단일 문자열 인수를 사용합니다. 인수는 리터럴 문자열 또는 문자열 흐름 변수일 수 있습니다.

예

함수 호출:

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)	문자열을 소문자로 변환합니다.

인수

문자열 - 변환할 문자열입니다. 리터럴 문자열 또는 문자열 흐름 변수일 수 있습니다.

예

<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

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

메시지 템플릿 표현식	Result
{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)

인수

• 문자열 - 대체를 수행할 리터럴 문자열 또는 문자열 흐름 변수.
• 정규식 - 정규 표현식입니다.
• value - 문자열 내의 모든 정규식 일치 항목을 대체할 값입니다.

예

다음 예에서는 다음과 같은 흐름 변수가 있다고 가정합니다.

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

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

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

첫 번째 함수 대체

문자열에서 지정된 정규 표현식 일치 항목의 첫 번째 일치하는 항목만 바꿉니다.

문법

replaceFirst(string,regex,value)

인수

• 문자열 - 대체를 수행할 리터럴 문자열 또는 문자열 흐름 변수.
• 정규식 - 정규 표현식입니다.
• value - 문자열 내의 정규식 일치 항목을 대체할 값입니다.

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

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

문법

함수	설명
EscJSON(문자열)	백슬래시는 큰따옴표를 이스케이프합니다.
EscXML(문자열)	꺾쇠괄호, 아포스트로피, 큰따옴표, 앰퍼샌드를 각 XML 요소로 바꿉니다. XML 1.0 문서에 사용합니다.
EscXML11(문자열)	escapeXML과 동일한 방식으로 작동하지만 XML v1.1 항목에 적용됩니다. 아래 사용 참고사항을 확인하세요.
인코딩 HTML(문자열)	아포스트로피, 꺾쇠괄호, 앰퍼샌드를 인코딩합니다.

인수

문자열 - 이스케이프할 문자열입니다. 리터럴 문자열 또는 문자열 흐름 변수일 수 있습니다.

사용 참고사항

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

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

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

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

예

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

{escapeHTML(food)}

결과:

"bread" & "butter"

시간 형식 함수

현지 시간대 또는 UTC 형식으로 시간 문자열 표현을 반환합니다.

문법

함수	설명
timeFormat(format,str)	현지 시간대로 형식이 지정된 날짜를 반환합니다.
timeFormatMs(format,str)	현지 시간대로 형식이 지정된 날짜를 반환합니다.
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)

인수

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

예

{random()}

결과는 다음과 같습니다.

5211338197474042880

정규식 텍스트 생성기

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

문법

xeger(regex)

인수

정규식 - 정규 표현식입니다.

예

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

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

결과 예시:

9857253

Null 병합 함수

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

문법

firstnonnull(var1,varn)

인수

var1 - 컨텍스트 변수

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

예

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

템플릿	Var1	Var2	Var3	Result
{firstnonnull(var1,var2)}	설정되지 않음	foo	N/A	foo
{firstnonnull(var1,var2)}	foo	bar	N/A	foo
{firstnonnull(var1,var2)}	foo	설정되지 않음	N/A	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)}	설정되지 않음	N/A	N/A	null
{firstnonnull(var1)}	foo	N/A	N/A	foo
{firstnonnull(var1,var2)}	""	bar	N/A	""
{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입니다. 기본값은 일반적으로 적합합니다.

예시 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

노드의 값만 원하는 경우 다음과 같이 text() 함수를 사용합니다.

<AssignMessage>
  <AssignVariable>
    <Name>extracted_tag</Name>
    <Template>{xpath('/tag/tagid/text()',xml)}</Template>
  </AssignVariable>
</AssignMessage>

이 작업의 결과로 컨텍스트 변수 extracted_tag가 250397로 설정됩니다.

여러 노드를 선택한 경우 xpath()의 결과는 선택한 모든 값이 쉼표로 연결되어 있습니다.

예시 3: 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('/tag/tagid/text()',xml)}

XPath 표현식에 네임스페이스 프리픽스(및 콜론)가 포함된 경우 해당 XPath 표현식을 변수에 할당하고 표현식 대신 직접 변수 이름을 지정해야 합니다.

{xpath(xpathexpression,xml,ns1)}

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

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']