[comment]: # translation:outdated
[comment]: # ({d30dc182-d30dc182})
# 2 ユーザーマクロ
[comment]: # ({/d30dc182-d30dc182})
[comment]: # ({d8f2997a-3e220640})
#### 概要
Zabbixでは、[supported](/manual/appendix/macros/supported_by_location)マクロに加え、より柔軟性の高い
ユーザーマクロがサポートされています。
ユーザマクロは、グローバル、テンプレート、ホストレベルで定義することができます。これらのマクロは
特別な構文を持っています:
{$MACRO}
Zabbixは以下の優先順位に従ってマクロを解決します:
1. ホストレベルのマクロ (最初にチェックされます)
2. ホストの第1階層のテンプレート(ホストに直接リンクされたテンプレート)に定義されたマクロ(テンプレートIDでソートされます)
3. ホストの第2階層のテンプレートに対して定義されたマクロ (テンプレートIDでソートされます)
4. ホストの第3階層のテンプレートに対して定義されたマクロで、テンプレートID順に並べられます。
5. グローバルマクロ(最後にチェック)
つまり、あるホストにマクロが存在しない場合、Zabbixはホストテンプレートから徐々にマクロを探そうとします。
それでも見つからない場合、グローバルマクロが存在すれば、それを使用します。
::: notewarning
同じレベルのリンクされた複数のテンプレートに**同じ名前**のマクロが存在する場合、IDが最も小さいテンプレートの
マクロが使用されます。したがって、複数のテンプレートに同じ名前のマクロが存在することは、設定上のリスクとなります。
:::
Zabbix がマクロを見つけることができない場合、マクロは解決されません。
::: noteimportant
マクロ（ユーザーマクロを含む）は、複雑な設定をより分かりやすくするため、設定セクション（トリガーリストなど）で
未解決のままになっています。
:::
以下の箇所でユーザーマクロを使用することができます:
- item キーパラメーター
- item の更新間隔とフレキシブル間隔
- トリガー名と説明
- トリガ式パラメータと定数(参照: [examples](#examples))
- 他の多くの場所 - [full list](/manual/appendix/macros/supported_by_location_user)を参照してください
[comment]: # ({/d8f2997a-3e220640})
[comment]: # ({e3755145-e3755145})
##### グローバルマクロとホストマクロの一般的な使用例
- グローバルマクロを複数の場所で使用し、マクロの値を変更すると、ワンクリックですべての場所に設定変更が適用されます。
- ホスト固有の属性（パスワード、ポート番号、ファイル名、正規表現など）を持つテンプレートを活用します。
[comment]: # ({/e3755145-e3755145})
[comment]: # ({be6c0958-60e46db2})
::: ヒント
グローバルマクロを追加、更新、または削除すると、すべてのホストの設定が強制的に増分更新されるため、グローバルマクロではなくホストマクロを使用することをお勧めします。詳細については、[パッシブエージェントチェックとアクティブエージェントチェック](/manual/appendix/items/activepassive#active-checks)を参照してください。
:::
[comment]: # ({/be6c0958-60e46db2})
[comment]: # ({e7589013-561314a3})
#### 設定
ユーザーマクロを定義するには、フロントエンドの対応する場所に移動します。
- グローバルマクロの場合、*Administration → General → Macros* をご覧ください。
- ホストとテンプレートレベルのマクロは、ホストまたはテンプレートのプロパティを開き、*Macros*タブを探します。
::: notetip
ユーザー・マクロがテンプレート内の item またはトリガーで使用されている場合、テンプレート内の item や
トリガーでユーザーマクロが使用される場合、たとえそれがグローバルレベルで定義されていても、そのマクロを
テンプレートに追加することが推奨されます。そうすれば、マクロのタイプが *text* の場合、テンプレートを
XML にエクスポートして別のシステムでインポートしても、期待通りに動作します。
シークレットマクロの値は [exported](/manual/xml_export_import) されません。
:::
ユーザーマクロは以下の属性を持ちます:
{width="600"}
|パラメータ|説明|
|---------|-----------|
|*Macro*|Macro name. The name must be wrapped in curly brackets and start with a dollar sign.
Example: {$FRONTEND\_URL}. The following characters are allowed in the macro names: **A-Z** (uppercase only) , **0-9** , **\_** , **.**|
|*Value*|Macro value. Three value types are supported:
**Text** (default) - plain-text value
**Secret text** - the value is masked with asterisks, which could be useful to protect sensitive information such as passwords or shared keys.
**Vault secret** - the value contains a reference path (as 'path:key', for example “secret/zabbix:password”) to a [Vault secret](/manual/config/secrets)
*Note* that while the value of a secret macro is hidden from sight, the value can be revealed through the use in items. For example, in an external script an 'echo' statement referencing a secret macro may be used to reveal the macro value to the frontend because Zabbix server has access to the real macro value.
To select the value type click on the button at the end of the value input field:
 icon indicates a text macro;
 icon indicates a secret text macro. Upon hovering, the value field transforms into a  button, which allows to enter a new value of the macro (to exit without saving a new value, click the backwards arrow ().
 icon indicates a secret Vault macro.
Maximum length of a user macro value is 2048 characters (255 characters in versions before 5.2.0).|
|*Description*|Text field used to provide more information about this macro.|
::: noteclassic
シークレットマクロを含むURLは、マクロが "\*\*\*\*\*\*" として解決されるため、動作しないことがあります。
:::
::: noteimportant
トリガ式では、ユーザマクロはパラメータや定数を参照する場合に解決されます。
パラメータまたは定数を参照している場合、解決されます。ホスト、item キー、関数、演算子、または別のトリガー式を
参照している場合は、解決されません。シークレット マクロは、トリガ式では使用できません。
:::
[comment]: # ({/e7589013-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)**),
SOME\_PERIOD => \#3
というようにマクロ定義にハッシュ記号を入れてください。
:::
[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]: # ({4ff22155-0f8052f1})
##### 例 5
稼働時間の設定を一元化する。
- グローバルな {$WORKING_HOURS} マクロを作成し、`1-5,09:00-18:00`とします。
- *Administration* → *General* → *GUI* の *Working time* フィールドで使用します。
- *Administration* → *User* → *Media*の *When active* フィールドで使用します。
- 稼働時間中に、より頻繁に item のポーリングを設定するために使用します。
- *Time period* の動作条件で使用します。
- 必要に応じて、*Administration* → *General* → *Macros* で稼働時間を調整します。
[comment]: # ({/4ff22155-0f8052f1})
[comment]: # ({3c2ac944-3c2ac944})
##### 例 6
ホストプロトタイプマクロを使用して、検出されたホストの item を設定します:
ホストプロトタイプで、{$SNMPVALUE} を {\#SNMPVALUE}[low-level discovery](/manual/config/macros/lld_macros) マクロ値として定義します:
- ホストプロトタイプに *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})