マクロ関数

概要

マクロ関数を使用すると、マクロの値をカスタマイズできます（たとえば、短縮したり、特定の部分文字列を抽出したりできます）。これにより、扱いやすくなります。

マクロ関数の構文は次のとおりです。

{macro.func(params)}

ここで、

• macro - カスタマイズするマクロ;
• func - 適用する関数（サポートされる関数を参照）;
• params - 関数パラメーターのカンマ区切りリスト。次の場合は 二重引用符 で囲む必要があります:
  • スペースまたは二重引用符で始まる;
  • 閉じ括弧またはカンマを含む。

例:

{{TIME}.fmttime(format,time_shift)}
{{ITEM.VALUE}.regsub(pattern, output)}
{{$USERMACRO}.regsub(pattern, output)}
{{#LLDMACRO}.regsub(pattern, output)}

マクロ関数は、次のマクロでサポートされています。

• 組み込みマクロ
• ユーザーマクロ
• 低レベルディスカバリマクロ
• 式マクロ

マクロ関数は、列挙したマクロをサポートするすべての場所で使用できます。 ただし、ホストマクロの設定時や低レベルディスカバリルールのフィルターのように、明示的にマクロのみが期待される場合はこの限りではありません。

1つのマクロにつき1つの関数のみがサポートされており、複数のマクロ関数を連結することはできません。

サポートされている関数

関数は追加情報なしで一覧表示されています。
関数をクリックすると、詳細を確認できます。

関数の詳細

オプションの関数パラメータは < > で示されます。

btoa

マクロ値をBase64エンコーディングにエンコードします。 Base64エンコーディングは、バイナリデータをテキストとして表現する方法であり、テキストベースのプロトコルでバイナリコンテンツを保存および安全に転送するのに便利です。

例:

{{ITEM.VALUE}.btoa()} - "zabbix"のような値をBase64で"emFiYml4"にエンコードします

fmtnum(digits)

小数点以下の桁数を制御するための数値フォーマット。

パラメータ:

• digits - 小数点以下の桁数。 有効範囲: 0-20。 末尾のゼロは出力されません。

例:

{{ITEM.VALUE}.fmtnum(2)} - 受信値 "24.3483523" から "24.35" を返します
{{ITEM.VALUE}.fmtnum(0)} - 受信値 "24.3483523" から "24" を返します

fmttime(format,<time_shift>)

時刻の書式設定。
この関数は、次のいずれかの時刻形式の値に解決されるマクロで使用できます。

• hh:mm:ss
• yyyy-mm-ddThh:mm:ss[tz] (ISO8601 標準)
• UNIX タイムスタンプ

パラメーター:

• format - 必須の書式文字列。strftime 関数の書式指定と互換性があります。
• time_shift (任意) - 書式設定前に時刻へ適用する時間シフト。-<N><time_unit> または +<N><time_unit> で始める必要があります。ここで:
  • N - 加算または減算する時間単位の数;
  • time_unit - h (時間), d (日), w (週), M (月), y (年)。

コメント:

• time_shift パラメーターは複数段階の時刻操作をサポートし、時間単位の先頭へシフトするための /<time_unit> を含めることができます (/d - 深夜、/w - 週の1日目 (月曜日)、/M - 月の1日目、など)。 例: -1w - ちょうど7日前; -1w/w - 前週の月曜日; -1w/w+1d - 前週の火曜日。
• 時刻操作は優先順位なしで左から右へ計算されます。 たとえば、-1M/d+1h/w は ((-1M/d)+1h)/w として解釈されます。

例:

{{TIMESTAMP}.fmttime(%B)} - 受信した値 `1633098961` から "October" を返します
{{TIMESTAMP}.fmttime(%d %B,-1M/M)} - 受信した値 `1633098961` から "1 September" を返します
{{EVENT.TIMESTAMP}.fmttime("%x %X")} - ロケールに応じた日付と時刻の表現を返します。たとえば、イベントのタイムスタンプ `1784100339` に対して "07/15/26 10:25:39" を返します
{{EVENT.TIME}.fmttime("%x %X")} - イベントに関連付けられたタイムスタンプ `1784100339` に対して、ロケールに応じた日付と時刻の表現を返します。たとえば、"07/15/26 10:25:39" を返します

htmldecode

マクロ値をHTMLエンコードからデコードします。

以下の文字がサポートされています:

例:

{{ITEM.VALUE}.htmldecode()} - "&lt;"のような値をHTMLデコードして"<"にします

htmlencode

マクロ値をHTMLエンコーディングに変換します。

以下の文字がサポートされています:

例:

{{ITEM.VALUE}.htmlencode()} - "<" のような文字を "&lt;" にHTMLエンコードします

iregsub(pattern,output)

正規表現(大文字・小文字を区別しない)による部分文字列の抽出。

パラメータ:

• pattern - マッチさせる正規表現
• output - 出力オプション。 \1 - \9 プレースホルダーはキャプチャグループに対応。 \0 はマッチしたテキストを返します。

コメント:

• 正規表現にマッチしない場合、関数は空文字列を返します。
• 関数パターンが不正な正規表現の場合、マクロは「UNKNOWN」と評価されます(ただし、ローレベルディスカバリーマクロの場合は関数が無視され、マクロは未解決のままになります)。
• 置換文字列内で存在しないキャプチャグループへの参照は空文字列に置き換えられます。

例:

{{ITEM.VALUE}.iregsub("fail|error|fault|problem","ERROR")} - "fail"、"error"、"fault"、"problem"のいずれかの部分文字列が受信された場合(大文字・小文字を区別しない)は"ERROR"に解決されます。マッチしない場合は空文字列を返します

jsonpath(pattern,<default>)

JSONPathの結果を返します。
サポートされている値のタイプ: String、Text、Log。

パラメータ:

• pattern - 必須のパターン;
  
• default - JSONPathクエリがデータを返さない場合のオプションのフォールバック値。その他のエラーが発生した場合は、失敗が返されます。

コメント:

• 次の場合、関数はエラーで失敗します:
  • JSONが無効な場合。
  • JSONPathクエリが失敗した場合。
  • JSONPathの結果にデータが含まれておらず、defaultパラメータが指定されていない場合。

例:

{{ITEM.VALUE}.jsonpath("$.columns.servicename", "NA")}

lowercase

すべてのマクロ値の文字を小文字に変換します。 シングルバイト文字セット（ASCIIなど）で動作し、UTF-8はサポートしていません。

例:

{{ITEM.VALUE}.lowercase()} - "Zabbix SERVER"のような値を"zabbix server"（小文字）に変換します

regrepl(pattern,replacement,<pattern2>,<replacement2>,...)

マクロ値内の文字/サブストリングを置換します。

パラメーター:

• pattern - 一致させる正規表現。
• replacement - 置換文字列。 \1 - \9 のプレースホルダーは、置換文字列内でキャプチャグループを参照するために使用できます。

コメント:

• pattern に一致するすべての出現箇所が置換されます。
• pattern と replacement は順番に処理され、各後続のペアは前の置換結果に従って適用されます。
• 置換文字列内で存在しないキャプチャグループを参照した場合は、空文字列に置き換えられます。

例:

{{ITEM.VALUE}.regrepl("oldParam", "newParam")} - "oldParam" を "newParam" に置換します
{{ITEM.VALUE}.regrepl("([^a-z])","\\\1")} - 英字以外のすべての文字はバックスラッシュでエスケープされます
{$THRESHOLD:"{{#FSNAME}.regrepl(\"\\$\",\"\")}"} - 末尾のバックスラッシュを削除します（たとえば、"C:\" を "C:" に置換する場合）
{{ITEM.VALUE}.regrepl("_v1\.0", "_v2.0", "\(final\)", "")} - アイテム値内の複数の部分を置換します

regsub(pattern,output)

正規表現マッチによる部分文字列の抽出（大文字と小文字を区別）。

パラメータ:

• pattern - マッチさせる正規表現
• output - 出力オプション。 \1 - \9 プレースホルダーはキャプチャグループに対応。 \0 はマッチしたテキストを返します。

コメント:

• 正規表現にマッチしない場合、関数は空文字列を返します。
• 関数パターンが不正な正規表現の場合、マクロは 'UNKNOWN' に評価されます（ただし、ローレベルディスカバリーマクロの場合は関数が無視され、マクロは未解決のままになります）。
• 置換文字列で存在しないキャプチャグループへの参照は、空文字列に置き換えられます。

例:

{{ITEM.VALUE}.regsub("^([0-9]+)", Problem ID: \1)} - "123 Log line" のような値を受信した場合、"Problem ID: 123" に解決されます
{{ITEM.VALUE}.regsub("fail|error|fault|problem","ERROR")} - "fail"、"error"、"fault"、"problem" のいずれかの部分文字列を受信した場合（大文字と小文字を区別）、"ERROR" に解決されます。マッチしない場合は空文字列を返します

追加の例も参照してください。

tr(characters,replacement)

マクロ値の文字の音訳。

• characters - 置換する文字のセット
• replacement - 位置的に対応する置換文字のセット

例:

{{ITEM.VALUE}.tr(abc, xyz)} - "a"を"x"、"b"を"y"、"c"を"z"にすべて置換します
{{ITEM.VALUE}.tr(abc, xyzq)} - "a"を"x"、"b"を"y"、"c"を"z"にすべて置換します（"q"は無視されます）
{{ITEM.VALUE}.tr(abcde, xyz)} - "a"を"x"、"b"を"y"、"c"を"z"、"d"を"z"、"e"を"z"にすべて置換します（つまりxyzzz）
{{ITEM.VALUE}.tr("\\\'", "\/\"")} - バックスラッシュをスラッシュに、シングルクォートをダブルクォートにすべて置換します
{{ITEM.VALUE}.tr(A-Z,a-z)} - すべての文字を小文字に変換します
{{ITEM.VALUE}.tr(0-9a-z,*)} - すべての数字と小文字を"*"に置換します
{{ITEM.VALUE}.tr(0-9,ab)} - 0を"a"に、1,2,3,4,5,6,7,8,9を"b"にすべて置換します
{{ITEM.VALUE}.tr(0-9abcA-L,*)} - すべての数字、"abc"文字、A-L範囲を"*"に置換します
{{ITEM.VALUE}.tr("\n","*")} - 行末を*に置換します
{{ITEM.VALUE}.tr("e", "\n")} - すべての"e"を行末に置換します

リテラル文字を含めるには:

バックスラッシュ - \\でエスケープする必要があります
シングルクォート - \'でエスケープする必要があります
ダブルクォート - \"でエスケープする必要があります

バックスラッシュによるサポートされるエスケープシーケンス:

\\\\ => \\ - ダブルバックスラッシュをシングルバックスラッシュに
\\a  => \a - アラート
\\b  => \b - バックスペース
\\f  => \f - フォームフィード
\\n  => \n - 改行
\\r  => \r - リターン
\\t  => \t - 水平タブ
\\v  => \v - 垂直タブ

uppercase

すべてのマクロ値の文字を大文字に変換します。 シングルバイト文字セット(ASCIIなど)で動作し、UTF-8はサポートしていません。

例:

{{ITEM.VALUE}.uppercase()} - "Zabbix Server"のような値を"ZABBIX SERVER"(大文字)に変換します

urldecode

マクロ値をURLエンコードからデコードします。

例:

{{ITEM.VALUE}.urldecode()} - "%2F"のような値を"/"にURLデコードします

urlencode

マクロ値をURLエンコーディングに変換します。

例:

{{ITEM.VALUE}.urlencode()} - "/"のような文字を"%2F"にURLエンコードします

xmlxpath(pattern,<default>)

XML XPathの結果を返します。
サポートされている値のタイプ: String、Text、Log。

パラメータ:

• pattern - 必須のパターン;
  
• default - XPathクエリがデータを返さない場合のオプションのフォールバック値。その他のエラーが発生した場合は、失敗が返されます。

コメント:

• 次の場合、関数はエラーで失敗します。
  • XMLが無効である。
  • XPathクエリが失敗する。
  • XPathの結果にデータが含まれておらず、defaultパラメータが指定されていない。
  • ZabbixがXMLサポートなしでコンパイルされている。

例:

{{ITEM.VALUE}.xmlxpath("/response/error/status","unknown")}

追加例

以下の表は、マクロ関数の使用例をさらに示しています。

:::noteinfo {#IFALIAS}はLLDマクロであり、低レベルディスカバリのコンテキスト（ディスカバリルール、プロトタイプ、およびそれらから作成されたアイテム/トリガー）でのみ定義されます。 LLD以外で使用すると、トークンは展開されません。 :::

アイテム値全体の表示

テキスト/ログアイテムの解決された{ITEM.VALUE}および{ITEM.LASTVALUE}マクロの長い値は、一部のフロントエンドの場所で20文字に切り捨てられます。 これらのマクロの完全な値を表示するには、以下のようなマクロ関数を使用できます。

{{ITEM.VALUE}.regsub("(.*)", \1)}
{{ITEM.LASTVALUE}.regsub("(.*)", \1)}

詳細は、{ITEM.VALUE}および{ITEM.LASTVALUE}のマクロ詳細も参照してください。