メッセージ テンプレート

Apigee X のドキュメントが表示されています。
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>
    <ReasonPhrase>Quota Exceeded</ReasonPhrase>
  </Set>
</AssignMessage>

AssignMessage ポリシーでは、<Set> 要素内の以下の要素でメッセージ テンプレートの使用がサポートされます。

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

メッセージ テンプレートのフロー変数は中かっこで囲む必要があります

このポリシーが実行されると、次のようになります。

  • <Header> 要素は、指定されたフロー変数の値を受け取ります。
  • Payload には、リテラル テキストと変数が混在しています(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 ポリシー <SourceAddress>mask 属性と IP アドレス用)
AssignMessage ポリシー <Set> 子要素: Payload、ContentType、Verb、Version、Path、StatusCode、ReasonPhrase、Headers、QueryParams、FormParams

<Add> 子要素: Headers、QueryParams、FormParams

<AssignVariable> 子要素: <Template>

CORS ポリシー

<AllowHeaders>

<AllowMethods>

<AllowOrigins>

<ExposeHeaders>

ExtensionCallout ポリシー <Input>
ExtractVariables ポリシー <JsonPath>
GenerateJWS ポリシー
VerifyJWS ポリシー

<Payload>GenerateJWS ポリシーのみ)

<AdditionalHeaders><Claim>

* これらの要素では、type=map の場合のみメッセージ テンプレートがサポートされます。

GenerateJWT ポリシー
VerifyJWT ポリシー
<AdditionalClaims><Claim>

<AdditionalHeaders><Claim>

* これらの要素では、type=map の場合のみメッセージ テンプレートがサポートされます。

MessageLogging ポリシー <Syslog><Message>

<File><Message>

OASValidation ポリシー <OASResource> 要素
RaiseFault ポリシー

<Set> 要素:

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

<Add> 要素:

  • <FormParams>
  • <Headers>
  • <QueryParams>
SAMLAssertion ポリシー <Template>

* ポリシーの署名が <GenerateSAMLAssertion> の場合のみ

ServiceCallout ポリシー

<Set> 要素:

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

<Add> 要素:

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

<HTTPTargetConnection>/<URL>: 文字列の最初の部分が http または https である必要があります。

メッセージ テンプレートを受け入れる <TargetEndpoint> 要素

<HTTPTargetConnection> 要素 メッセージ テンプレートがサポートされる子要素
<SSLInfo> <Enabled><KeyAlias><KeyStore><TrustStore><ClientAuthEnabled><CLRStore>
<LocalTargetConnection> <ApiProxy><ProxyEndpoint>
<Path> 該当なし

メッセージ テンプレートの構文

このセクションでは、メッセージ テンプレートを使用するために従う必要があるルールについて説明します。

中かっこを使用して変数を示す

変数名を中かっこ { } で囲みます。変数が存在しない場合は、出力で空の文字列が返されます。ただし、メッセージ テンプレートではデフォルト値(変数が解決されない場合に置換される値)を指定できます。詳しくは、メッセージ テンプレートのデフォルト値の設定をご覧ください。

メッセージ テンプレートの文字列全体を引用符で囲むことはきますが、省略可能です。たとえば、次の 2 つのメッセージ テンプレートは同じです。

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

メッセージ テンプレートのデフォルト値の設定

テンプレート化された変数を解決できない場合、空の文字列に置換されます。ただし、次のようにデフォルト値を指定することもできます。

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

上記のサンプルでは、変数 request.header.id を解決できない場合、その値が Unknown に置き換えられます。例:

Test message. id = Unknown

JSON ペイロードのレガシー構文

Cloud リリース 16.08.17 より前の Apigee バージョンでは、中かっこを使用して JSON ペイロード内の変数参照を指定できませんでした。こうしたバージョンでは、variablePrefix 属性と variableSuffix 属性を使用して区切り文字を指定し、次のように変数名をラップする必要がありました。

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

新しい中かっこの構文の使用をおすすめしますが、以前の構文も引き続き機能します。

メッセージ テンプレート関数の使用

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

この問題を回避するには、JSON 内の引用符をエスケープするメッセージ テンプレート関数を使用するように AssignMessage ポリシーを変更します。この関数 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) の場合、valueabc を持つときに、文字列 YWJj を返します。
decodeBase64(string) base64 でエンコードされた文字列をデコードします。たとえば decodeBase64(value) の場合、valueaGVsbG8sIHdvcmxk を持つときに は文字列 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

Replace First 関数

文字列内で指定された正規表現と最初に一致したもののみを置き換えます。

構文

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 バイトまたはペアになっていない Unicode サロゲート コードポイントはエスケープ適用後でも表記できません。escapeXML11() 関数では、次の範囲に適合しない文字が削除されます。

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

escapeXML11() 関数では、次の範囲の文字がエスケープされます。

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

food というフロー変数があり、値として "bread" & "butter" が格納されているとします。関数は次のとおりです。

{escapeHTML(food)}

結果は次のようになります。

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

時刻形式関数

時間の文字列表現をローカル タイム ゾーンまたは UTC 形式で返します。

構文

関数 説明
timeFormat(format, str) ローカル タイム ゾーン形式で日付を返します。
timeFormatMs(format, str) ローカルタイム ゾーン形式の日付を返します。
timeFormatUTC(format, str) UTC 形式の日付を返します。
timeFormatUTCMs(format, str) UTC 形式の日付を返します。

引数

  • format: 日付 / 時刻形式の文字列。リテラル文字列または文字列変数を使用できます。
  • str: 時間の値が含まれる文字列または文字列フロー変数。この値は、timeFormatMs の seconds-since-epoch または milliseconds-since-epoch で指定できます。

以下の値を想定してみます。ローカルタイム ゾーンは Pacific とします。

  • 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 を計算する代替手段を提供します。この関数は、1 つの HMAC の出力が 2 番目の 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 - (省略可)指定したエンコードに従って秘密鍵の文字列をデコードします。有効な値: hexbase16base64utf-8。デフォルト: utf-8
  • outputencoding - (省略可)出力に使用するエンコード アルゴリズムを指定します。有効な値: hexbase16base64値の大文字と小文字は区別されません。hexbase16 は類義語です。デフォルト: 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>{hmac256(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

Random Long Generator 関数

ランダムな長整数を返します。

構文

randomLong(args)

引数

  • 引数を指定しない場合、この関数では Java SecureRandom クラスによって計算されたランダムな長整数が返されます。
  • 引数が 1 つ存在している場合は、計算の最小値として処理されます。
  • 引数を 2 つ指定する場合は、2 つ目の引数が計算の最大値として処理されます。

{random()}

結果は次のようになります。

5211338197474042880

正規表現テキスト生成ツール

指定した正規表現と一致するテキスト文字列を生成します。

構文

xeger(regex)

引数

regex: 正規表現

この例では、0 のない 7 桁の文字列を生成します。

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

結果の例:

9857253

null 結合関数

firstnonnull() 関数では、左端の null ではない引数が返されます。

構文

firstnonnull(var1, varn)

引数

var1: コンテキスト変数。

varn: 1 つ以上のコンテキスト変数。右端の引数を文字列に設定して、代替値(左側の引数が設定されていない場合に設定される値)を指定できます。

次の表に、関数の使用方法を示します。

テンプレート 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 関数

XPath 式を XML 変数に適用します。

構文

xpath(xpath_expression, xml_string, [datatype])

引数

xpath_expression: XPath 式。

xml_string: XML を含むフロー変数または文字列。

datatype: (省略可)クエリの戻り値の型を指定します。有効な値は nodesetnodenumberboolean または 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

ノードの値のみが必要な場合は、次のように text() 関数を使用します。

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

このオペレーションの結果として、コンテキスト変数 extracted_tag250397 に設定されます。

複数のノードを選択した場合、xpath() の結果は、選択したすべての値をカンマで連結したものです。

例 3: XML 名前空間

名前空間を指定するには、prefix:namespaceuri のような文字列である追加パラメータをそれぞれ 1 つずつ追加します。たとえば、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() 関数に渡されるオプションの 3 番目のパラメータでは、クエリの戻り値の型が指定されます。

一部の XPath クエリでは、数値またはブール値を返すことができます。たとえば、count() 関数は数値を返します。これは有効な XPath クエリです。

count(//Record/Fields/Pair)

この有効なクエリではブール値が返されます。

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

このような場合は、その型を指定する 3 番目のパラメータを使用して xpath() 関数を呼び出します。

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

3 番目のパラメータにコロンが含まれている場合、名前空間引数と解釈されます。コロンが含まれていない場合、目的の戻り値の型として扱われます。ここで、3 番目のパラメータが有効な値ではない場合(大文字と小文字は区別されません)、xpath() 関数ではデフォルトでノードセットが返されます。

JSON Path 関数

JSON Path 式を JSON 変数に適用します。

構文

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

引数

  • (必須)json-path:(文字列)JSON Path 式。
  • (必須)json-var: (文字列)JSON を含むフロー変数または文字列。
  • (省略可)want-array:(文字列)このパラメータが 'true' に設定され、結果セットが配列の場合は、すべての配列要素が返されます。他の値に設定するか、このパラメータを省略すると、結果セットの配列の 0 番目の要素のみが返されます。結果セットが配列でない場合、この 3 番目のパラメータが存在する場合は、無視されます。

例 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 番目の要素のみが返されます。配列全体を返すには、次の例に示すように、3 番目のパラメータとして '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']