本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 範本和變數 **** 本文件主題專為支援 Grafana **8.x 版的 Grafana** 工作區而設計。 如需支援 Grafana 12.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 12 版](using-grafana-v12.md)。 如需支援 Grafana 10.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 10 版](using-grafana-v10.md)。 如需支援 Grafana 9.x 版的 Grafana 工作區，請參閱 [使用 Grafana 第 9 版](using-grafana-v9.md)。 變數是值的預留位置。您可以在指標查詢和面板標題中使用變數。變數可讓您建立更具互動性和動態的儀表板。您可以在指標查詢中使用變數，而不是硬式編碼，例如伺服器、應用程式和感應器名稱。 變數會顯示為儀表板頂端的下拉式清單。當您使用儀表板頂端的下拉式清單變更值時，面板的指標查詢會反映新值。 對於想要允許瀏覽者快速調整視覺效果，但不想提供完整編輯許可的管理員來說，這些功能特別有用。Grafana 檢視器可以使用變數。 透過使用變數和範本，您可以單一來源儀表板。如果您有多個相同的資料來源或伺服器，您可以建立一個儀表板，並使用變數來變更您正在檢視的內容。這可簡化維護和維護。 如需支援的變數類型清單，以及新增每種變數類型的說明，請參閱 [變數類型](variables-types.md) ## 範本 *範本*是包含變數的任何查詢。 例如，如果您管理儀表板來監控多個伺服器，您可以為每個伺服器建立儀表板。或者，您可以建立一個儀表板，並將面板與範本查詢搭配使用，如下列範例所示。 ``` wmi_system_threads{instance=~"$server"} ``` 變數值一律會使用語法 同步至 URL`var-=value`。 ## 變數最佳實務 變數下拉式清單會依其在**儀表板設定**中的變數清單中列出的順序顯示。 將您經常變更的變數放在頂端，以便它們首先顯示在儀表板最左側。 ## 變數語法 面板標題和指標查詢可以使用兩種不同的語法來查看變數： + `$varname` 此語法更容易閱讀，如下列範例所示：`apps.frontend.$server.requests.count`。不過，您無法在單字中間使用變數。 + `${var_name}` 當您想要在表達式中間插入變數時，請使用此語法。 + `${var_name:}` 此格式可讓您進一步控制 Grafana 如何插補值。如需詳細資訊，請參閱[進階變數格式選項](#advanced-variable-format-options)。 將查詢傳送至資料來源之前，會*插入*查詢，這表示變數會取代為目前的值。在插補期間，可能會*逸出*變數值，以符合查詢語言及其使用位置的語法。例如，在 Prometheus 查詢中用於 regex 表達式的變數將被 regex 逸出。如需插補期間值逸出的詳細資訊，請參閱資料來源特定的文件主題。 如需覆寫資料來源預設格式的進階語法資訊，請參閱 [進階變數格式選項](#advanced-variable-format-options)。 ## 其他變數選項 本節說明其他可用的變數選項。 ### 輸入變數選取選項 您可以使用**選擇選項**來管理變數選項選擇。所有選擇選項都是選用的，預設為關閉。 #### 多值 如果您開啟此選項，則變數下拉式清單支援同時選取多個選項。如需詳細資訊，請參閱[格式化多值變數](#formatting-multi-value-variables)。 #### 包含所有選項 Grafana 工作區會將 `All`選項新增至變數下拉式清單。如果最終使用者選取此選項，則會選取所有變數選項。 #### 自訂所有值 只有在選取**包含所有選項時，才會顯示此選項**。 若要定義`All`選項的值，請在**自訂所有值**欄位中輸入 regex、glob 或 Lucene 語法。 根據預設， `All`值包含合併表達式中的所有選項。這可能會變得很長，並可能有效能問題。有時候，最好指定自訂的所有值，例如萬用字元 regex。 當您在自訂**所有值**選項中使用自訂 regex、glob 或 Lucene 語法時，它永遠不會逸出，因此您必須考慮資料來源的有效值為何。 ### 進階變數格式選項 變數插補的格式取決於資料來源，但在某些情況下，您可能想要變更預設格式。 例如，MySQL 資料來源的預設值是以逗號分隔的引號聯結多個值：`'server01','server02'`。在某些情況下，您可能想要有一個逗號分隔的字串，不含引號：`server01,server02`。若要這樣做，請使用下列進階變數格式化選項。 #### 一般語法 語法: `${var_name:option}` 如果指定了任何無效的格式選項，則 `glob`為預設選項或備用選項。 #### CSV 將具有多個值的變數格式化為逗號分隔字串。 ``` servers = ['test1', 'test2'] String to interpolate: '${servers:csv}' Interpolation result: 'test1,test2' ``` #### 分散式 - OpenTSDB 使用 OpenTSDB 自訂格式的多個值格式化變數。 ``` servers = ['test1', 'test2'] String to interpolate: '${servers:distributed}' Interpolation result: 'test1,servers=test2' ``` #### 雙引號 將單一值和多值變數格式化為逗號分隔字串、以 逸出`"`每個值`\"`，並使用 引號引出每個值`"`。 ``` servers = ['test1', 'test2'] String to interpolate: '${servers:doublequote}' Interpolation result: '"test1","test2"' ``` #### Glob - 石灰色 將具有多個值的變數格式化為 glob （適用於 Graphite 查詢）。 ``` servers = ['test1', 'test2'] String to interpolate: '${servers:glob}' Interpolation result: '{test1,test2}' ``` #### JSON 將具有多個值的變數格式化為逗號分隔字串。 ``` servers = ['test1', 'test2'] String to interpolate: '${servers:json}' Interpolation result: '["test1", "test2"]' ``` #### Lucene - OpenSearch 使用 OpenSearch 的 Lucene 格式的多個值格式化變數。 ``` servers = ['test1', 'test2'] String to interpolate: '${servers:lucene}' Interpolation result: '("test1" OR "test2")' ``` #### 百分比編碼 格式化單一值和多值變數，以用於 URL 參數。 ``` servers = ['foo()bar BAZ', 'test2'] String to interpolate: '${servers:percentencode}' Interpolation result: 'foo%28%29bar%20BAZ%2Ctest2' ``` #### 管道 將具有多個值的變數格式化為管道分隔字串。 ``` servers = ['test1.', 'test2'] String to interpolate: '${servers:pipe}' Interpolation result: 'test1.|test2' ``` #### Raw 關閉資料來源特定的格式，例如 SQL 查詢中的單引號。 ``` servers = ['test1.', 'test2'] String to interpolate: '${var_name:raw}' Interpolation result: '{test.1,test2}' ``` #### Regex 將具有多個值的變數格式化為 regex 字串。 ``` servers = ['test1.', 'test2'] String to interpolate: '${servers:regex}' Interpolation result: '(test1\.|test2)' ``` #### 單引號 將單值和多值變數格式化為逗號分隔字串，以 逸出每個值`'`，`\'`並使用 引用每個值`'`。 ``` servers = ['test1', 'test2'] String to interpolate: '${servers:singlequote}' Interpolation result: "'test1','test2'" ``` #### Sqlstring 將單值和多值變數格式化為逗號分隔字串，以 逸出每個值`'`，`''`並使用 引用每個值`'`。 ``` servers = ["test'1", "test2"] String to interpolate: '${servers:sqlstring}' Interpolation result: "'test''1','test2'" ``` #### 文字 將單值和多值變數格式化為文字表示法。對於單一變數，它只會傳回文字表示法。對於多值變數，它會傳回結合 的文字表示法`+`。 ``` servers = ["test1", "test2"] String to interpolate: '${servers:text}' Interpolation result: "test1 + test2" ``` ### 格式化多值變數 插入已選取多個值的變數很棘手，因為它不會直接將多個值格式化為字串，在使用該變數的特定內容中有效。Grafana 嘗試透過讓每個資料來源外掛程式通知範本插補引擎要用於多個值的格式來解決此問題。 **注意** 變數上的**自訂所有值**選項必須為空白，Grafana 才能將所有值格式化為單一字串。如果保留空白，則 Grafana 會串連 （加在一起） 查詢中的所有值。類似 的內容`value1,value2,value3`。如果使用自訂`all`值，則值會改為類似 `*`或 `all`。 #### 具有 Graphite 資料來源的多值變數 Graphite 使用 glob 表達式。在此情況下，具有多個值的變數會被插入，就`{host1,host2,host3}`好像目前的變數值是 *host1*、*host2* 和 *host3*。 #### 具有 Prometheus 或 InfluxDB 資料來源的多值變數 InfluxDB 和 Prometheus 使用 regex 表達式，因此相同的變數會插入為 `(host1|host2|host3)`。每個值也會逸出 regex。如果沒有，具有 regex 控制字元的值會破壞 regex 表達式。 #### 具有彈性資料來源的多值變數 Amazon OpenSearch 使用 Lucene 查詢語法，因此相同的變數會格式化為 `("host1" OR "host2" OR "host3")`。在這種情況下，每個值都必須逸出，以便該值只包含 Lucene 控制單字和引號。 #### 對格式化進行故障診斷 自動逸出和格式化可能會導致問題。很難掌握問題背後的邏輯，特別是 InfluxDB 和 Prometheus，其中使用 regex 語法需要 變數用於 regex 運算子內容。 如果您不希望 Grafana 執行此自動 regex 逸出和格式化，您必須執行下列其中一項操作： + 關閉**多值****包含所有選項**選項。 + 使用 【原始變數格式】({{< relref "advanced-variable-format-options.md\#raw" >}})。 ### 使用 regex 篩選變數 使用 Regex 查詢選項，您可以篩選變數查詢傳回的選項清單，或修改傳回的選項。 本節說明如何使用 regex 來篩選和修改變數下拉式清單中的值。 使用 Regex 查詢選項，您可以篩選變數查詢傳回的選項清單，或修改傳回的選項。如需詳細資訊，請參閱[規則表達式](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions)。 篩選下列選項清單的範例： ``` backend_01 backend_02 backend_03 backend_04 ``` #### 篩選，只`02`傳回以 `01`或 結尾的選項 Regex： ``` /.*[01|02]/ ``` 結果： ``` backend_01 backend_02 ``` #### 使用 regex 擷取群組篩選和修改選項，以傳回部分文字 Regex： ``` /.*(01|02)/ ``` 結果： ``` 01 02 ``` #### 篩選和修改 - Prometheus 範例 選項清單： ``` up{instance="demo.robustperception.io:9090",job="prometheus"} 1 1521630638000 up{instance="demo.robustperception.io:9093",job="alertmanager"} 1 1521630638000 up{instance="demo.robustperception.io:9100",job="node"} 1 1521630638000 ``` Regex： ``` /.*instance="([^"]*).*/ ``` 結果： ``` demo.robustperception.io:9090 demo.robustperception.io:9093 demo.robustperception.io:9100 ``` #### 使用具名文字和值擷取群組進行篩選和修改 使用具名擷取群組，您可以從變數查詢傳回的選項中擷取個別的「文字」和「值」部分。變數下拉式清單可以包含每個可選取值的易記名稱。 例如，查詢 `node_hwmon_chip_names` Prometheus 指標時， `chip_name` 比 `chip`值更友善。從下列變數查詢結果開始。 ``` node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_0",chip_name="enp216s0f0np0"} 1 node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_1",chip_name="enp216s0f0np1"} 1 node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_2",chip_name="enp216s0f0np2"} 1 node_hwmon_chip_names{chip="0000:d7:00_0_0000:d8:00_3",chip_name="enp216s0f0np3"} 1 ``` 透過下列 Regex 傳遞。 ``` /chip_name="(?[^"]+)|chip="(?[^"]+)/g ``` 會產生下列下拉式清單。 ``` Display Name Value ------------ ------------------------- enp216s0f0np0 0000:d7:00_0_0000:d8:00_0 enp216s0f0np1 0000:d7:00_0_0000:d8:00_1 enp216s0f0np2 0000:d7:00_0_0000:d8:00_2 enp216s0f0np3 0000:d7:00_0_0000:d8:00_3 ``` **注意：**僅支援 `text`和`value`擷取群組名稱。 ### 重複面板或資料列 您可以使用*範本變數*建立動態儀表板。在將查詢傳送至資料庫之前，查詢中的所有變數都會擴展到變數的目前值。使用變數，您可以為所有 服務重複使用單一儀表板。 範本變數對於動態變更整個儀表板的查詢非常有用。如果您希望 Grafana 根據您選取的值動態建立新的面板或資料列，您可以使用*重複*功能。 #### 重複面板 如果您有開啟 `Multi-value`或 `Include all value`選項的變數，您可以選擇一個面板，並讓 Grafana 為每個選取的值重複該面板。您可以在面板編輯模式中*的一般索引標籤*下找到*重複*功能。 `direction` 控制面板的排列方式。 如果您選擇 `horizontal`，面板會side-by-side排列。Grafana 會自動調整每個重複面板的寬度，以便填滿整個資料列。目前，您無法將資料列上的其他面板與重複的面板混合。 設定 `Max per row`以告知 Grafana 您最多想要每一列多少個面板。預設為 *4*。 如果您選擇 `vertical`，面板會在資料欄中從上到下進行排列。重複面板的寬度與正在重複的第一個面板 （原始範本） 相同。 僅對第一個面板 （原始範本） 進行變更。若要讓變更在所有面板上生效，您需要啟動動態儀表板重建。您可以透過變更變數值 （即重複的基礎） 或重新載入儀表板來執行此操作。 **注意** 重複面板需要變數，才能選取一或多個項目。您無法重複面板零次來隱藏面板。 #### 重複資料列 如上所示，如果您有使用 `Multi-value`或 `Include all value` 選擇選項設定的變數，您也可以重複資料列。 若要開啟此功能，您必須先使用新增*面板功能表來新增*資料*列*。然後暫停資料列標題，然後選擇齒輪按鈕以存取`Row Options`組態面板。然後，您可以選取要為其重複資料列的變數。 最佳實務也是在資料列標題中使用變數。