[comment]: # ({d30dc182-d30dc182})
# 2 ユーザーマクロ

[comment]: # ({/d30dc182-d30dc182})

[comment]: # ({c282a934-3e220640})
#### 概要

Zabbixでは、標準で[サポートされているマクロ](/manual/appendix/macros/supported_by_location)に加えて、より柔軟性を持たせるためにユーザーマクロがサポートされています。

ユーザーマクロは、グローバル、テンプレート、ホストレベルで定義できます。これらのマクロには特別な構文があります。

    {$MACRO}

Zabbixは、以下の優先順位でマクロを解決します。

1.  ホストレベルのマクロ（最初にチェックされる）
2.  ホストの第1レベルテンプレート（ホストに直接リンクされているテンプレート）で定義されたマクロ（テンプレートIDでソート）
3.  ホストの第2レベルテンプレートで定義されたマクロ（テンプレートIDでソート）
4.  ホストの第3レベルテンプレートで定義されたマクロ（テンプレートIDでソート）、以下同様
5.  グローバルマクロ（最後にチェックされる）

つまり、ホストにマクロが存在しない場合、Zabbixは深さを増しながらホストテンプレート内でマクロを探します。それでも見つからない場合、存在すればグローバルマクロが使用されます。

::: notewarning
**同じ名前**のマクロが同じレベルの複数のリンクされたテンプレートに存在する場合、IDが最も小さいテンプレートのマクロが使用されます。したがって、複数のテンプレートで同じ名前のマクロを持つことは、設定上のリスクとなります。
:::

Zabbixがマクロを見つけられない場合、そのマクロは解決されません。

::: noteimportant
マクロ（ユーザーマクロを含む）は、複雑な設定をより明確にするために、設計上、[設定]セクション（たとえばトリガーリスト）では未解決のまま残されます。
:::

ユーザーマクロは以下で使用できます。

-   アイテム名
-   アイテムキーのパラメータ
-   アイテムの更新間隔および柔軟な間隔
-   トリガー名および説明
-   トリガー式のパラメータおよび定数（[例](#examples)を参照）
-   その他多くの場所 - [完全なリスト](/manual/appendix/macros/supported_by_location_user)を参照

[comment]: # ({/c282a934-3e220640})

[comment]: # ({e3755145-e3755145})
##### グローバルマクロとホストマクロの一般的な使用例

-   グローバルマクロを複数の場所で使用し、マクロの値を変更すると、ワンクリックですべての場所に設定変更が適用されます。
-   ホスト固有の属性（パスワード、ポート番号、ファイル名、正規表現など）を持つテンプレートを活用します。

[comment]: # ({/e3755145-e3755145})

[comment]: # ({6b1da1a4-60e46db2})
::: notetip
グローバルマクロの追加、更新、削除はすべてのホストのインクリメンタル設定の更新を強制するため、グローバルマクロよりもホストマクロの使用を推奨します。詳細は、[Passive and active agent checks](/manual/appendix/items/activepassive#active-checks)を参照してください。
:::

[comment]: # ({/6b1da1a4-60e46db2})

[comment]: # ({6f1c5f99-561314a3})
#### 設定

ユーザーマクロを定義するには、Webインターフェースの該当する場所に移動します。

-   グローバルマクロの場合は、*Administration → Macros* を開きます
-   ホストおよびテンプレートレベルのマクロの場合は、ホストまたはテンプレートのプロパティを開き、*Macros* タブを探します

ユーザーマクロには、次の属性があります。

![](../../../../assets/en/manual/config/macros/user_macros.png){width="600"}

|Parameter|Description|
|--|--------|
|*Macro*|マクロ名。名前は中括弧で囲み、ドル記号で始める必要があります。<br>例: {$FRONTEND\_URL}。マクロ名に使用できる文字は、**A-Z**（大文字のみ）、**0-9**、**\_**、**.** です。|
|*Value*|マクロの値。3種類の値タイプがサポートされています:<br>**Text**（デフォルト） - プレーンテキストの値<br>**[Secret text](/manual/config/macros/secret_macros#secret-text)** - 値はアスタリスクでマスクされます<br> **[Vault secret](/manual/config/macros/secret_macros#vault-secret)** - 値には [vault secret](/manual/config/secrets) へのパス/クエリが含まれます。<br><br>値タイプを変更するには、値入力欄の末尾にあるボタンをクリックします。<br><br>ユーザーマクロの値の最大長は 2048 文字です。|
|*Description*|このマクロに関する追加情報を記載するためのテキストフィールドです。|

ユーザーマクロを設定する際は、次のコンテキスト固有の動作に**注意**してください。

-   ユーザーマクロがテンプレートのアイテムまたはトリガーで使用されている場合は、それらのマクロをテンプレートにも追加することを検討してください（グローバルに定義されている場合でも同様です）。そうすることで、*Text* タイプのマクロは、テンプレートを XML にエクスポートして別のシステムにインポートした後でも、期待どおりに動作します（secret macro の値は [エクスポートされません](/manual/xml_export_import)）
-   ユーザーマクロがトリガー式で使用されている場合、それらのマクロはパラメーターまたは定数を参照している場合にのみ解決されます。ホスト、アイテムキー、関数、演算子、または別のトリガー式を参照している場合は解決されません（secret macro はトリガー式では使用できません）
-   ユーザーマクロが、ホストプロトタイプを含む低レベルディスカバリルールを持つホストで使用されている場合、[発見されたホスト](/manual/discovery/low_level_discovery/host_prototypes#discovered-hosts) は、そのホストで定義されたすべてのユーザーマクロを継承します

[comment]: # ({/6f1c5f99-561314a3})

[comment]: # ({4c860844-4c860844})
#### 例

[comment]: # ({/4c860844-4c860844})

[comment]: # ({b9cf8f56-b9cf8f56})
##### 例 1

"Status of SSH daemon" item キーにホストレベルマクロを使用する。

`net.tcp.service[ssh,,{$SSH_PORT}]`

この項目は、複数のホストで **{$SSH_PORT}** の値が定義されている場合に、複数のホストに割り当てることができます。

[comment]: # ({/b9cf8f56-b9cf8f56})

[comment]: # ({0fa7cf4a-0fa7cf4a})
##### 例 2

"CPU load is too high" トリガー でのホストレベルマクロの使用:

`last(/ca_001/system.cpu.load[,avg1])>{$MAX_CPULOAD}`

このようなトリガーは、個々のホストで編集するのではなく、テンプレート上で作成されることになります。

::: notetip
値の量を関数のパラメーターとして使用する場合（例えば, **max(/host/key,\#3)**), <br>
SOME\_PERIOD => \#3<br>
というようにマクロ定義にハッシュ記号を入れてください。
:::

[comment]: # ({/0fa7cf4a-0fa7cf4a})

[comment]: # ({36dc94ca-36dc94ca})
##### 例 3

"CPU load is too high" トリガーで2つのマクロを使用する:

`min(/ca_001/system.cpu.load[,avg1],{$CPULOAD_PERIOD})>{$MAX_CPULOAD}`

マクロはトリガー関数（この例では関数**min()**）のパラメータとして使用することができることに注意。

[comment]: # ({/36dc94ca-36dc94ca})

[comment]: # ({0dabfae5-0dabfae5})
##### 例 4

agent の利用不可条件と item の更新間隔を同期させる。:

-   {INTERVAL} マクロを定義し、item の更新間隔に使用する。
-   {INTERVAL} を agent 使用不可トリガーのパラメータとして使用する。

`nodata(/ca_001/agent.ping,{$INTERVAL})=1`

[comment]: # ({/0dabfae5-0dabfae5})

[comment]: # ({2d346656-0f8052f1})
##### 例5

勤務時間の設定を集中管理する:

- グローバルマクロ{$WORKING\_HOURS}を`1-5,09:00-18:00`に設定する
- *管理* → *一般* → *GUI*の*勤務時間*フィールドで使用する
- *ユーザー* → *ユーザー*の*メディア*タブの*有効期間*フィールドで使用する
- 勤務時間中により頻繁にアイテムのポーリングを行うために使用する

![](../../../../assets/en/manual/config/macros/usermacro_example5.png)

- *アクション*の*期間*条件で使用する
- 必要に応じて*管理* → *マクロ*で勤務時間を調整する

[comment]: # ({/2d346656-0f8052f1})

[comment]: # ({3c2ac944-3c2ac944})
##### 例 6

ホストプロトタイプマクロを使用して、検出されたホストの item を設定します:

ホストプロトタイプで、{$SNMPVALUE} を {\#SNMPVALUE}[low-level discovery](/manual/config/macros/lld_macros) マクロ値として定義します:

![](../../../../assets/en/manual/config/macros/usermacro_example6.png)

-   ホストプロトタイプに *Generic SNMPv2* テンプレートを割り当てます。
-   {SNMPVALUE} を使用します。汎用SNMPv2*テンプレート項目の *SNMP OID* フィールドに {$SNMPVALUE} を使用します。

[comment]: # ({/3c2ac944-3c2ac944})

[comment]: # ({44ca625a-44ca625a})
#### ユーザーマクロのコンテキスト

[user macros with context](/manual/config/macros/user_macros_context) を参照してください。

[comment]: # ({/44ca625a-44ca625a})