本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用訊息範本
<a name="alert-message-templates"></a>

****  
本文件主題專為支援 Grafana **8.x 版的 Grafana** 工作區而設計。  
如需支援 Grafana 10.x 版的 Grafana 工作區，請參閱[使用 Grafana 第 10 版](using-grafana-v10.md)。  
如需支援 Grafana 9.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 9 版](using-grafana-v9.md)。

透過 傳送的通知[使用聯絡點](alert-contact-points.md)是使用*簡訊範本*建置。Grafana 的預設範本是以 [Go 範本系統](https://golang.org/pkg/text/template)為基礎，其中某些欄位會評估為文字，而其他則評估為 HTML （這可能會影響逸出）。

由於大多數的聯絡點欄位都可以建立範本，因此您可以建立可重複使用的自訂範本，並在多個聯絡點中使用它們。[範本資料](#alert-template-data) 主題會列出可用於範本化的變數。

**使用 範本**

範本用於建立訊息。例如，使用 Slack 提醒訊息，您可以在聯絡點中設定標題和內文。下列範例示範如何使用預設範本來建立標題，其中包含觸發和解決的提醒計數，以及列出提醒及其狀態的內文。
+ **標題**：

  ```
  {{ len .Alerts.Firing }} firing, {{ len .Alerts.Resolved }} resolved
  ```
+ **文字內文**：

  ```
  {{ range .Alerts }}{{ .Status }}: {{ .Labels.alertname }}
  {{end }}
  ```

您可以建立自己的自訂範本，如下列範例所示。
+ **標題**：

  ```
  {{ template "slack.default.title" .}}
  ```
+ **文字內文**：

  ```
  {{ template "mymessage" .}}
  ```

以下是範例範本。

```
{{ define "myalert" }}
  [{{.Status}}] {{ .Labels.alertname }}

  Labels:
  {{ range .Labels.SortedPairs }}
    {{ .Name }}: {{ .Value }}
  {{ end }}

  {{ if gt (len .Annotations) 0 }}
  Annotations:
  {{ range .Annotations.SortedPairs }}
    {{ .Name }}: {{ .Value }}
  {{ end }}
  {{ end }}

  {{ if gt (len .SilenceURL ) 0 }}
    Silence alert: {{ .SilenceURL }}
  {{ end }}
  {{ if gt (len .DashboardURL ) 0 }}
    Go to dashboard: {{ .DashboardURL }}
  {{ end }}
{{ end }}
```

下列程序說明如何建立、編輯和刪除自訂訊息範本。

**建立訊息範本**

1. 在 Grafana 主控台的 Grafana 功能表中，選擇**警示 **（鈴鐺） 圖示以開啟**警示**頁面。

1. 選擇**聯絡點**。

1. 從 **Alertmanager** 下拉式清單中，選取您要為其建立訊息範本的 Alertmanager 執行個體。預設為 Grafana Alertmanager。

1. 選擇**新增範本**。

1. 新增描述性**名稱**。

1. 新增範本**的內容**，例如：

   ```
   {{ define "mymessage" }}
     {{ range .Alerts }}
       [{{ .Status }}] {{ range .Labels }} {{ .Name }}={{.Value }}{{end}}
     {{ end }}
   {{ end }}
   ```

   內容區段中的`define`標籤會指派範本名稱。此標籤為選用，省略時，範本名稱衍生自**名稱**欄位。指定兩者時，最佳實務是保持兩者相同。

1. 選擇**儲存範本**。

**注意**  
提醒訊息範本中的 HTML 會轉譯為文字，並逸出控制字元。Grafana 不支援在產生的通知中轉譯 HTML。

**編輯訊息範本**

1. 在**提醒**頁面中，選擇**聯絡點**以開啟聯絡點清單。

1. 在**範本表格中**，尋找您要編輯的範本，然後選擇**編輯**圖示 （筆）。

1. 進行變更，然後選擇**儲存範本**。

**刪除訊息範本**

1. 在**提醒**頁面中，選擇**聯絡點**以開啟聯絡點清單。

1. 在**範本表格中**，尋找您要移除的範本，然後選擇**刪除**圖示 （垃圾桶）。

1. 選擇**是，刪除**以刪除範本。

**巢狀範本**

您可以在其他範本中內嵌範本。

例如，您可以使用`define`關鍵字定義範本片段：

```
{{ define "mytemplate" }}
  {{ len .Alerts.Firing }} firing. {{ len .Alerts.Resolved }} resolved.
{{ end }}
```

然後，您可以使用 `template`關鍵字在此片段中嵌入自訂範本。例如：

```
Alert summary:
{{ template "mytemplate" . }}
```

您可以使用下列內建範本選項來內嵌自訂範本。


| 名稱 | 備註 | 
| --- | --- | 
|  `default.title`  |  顯示高階狀態資訊。  | 
|  `default.message`  |  提供射擊和已解決警示的格式化摘要。  | 

**自訂範本範例**

以下是如何使用自訂範本的範例。

轉譯單一提醒的範本：

```
{{ define "myalert" }}
  [{{.Status}}] {{ .Labels.alertname }}

  Labels:
  {{ range .Labels.SortedPairs }}
    {{ .Name }}: {{ .Value }}
  {{ end }}

  {{ if gt (len .Annotations) 0 }}
  Annotations:
  {{ range .Annotations.SortedPairs }}
    {{ .Name }}: {{ .Value }}
  {{ end }}
  {{ end }}

  {{ if gt (len .SilenceURL ) 0 }}
    Silence alert: {{ .SilenceURL }}
  {{ end }}
  {{ if gt (len .DashboardURL ) 0 }}
    Go to dashboard: {{ .DashboardURL }}
  {{ end }}
{{ end }}
```

轉譯整個通知訊息的範本：

```
{{ define "mymessage" }}
  {{ if gt (len .Alerts.Firing) 0 }}
    {{ len .Alerts.Firing }} firing:
    {{ range .Alerts.Firing }} {{ template "myalert" .}} {{ end }}
  {{ end }}
  {{ if gt (len .Alerts.Resolved) 0 }}
    {{ len .Alerts.Resolved }} resolved:
    {{ range .Alerts.Resolved }} {{ template "myalert" .}} {{ end }}
  {{ end }}
{{ end }}
```

## 範本資料
<a name="alert-template-data"></a>

下列資料會傳遞至訊息範本。


| 名稱 | 類型 | 備註 | 
| --- | --- | --- | 
|  `Receiver`  |  string  |  正在傳送通知的聯絡點名稱。  | 
|  `Status`  |  string  |  如果至少一個提醒正在觸發，則觸發，否則會解決。  | 
|  `Alerts`  |  警示  |  此通知中包含的提醒物件清單 （請參閱下方）。  | 
|  `GroupLabels`  |  KeyValue  |  這些提醒分組依據的標籤。  | 
|  `CommonLabels`  |  KeyValue  |  此通知中包含的所有提醒通用的標籤。  | 
|  `CommonAnnotations`  |  KeyValue  |  此通知中所有提醒的常見註釋。  | 
|  `ExternalURL`  |  string  |  傳送通知的 Grafana 的返回連結。如果使用外部 Alertmanager，請返回此 Alertmanager 的連結。  | 

`Alerts` 類型會公開兩個用於篩選傳回提醒的函數。
+ `Alerts.Firing` – 傳回射擊提醒的清單。
+ `Alerts.Resolved` – 傳回已解析警示的清單。

**提醒 （類型）**

提醒類型包含下列資料。


| 名稱 | 類型 | 備註 | 
| --- | --- | --- | 
|  狀態  |  string  |  `firing` 或 `resolved`  | 
|  標籤  |  KeyValue  |  連接到提醒的一組標籤。  | 
|  註釋  |  KeyValue  |  附加到提醒的一組註釋。  | 
|  StartsAt  |  time.Time  |  警示開始觸發的時間。  | 
|  EndsAt  |  time.Time  |  只有在已知警示的結束時間時才設定。否則，請設定為自上次收到提醒以來的可設定逾時期間。  | 
|  GeneratorURL  |  string  |  Grafana 或外部 Alertmanager 的後退連結。  | 
|  SilenceURL  |  string  |  連結至 的 grafana 靜音，並預先填入此提醒的標籤。僅適用於 Grafana 受管提醒。  | 
|  DashboardURL  |  string  |  如果警示規則屬於一個，則連結至 grafana 儀表板。僅適用於 Grafana 受管提醒。  | 
|  PanelURL  |  string  |  如果警示規則屬於一個，則連結至 grafana 儀表板面板。僅適用於 Grafana 受管提醒。  | 
|  指紋  |  string  |  可用來識別提醒的指紋。  | 
|  ValueString  |  string  |  字串，其中包含提醒中每個減少表達式的標籤和值。  | 

**KeyValue 類型**

`KeyValue` 類型是一組代表標籤和註釋的鍵/值字串對。

除了直接存取存放為 的資料之外`KeyValue`，還有排序、移除和轉換資料的方法。


| 名稱 | 引數 | 傳回值 | 備註 | 
| --- | --- | --- | --- | 
|  SortedPairs  |    |  已排序的索引鍵和值字串對清單  |    | 
|  移除  |  【】字串  |  KeyValue  |  傳回不含指定金鑰的金鑰/值映射複本。  | 
|  名稱  |    |  【】字串  |  標籤名稱清單  | 
|  值  |    |  【】字串  |  標籤值清單  | 



## 範本函數
<a name="alert-template-functions"></a>

使用範本函數，您可以處理標籤和註釋來產生動態通知。下列 函數可供使用。


| 名稱 | 引數類型 | 傳回類型 | Description | 
| --- | --- | --- | --- | 
|  `humanize`  |  數字或字串  |  string  |  使用指標字首，將數字轉換為更易讀的格式。  | 
|  `humanize1024`  |  數字或字串  |  string  |  就像人文化一樣，但使用 1024 作為基礎，而不是 1000。  | 
|  `humanizeDuration`  |  數字或字串  |  string  |  以秒為單位將持續時間轉換為更易於讀取的格式。  | 
|  `humanizePercentage`  |  數字或字串  |  string  |  將比率值轉換為 100 的分數。  | 
|  `humanizeTimestamp`  |  數字或字串  |  string  |  以秒為單位將 Unix 時間戳記轉換為更易於讀取的格式。  | 
|  `title`  |  string  |  string  |  strings.Title，將每個單字的第一個字元大寫。  | 
|  `toUpper`  |  string  |  string  |  strings.ToUpper，將所有字元轉換為大寫。  | 
|  `toLower`  |  string  |  string  |  strings.ToLower， 會將所有字元轉換為小寫。  | 
|  `match`  |  模式、文字  |  boolean  |  未錨定 regexp 比對的 regexp.MatchString 測試。  | 
|  `reReplaceAll`  |  模式、替換、文字  |  string  |  Regexp.ReplaceAllString Regexp 替換，未錨定。  | 
|  `graphLink`  |  string - 具有 `expr`和 `datasource` 欄位的 JSON 物件  |  string  |  在探索中傳回指定表達式和資料來源的圖形檢視路徑。  | 
|  `tableLink`  |  string - 具有 `expr`和 `datasource` 欄位的 JSON 物件  |  string  |  在探索中傳回指定表達式和資料來源的表格式檢視路徑。  | 
|  `args`  |  【】 介面\$1\$1  |  map【string】interface\$1\$1  |  將物件清單轉換為具有索引鍵的映射，例如 arg0、arg1。使用此函數將多個引數傳遞至 範本。  | 
|  `externalURL`  |  無  |  string  |  傳回代表外部 URL 的字串。  | 
|  `pathPrefix`  |  無  |  string  |  傳回外部 URL 的路徑。  | 

下表顯示使用每個 函數的範例。


| 函式 | TemplateString | Input | 預期 | 
| --- | --- | --- | --- | 
|  人文化  |  \$1 人文化 \$1value \$1  |  1234567.0  |  12.35 公尺  | 
|  humanize1024  |  \$1 humanize1024 \$1value \$1  |  1048576.0  |  1Mi  | 
|  humanizeDuration  |  \$1 humanizeDuration \$1value \$1  |  899.99  |  14 公尺 59 秒  | 
|  humanizePercentage  |  \$1 humanizePercentage \$1value \$1  |  0.1234567  |  12.35%  | 
|  humanizeTimestamp  |  \$1 humanizeTimestamp \$1value \$1  |  1435065584.128  |  2015-06-23 13：19：44.128 \$10000 UTC  | 
|  標題  |  \$1 \$1value \$1 標題 \$1  |  aa bB CC  |  Aa Bb Cc  | 
|  toUpper  |  \$1 \$1value \$1 toUpper \$1  |  aa bB CC  |  AA BB CC  | 
|  toLower  |  \$1 \$1value \$1 toLower \$1  |  aa bB CC  |  aa bb cc  | 
|  match  |  \$1 match "a\$1" \$1labels.instance \$1  |  aa  |  true  | 
|  reReplaceAll  |  \$1\$1 reReplaceAll "localhost：(.\$1)" "my.domain：\$11" \$1labels.instance \$1\$1  |  localhost：3000  |  my.domain：3000  | 
|  graphLink  |  \$1\$1 graphLink "\$1\$1"expr\$1"： \$1"up\$1"， \$1"datasource\$1"： \$1"gdev-prometheus\$1"\$1" \$1\$1  |    |  /explore？left=【"now-1h"，"now"，"gdev-prometheus"，\$1"datasource"："gdev-prometheus"，"expr"："up"，"instant"：false，"range"：true\$1】  | 
|  tableLink  |  \$1\$1 tableLink "\$1\$1"expr\$1"：\$1"up\$1"、\$1"datasource\$1"：\$1"gdev-prometheus\$1"\$1" \$1\$1  |    |  /explore？left=【"now-1h"，"now"，"gdev-prometheus"，\$1"datasource"："gdev-prometheus"，"expr"："up"，"instant"：true，"range"：false\$1】  | 
|  args  |  \$1\$1define "x"\$1\$1\$1\$1.arg0\$1\$1 \$1\$1.arg1\$1\$1\$1\$1end\$1\$1\$1\$1template "x" (args 1 "2")\$1\$1  |    |  1 2  | 
|  externalURL  |  \$1 externalURL \$1  |    |  http：//localhost/path/prefix  | 
|  pathPrefix  |  \$1 pathPrefix \$1  |    |  /path/prefix  |