使用 Go 的模板語言

本文件主題是針對支援 Grafana 9.x 版的 Grafana 工作區所設計。

如需支援 Grafana 10.x 版的 Grafana 工作區，請參閱。在 Grafana 第 10 版工作

如需支援 Grafana 8.x 版的 Grafana 工作區，請參閱。在 Grafana 第 8 版中工作

您可以使用 Go 的模板語言，文本/模板編寫通知模板。

本節提供 Go 的模板語言和在文本/模板中編寫模板的概述。

圓點

在文本/模板中有一個名為點的特殊光標，並寫成。.您可以將此游標視為變數，其值會根據範本中的使用位置而變更。例如，在通知模板的開頭.是指對ExtendedData象，其中包含許多字段Alerts，包括Status、GroupLabels、CommonLabels、CommonAnnotations和ExternalURL。然而，當在一個列表中使用時，點可能是指別的東西，當range在一個列表中使用時with，或編寫要在其他模板中使用的功能模板時。您可以在中看到此範例建立通知範本，以及中的所有資料和函數範本參考。

開啟和結束標籤

在文本/模板中，模板開始{{和結束與無}}論模板是否打印一個變量還是運行控制結構，如 if 語句。這與其他模板語言（例如 Jinja）不同，其中打印變量使用{{和}}和控制結構使用{%和%}。

Print (列印)

要打印的東西使用{{和的價值}}。您可以列印點的值、點的欄位、函數的結果，以及變數的值。例如，要打印點引用的Alerts字段，ExtendedData您將編寫以下內容：

{{ .Alerts }}

迭代警報

若只要列印每個警示的標籤，而不要列印警示的所有資訊，您可以使range用 a 在中迭代警示ExtendedData：

{{ range .Alerts }}
{{ .Labels }}
{{ end }}

範圍內的點不再是指ExtendedData，而是指Alert. 您可以使{{ .Labels }}用列印每個警示的標籤。這是有效的，因為{{ range .Alerts }}更改點以引用警報列表中的當前警報。當範圍完成時，點被重置為它在範圍開始之前的值，在這個例子中是ExtendedData：

{{ range .Alerts }}
{{ .Labels }}
{{ end }}
{{/* does not work, .Labels does not exist here */}}
{{ .Labels }}
{{/* works, cursor was reset */}}
{{ .Status }}

迭代註釋和標籤

讓我們寫一個模板來打印每個警報的格式The name of the label is $name, and the value is $value，其$name中$value包含每個標籤的名稱和值的標籤。

就像前面的範例一.Alerts樣，使用範圍來重複查看警示，使點指的是警示清單中的目前警示，然後在排序的標籤上使用第二個範圍，以便第二次更新點以參照目前的標籤。在第二個範圍內使用.Name和.Value打印每個標籤的名稱和值：

{{ range .Alerts }}
{{ range .Labels.SortedPairs }}
The name of the label is {{ .Name }}, and the value is {{ .Value }}
{{ end }}
{{ range .Annotations.SortedPairs }}
The name of the annotation is {{ .Name }}, and the value is {{ .Value }}
{{ end }}
{{ end }}

如果陳述

您可以在模板中使用 if 語句。例There are no alerts如，要在沒有警報時進行打印，請編寫.Alerts以下內容：

{{ if .Alerts }}
There are alerts
{{ else }}
There are no alerts
{{ end }}

同

WITH 與 if 語句類似，但與 if 語句不同，with更新點以引用與的值：

{{ with .Alerts }}
There are {{ len . }} alert(s)
{{ else }}
There are no alerts
{{ end }}

Variables

文本/模板中的變量必須在模板中創建。例如，要創建一個使用 dot 的當前值調$variable用的變量，您可以編寫以下內容：

{{ $variable := . }}

您可以在範圍$variable內使用with，也可以在定義變量時引用點的值，而不是點的當前值。

例如，您無法撰寫在第二個範圍內使用{{ .Labels }}的範本，因為這裡的點指的是目前的標籤，而不是目前的警示：

{{ range .Alerts }}
{{ range .Labels.SortedPairs }}
{{ .Name }} = {{ .Value }}
{{/* does not work because in the second range . is a label not an alert */}}
There are {{ len .Labels }}
{{ end }}
{{ end }}

您可以通過定義$alert在第一個範圍內和第二個範圍之前調用的變量來解決此問題：

{{ range .Alerts }}
{{ $alert := . }}
{{ range .Labels.SortedPairs }}
{{ .Name }} = {{ .Value }}
{{/* works because $alert refers to the value of dot inside the first range */}}
There are {{ len $alert.Labels }}
{{ end }}
{{ end }}

範圍與索引

您可以在範圍開頭定義索引和值變數，以取得範圍內每個警示的索引：

{{ $num_alerts := len .Alerts }}
{{ range $index, $alert := .Alerts }}
This is alert {{ $index }} out of {{ $num_alerts }}
{{ end }}

定義範本

您可以定義可以在其他模板中使用的模板，使用define和雙引號模板的名稱。您不應定義與其他範本同名的範本，包括預設範本__subject，例如__text_values_list__text_alert_list、default.title和default.message。如果範本建立的範本與預設範本名稱相同，或是另一個通知範本中的範本，Grafana 可能會使用其中一個範本。當有兩個或兩個以上的範本具有相同名稱時，Grafana 不會阻止或顯示錯誤訊息。

{{ define "print_labels" }}
{{ end }}

內嵌範本

您可以在模板中嵌入定義的模板template，使用雙引號模板的名稱以及應傳遞給模板的光標：

{{ template "print_labels" . }}

將資料傳遞至範本

在一個模板點是指傳遞給模板的值。

例如，如果一個模板被傳遞觸發警報的列表，那麼 dot 指的是觸發警報的列表：

{{ template "print_alerts" .Alerts }}

如果模板傳遞了警報的排序標籤，則點指的是已排序標籤的列表：

{{ template "print_labels" .SortedLabels }}

這在編寫可重複使用的模板時很有用。例如，要打印所有警報，您可以編寫以下內容：

{{ template "print_alerts" .Alerts }}

然後只打印觸發警報，你可以寫這個：

{{ template "print_alerts" .Alerts.Firing }}

這是有效的，因為.Alerts和.Alerts.Firing都是警報列表。

{{ define "print_alerts" }}
{{ range . }}
{{ template "print_labels" .SortedLabels }}
{{ end }}
{{ end }}

說明

您可以使用{{/*和添加註釋*/}}：

{{/* This is a comment */}}

要防止註釋添加換行符，請使用：

{{- /* This is a comment with no leading or trailing line breaks */ -}}

縮排

您可以使用縮排（製表符和空格以及換行符號）來使模板更具可讀性：

{{ range .Alerts }}
  {{ range .Labels.SortedPairs }}
    {{ .Name }} = {{ .Value }}
  {{ end }}
{{ end }}

但是，模板中的縮進也將出現在文本中。接下來，我們將看到如何刪除它。

刪除空格和換行符

在文本/模板中使用{{-和刪-}}除前導和尾隨空格和換行符。

例如，當使用縮進和換行符來使模板更具可讀性時：

{{ range .Alerts }}
  {{ range .Labels.SortedPairs }}
    {{ .Name }} = {{ .Value }}
  {{ end }}
{{ end }}

縮進和換行符也將出現在文本中：

    alertname = "Test"

    grafana_folder = "Test alerts"

您可以從每個範圍開始-}}處更改}}為的文本中刪除縮進和換行符：

{{ range .Alerts -}}
  {{ range .Labels.SortedPairs -}}
    {{ .Name }} = {{ .Value }}
  {{ end }}
{{ end }}

模板中的縮進和換行符現在不在文本中：

alertname = "Test"
grafana_folder = "Test alerts"