メッセージ テンプレート

このトピックでは、API プロキシでメッセージ テンプレートを使用する方法を説明し、関数リファレンスを提供します。

メッセージ テンプレートとは

メッセージ テンプレートを使用すると、特定のポリシーと TargetEndpoint 要素で変数文字列の置換を実行できます。この機能に対応している場合は、プロキシの実行時に文字列データを動的に代入できます。

メッセージ テンプレートには、フロー変数参照とリテラル テキストの任意の組み合わせを含めることができます。フロー変数名は中かっこで囲む必要があり、中かっこで囲まれていないテキストはすべてリテラル テキストとして出力されます。

メッセージ テンプレートを使用できる状況もご覧ください。

例

たとえば、Assign Message ポリシーでは、<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 要素は指定されたフロー変数の値を受け取ります。
• ペイロードにはリテラル テキストと変数が混在しています（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 構成で使用される特定の要素でサポートされています。

メッセージ テンプレートを受け入れるポリシー

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

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

ここでは、メッセージ テンプレートの使用時に適用されるルールについて説明します。

変数を示す中かっこの使用

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

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

<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

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

次に、このメッセージをカスタム ペイロードでクライアントの呼び出し元に返すとします。通常の方法では、ターゲットのレスポンス ペイロードからメッセージを抽出して、Assign Message を使用してそれをカスタム プロキシ レスポンスに追加します（つまり、クライアントに返信します）。

user_message 情報を standard.systemMessage という変数に抽出する、Extract Variables ポリシーを次に示します。

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

以下は、抽出された変数をレスポンス ペイロード（プロキシ レスポンス）に追加する、完全に有効な Assign Message ポリシーです。

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

ここで問題が発生します。メッセージ部分を囲むエスケープされた引用符が Extract Variables ポリシーによって削除されてしまいます。このため、クライアントに返されるレスポンスが無効な JSON になっています。これは意図した結果ではありません。

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

この問題を回避するには、JSON 内の引用符を自動的にエスケープするメッセージ テンプレート関数を使用するように、Assign Message ポリシーを変更します。この関数 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 進数として返します。

構文

引数

string - ハッシュ関数は、ハッシュ アルゴリズムが計算される単一の文字列引数を取ります。この引数には、リテラル文字列か文字列フロー変数を指定できます。

例

関数呼び出し:

sha256Hex('abc')

結果:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

関数呼び出し:

var str = 'abc';
sha256Hex(str)

結果:

ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

Base64 ハッシュ関数

ハッシュ値を計算し、そのハッシュの文字列表現を Base64 エンコード値として返します。

構文

引数

string - ハッシュ関数は、ハッシュ アルゴリズムが計算される単一の文字列引数を取ります。この引数には、リテラル文字列か文字列フロー変数を指定できます。

例

関数呼び出し:

sha256Base64('abc')

結果:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

関数呼び出し:

var str = 'abc';
sha256Base64(str)

結果:

ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=

文字列関数

メッセージ テンプレート内の文字列に対してオペレーションを実行します。

Base64 エンコード関数

Base64 エンコード スキームを使用して文字列をエンコード / デコードします。

構文

引数

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>

大文字と小文字の変換関数

文字列すべてを大文字または小文字に変換します。

構文

引数

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 - （省略可）文字列の終了インデックス。指定しない場合、終了インデックスは文字列の末尾になります。

例

以降の例では、次のフロー変数が存在すると想定されています。

上記の変数を使用した関数呼び出しの結果を以下に示します。

Replace All 関数

文字列に正規表現を適用し、一致する場合は一致したものを置換値に置き換えます。

構文

replaceAll(string, regex, value)

引数

• string - 置換を行うリテラル文字列または文字列フロー変数。
• regex - 正規表現。
• value - 文字列内のすべての正規表現一致を置き換える値。

例

以降の例では、次のフロー変数が存在すると想定されています。

上記の変数を使用した関数呼び出しの結果を以下に示します。

Replace First 関数

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

構文

replaceFirst(string, regex, value)

引数

• string - 置換を行うリテラル文字列または文字列フロー変数。
• regex - 正規表現。
• value - 文字列内の正規表現一致を置き換える値。

文字のエスケープとエンコードの関数

文字列内の特殊文字をエスケープまたはエンコードする関数。

構文

引数

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

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

時間表示形式の関数

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

構文

引数

• format - 日付/時刻形式文字列。リテラル文字列または文字列変数を使用できます。
• str - 時間値を含む文字列または文字列フロー変数。この値は、エポック時間（秒）か、timeFormatMs の場合はエポック時間（ミリ秒）です。

例

以下の値を想定してみます。ローカルタイム ゾーンは 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

その他の関数

Create UUID 関数

UUID を生成して返します。

構文

createUuid()

引数

なし

例

{createUuid()}

結果のサンプル

ec3ca9be-d1e1-4ef4-aee4-4a58f3130db8

Random Long Generator 関数

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

構文

randomLong(args)

引数

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

例

{random()}

次のような結果が返されます。

5211338197474042880

正規表現テキスト ジェネレータ

指定の正規表現と一致するテキスト文字列が返されます。

構文

xeger(regex)

引数

regex - 正規表現。

例

この例では、ゼロが含まれない 7 桁の文字列が生成されます。

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

例の結果

9857253

null 結合関数

firstnonnull() 関数は、null 以外の左端の引数の値を返します。

構文

firstnonnull(var1, varn)

引数

var1 - コンテキスト変数。

var_n - 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 - （省略可）クエリの目的の戻り値の型を指定します。ノードセット、ノード、数値、ブール値、文字列を指定できます。デフォルトはノードセットです。通常はデフォルトが適切です。

例 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() 関数に渡されるオプションの 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 変数に JSON Path 表現を適用します。

構文

jsonPath(json-path, json-var)

引数

json-path - JSON Path 式。

json-var - JSON を含むフロー変数または文字列。

例

以下のメッセージ テンプレートがあるとします。

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