このページは 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 構成で使用される特定の要素でサポートされます。
メッセージ テンプレートを受け入れるポリシー
次の表に、ポリシーと、サポートされる要素 / 子要素を示します。
| ポリシー | 要素 / 子要素 |
|---|---|
| AccessControl ポリシー | <SourceAddress>（mask 属性と IP アドレス用） |
| AssignMessage ポリシー | <Set> 子要素: Payload、ContentType、Verb、Version、Path、StatusCode、Headers、QueryParams、FormParams
|
| CORS ポリシー | |
| ExtractVariables ポリシー | <JsonPath>
|
| GenerateJWS ポリシー VerifyJWS ポリシー |
* これらの要素では、type=map の場合のみ、メッセージ テンプレートがサポートされます。 |
| GenerateJWT ポリシー VerifyJWT ポリシー |
<AdditionalClaims><Claim>
* これらの要素では、type=map の場合のみ、メッセージ テンプレートがサポートされます。 |
| HTTPModifier ポリシー | <Set> 子要素:
|
| MessageLogging ポリシー |
|
| OASValidation ポリシー | |
| RaiseFault ポリシー |
|
| SAMLAssertion ポリシー | <Template>
* ポリシーの署名が |
| ServiceCallout ポリシー |
|
メッセージ テンプレートを受け入れる <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 ハッシュを計算します。 |
引数
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
|
Replace All 関数
文字列を正規表現と照合し、一致する場合は一致した文字列を置換値に置き換えます。
構文
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]
例
"bread"
& "butter" の値を持つ food というフロー変数があるとします。関数は次のとおりです。
{escapeHTML(food)}
結果は次のようになります。
"bread" & "butter"
時刻形式関数
時間の文字列表現を UTC 形式で返します。
構文
| 関数 | 説明 |
|---|---|
timeFormat(format,str)
|
UTC 形式の日付を返します。 DEPRECATED: ローカルタイム ゾーン形式の日付を返します。 |
timeFormatMs(format,str)
|
UTC 形式の日付を返します。 DEPRECATED: ローカルタイム ゾーン形式の日付を返します。 |
timeFormatUTC(format,str)
|
UTC 形式の日付を返します。 |
timeFormatUTCMs(format,str)
|
UTC 形式の日付を返します。 |
引数
format: 日付時刻形式の文字列。リテラル文字列（単一引用符で囲まれた）または文字列変数を指定できます。書式にコロンが含まれる場合は、リテラルではなく変数を使用します。このセクションの前の注をご覧ください。str: 時間の値が含まれる文字列または文字列フロー変数。この値は、エポック時間（秒）か、timeFormatMs の場合はエポック時間（ミリ秒）です。
例
以下の値を想定してみます。ローカルタイム ゾーンは Pacific とします。
epoch_time_ms = 1494390266000epoch_time = 1494390266fmt1 = yyyy-MM-ddfmt2 = yyyy-MM-dd HH-mm-ssfmt3 = 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}' )
結果の例:
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: （省略可）クエリの戻り値の型を指定します。有効な値は 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 パス関数
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']