このページは Cloud Translation API によって翻訳されました。

メッセージテンプレート

このページの内容は Apigee と Apigee ハイブリッドに該当します。

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

注: ポリシーのドキュメントを参照して、メッセージテンプレートをサポートするポリシーや <TargetEndpoint> 要素を確認することもできます。

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

次の表に、ポリシーと、サポートされる要素 / 子要素を示します。

ポリシー	要素 / 子要素
AccessControl ポリシー	`<SourceAddress>`（`mask` 属性と IP アドレス用）
AssignMessage ポリシー	`<Set>` 子要素: Payload、ContentType、Verb、Version、Path、StatusCode、Headers、QueryParams、FormParams `<Add>` 子要素: Headers、QueryParams、FormParams `<AssignVariable>` 子要素: `<Template>`
CORS ポリシー	`<AllowHeaders>` `<AllowMethods>` `<AllowOrigins>` `<ExposeHeaders>`
ExtractVariables ポリシー	`<JsonPath>` 注: メッセージテンプレートは `<XMLPath>` では受け入れられません。
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 テンプレートをご覧ください。

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

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

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

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

メッセージテンプレートの文字列全体を引用符で囲むことはきますが、省略可能です。たとえば、次の 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 )}

ネストされた関数はサポートされていません

テンプレート内の別の関数内での関数の呼び出しはサポートされていません。たとえば、以下は使用できません。

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

テンプレート関数の文字列リテラルは一重引用符で囲む

関数内で文字列リテラルを指定する場合は、二重引用符ではなく、一重引用符で囲みます。

次に例を示します。

{replaceAll('BEARER: 1234','^Bearer ','TOKEN:')}

文字列リテラルに特殊文字を使用しない

文字列リテラルで、「:」、「/」、「\」、「<」、「>」などの特殊文字を使用しないでください。これらの文字はエラーの原因となる場合があります。文字列リテラルに特殊文字が必要な場合は、Python または JavaScript ポリシーを使用して変数に値を割り当ててから、その変数をテンプレートで使用します。

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

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

<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 には、後で説明するとおり、メッセージテンプレート内で文字列変数のエスケープ、エンコード、ハッシュ、書式設定に使用できる一連の関数が用意されています。

例: 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 ハッシュを計算します。

引数

例

関数呼び出し:

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`

Replace First 関数

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

構文

replaceFirst(string,regex,value)

引数

string: 置換を行うリテラル文字列（単一引用符で囲まれた）または文字列フロー変数。
regex: 正規表現。
value: 文字列内で正規表現と一致した文字列を置き換える値。

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

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

構文

関数	説明
`escapeJSON(string)`	二重引用符をバックスラッシュでエスケープします。
`escapeXML(string)`	山かっこ、アポストロフィ、二重引用符、アンパサンドをそれぞれの XML エンティティに置き換えます。XML 1.0 ドキュメントに使用します。 XML1.0 ドキュメントには escapeXML を、XML 1.1 ドキュメントには escapeXML11 を使用します。
`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]

例

"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 の場合はエポック時間（ミリ秒）です。

Examples

以下の値を想定してみます。ローカルタイムゾーンは 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 - （省略可）指定したエンコードに従って秘密鍵の文字列をデコードします。有効な値: 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

Random Long Generator 関数

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

構文

randomLong(args)

引数

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

例

{randomLong()}

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

5211338197474042880

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

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

構文

xeger(regex)

引数

regex: 正規表現

例

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

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

結果の例:

null 結合関数

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

構文

firstnonnull(var1,var_n)

引数

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: （省略可）クエリの戻り値の型を指定します。有効な値は 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 のような文字列である追加パラメータをそれぞれ 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(xpathexpression,xml,ns1)}

例 3: 戻り値の型の指定

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

メッセージ テンプレート

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

例

例

例

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

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

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

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

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

関数式でのスペースの使用禁止

ネストされた関数はサポートされていません

テンプレート関数の文字列リテラルは一重引用符で囲む

文字列リテラルに特殊文字を使用しない

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

URL テンプレート

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

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

例: toLowerCase()

例: escapeJSON()

ハッシュ関数

16 進ハッシュ関数

構文

引数

例

Base64 ハッシュ関数

構文

引数

例

文字列関数

Base64 エンコード関数

構文

引数

例

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

構文

引数

例

Substring 関数

構文

引数

例

すべての関数を置換する

構文

引数

例

Replace First 関数

構文

引数

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

構文

引数

使用上の注意:

例

時刻形式関数

構文

引数

Examples

HMAC 計算関数

構文

引数

例

その他の関数

UUID 関数を作成する

構文

引数

例

Random Long Generator 関数

構文

引数

例

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

構文

引数

例

null 結合関数

構文

引数

例

XPath 関数

メッセージテンプレート

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

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

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

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

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

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

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