本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 變數類型 **** 本文件主題專為支援 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 使用多種類型的變數。 | 變數類型 | Description | | --- | --- | | Query | 查詢產生的值清單，例如指標名稱、伺服器名稱、感應器 IDs、資料中心等。如需詳細資訊，請參閱[新增查詢變數](#add-a-query-variable)。 | | Custom | 使用逗號分隔清單手動定義變數選項。如需詳細資訊，請參閱[新增自訂變數](#add-a-custom-variable)。 | | Text box (文字方塊) | 顯示具有選用預設值的文字輸入欄位。如需詳細資訊，請參閱[新增文字方塊變數](#add-a-text-box-variable)。 | | 常數 | 定義隱藏的常數。如需詳細資訊，請參閱[新增常數變數](#add-a-constant-variable)。 | | 資料來源 | 快速變更整個儀表板的資料來源。如需詳細資訊，請參閱[新增資料來源變數](#add-a-data-source-variable)。 | | Interval | 間隔變數代表時間範圍。如需詳細資訊，請參閱[新增間隔變數](#add-an-interval-variable)。 | | 臨機操作篩選條件 | 金鑰/值篩選條件會自動新增至資料來源的所有指標查詢 （僅限 InfluxDB、Prometheus 和 OpenSearch)。如需詳細資訊，請參閱[新增臨機操作篩選條件](#add-ad-hoc-filters)。 | | 全域變數 | 內建變數，可用於查詢編輯器中的表達式。如需詳細資訊，請參閱[全域變數](#global-variables)。 | | 鏈結變數 | 變數查詢可以包含其他變數。如需詳細資訊，請參閱[鏈結變數](#chained-variables)。 | ## 新增查詢變數 使用查詢變數，您可以撰寫資料來源查詢，傳回指標名稱、標籤值或索引鍵的清單。例如，查詢變數可能會傳回伺服器名稱、感應器 IDs或資料中心的清單。變數值會隨著動態擷取具有資料來源查詢的選項而變更。 查詢表達式可以包含對其他變數的參考，並實際上建立連結的變數。Grafana 會偵測到此情況，並在其中一個連結變數變更時自動重新整理變數。 ### 查詢表達式 每個資料來源的查詢表達式都不同。如需詳細資訊，請參閱資料來源的文件，網址為 [連線至資料來源](AMG-data-sources.md)。 ### 輸入一般選項 **輸入查詢變數的一般選項** 1. 導覽至您要為其建立變數的儀表板，然後選擇頁面頂端的**儀表板設定** （齒輪） 圖示。 1. 在**變數**索引標籤上，選擇**新增**。 1. 輸入變數**的名稱**。 1. 在**類型**清單中，選取**查詢**。 1. （選用） 針對**標籤**，輸入變數下拉式清單的顯示名稱。如果您未輸入顯示名稱，下拉式清單標籤將是變數名稱。 1. 選擇**隱藏**選項： + **無選擇 （空白）** – 變數下拉式清單會顯示變數**名稱**或**標籤**值。這是預設值。 + **標籤** – 變數下拉式清單只會顯示選取的變數值和向下箭頭。 + **變數** – 儀表板上不會顯示變數下拉式清單。 ### 輸入查詢選項 **輸入查詢變數的查詢選項** 1. 在**資料來源**清單中，選取查詢的目標資料來源。如需資料來源的詳細資訊，請參閱 [連線至資料來源](AMG-data-sources.md)。 1. 在**重新整理**清單中，選取變數應該更新選項的時間。 + **從不** - 快取變數查詢，且值不會更新。如果值永遠不會變更，這就沒問題，但如果它們是動態的且變更很大。 + **在儀表板載入**上 - 每次儀表板載入時都會查詢資料來源。這會使儀表板載入速度變慢，因為必須先完成變數查詢，才能初始化儀表板。 + **在時間範圍變更** - 在儀表板時間範圍變更時查詢資料來源。只有當您的變數選項查詢包含時間範圍篩選條件或取決於儀表板時間範圍時，才使用此選項。 1. 在**查詢**欄位中，輸入查詢。 + 查詢欄位會根據您的資料來源而有所不同。有些資料來源具有自訂查詢編輯器。 + 如果您在單一輸入欄位查詢編輯器中需要更多空間，請在欄位右下角的行上暫停並向下拖曳以展開。 1. （選用） 在 **Regex** 欄位中，輸入 regex 表達式來篩選或擷取資料來源查詢傳回的名稱的特定部分。如需範例，請參閱 [使用 regex 篩選變數](templates-and-variables.md#filter-variables-with-regex)。 1. 在**排序**清單中，選取要在下拉式清單中顯示之值的排序順序。預設選項**已停用**，表示將使用資料來源查詢傳回的選項順序。 1. （選用） 輸入**選擇選項**。如需詳細資訊，請參閱[輸入變數選取選項](templates-and-variables.md#enter-variable-selection-options)。 1. 在**預覽值**中，Grafana 工作區會顯示目前變數值的清單。檢閱它們以確保它們符合您的期望。 1. 選擇**新增**，將變數新增至儀表板。 ## 新增自訂變數 針對未變更的值使用*自訂*變數。這可能是數字、字串，甚至是其他變數。 例如，如果您的伺服器名稱或區域名稱未變更，您可以將它們建立為自訂變數，而不是查詢變數。由於它們不會變更，您可以在鏈結變數中使用它們，而不是其他查詢變數。這會減少 Grafana 在更新鏈結變數時必須傳送的查詢數量。如需鏈結變數的詳細資訊，請參閱 [鏈結變數](#chained-variables)。 ### 輸入一般選項 **輸入自訂變數的查詢選項** 1. 導覽至您要為其建立變數的儀表板，然後選擇頁面頂端的**儀表板設定** （齒輪） 圖示。 1. 在**變數**索引標籤上，選擇**新增**。 1. 輸入變數**的名稱**。 1. 在**類型**清單中，選擇**自訂**。 1. （選用） 針對**標籤**，輸入變數下拉式清單的顯示名稱。如果您未輸入顯示名稱，下拉式清單標籤將是變數名稱。 1. 選擇**隱藏**選項： + **無選擇 （空白）** – 變數下拉式清單會顯示變數**名稱**或**標籤**值。這是預設值。 + **標籤** - 變數清單下拉式清單只會顯示選取的變數值和向下箭頭。 + **變數** – 儀表板上不會顯示變數下拉式清單。 ### 輸入自訂選項 **輸入自訂變數的自訂選項** 1. 在**以逗號分隔的值**清單中，在以逗號分隔的清單中輸入此變數的值。您可以包含以冒號分隔的數字、字串、其他變數或鍵值對。 1. （選用） 輸入**選擇選項**。如需詳細資訊，請參閱[輸入變數選取選項](templates-and-variables.md#enter-variable-selection-options)。 1. 在**預覽值**中，Grafana 工作區會顯示目前變數值的清單。檢閱它們以確保它們符合您的期望。 1. 選擇**新增**，將變數新增至儀表板。 ## 新增文字方塊變數 *文字方塊*變數會顯示具有選用預設值的文字輸入欄位。這是最靈活的變數，因為您可以輸入任何值。如果您有高基數的指標，或想要同時更新儀表板中的多個面板，請使用此類型的變數。 ### 輸入一般選項 **輸入文字方塊變數的一般選項** 1. 導覽至您要為其建立變數的儀表板，然後選擇頁面頂端的**儀表板設定** （齒輪） 圖示。 1. 在**變數**索引標籤上，選擇**新增**。 1. 輸入變數**的名稱**。 1. 在**類型**清單中，選取**文字方塊**。 1. （選用） 針對**標籤**，輸入變數下拉式清單的顯示名稱。如果您未輸入顯示名稱，則下拉式清單將為變數名稱。 1. 選擇**隱藏**選項： + **無選擇 （空白）** – 變數下拉式清單會顯示變數**名稱**或**標籤**值。這是預設值。 + **標籤** – 變數下拉式清單只會顯示選取的變數值和向下箭頭。 + **變數** – 儀表板上不會顯示變數下拉式清單。 ### 輸入文字選項 **輸入文字方塊變數的文字選項** 1. （選用） 在**預設值**欄位中，選取變數的預設值。如果您在此欄位中未輸入任何內容，則 Grafana 會顯示一個空文字方塊，您可以在其中輸入文字。 1. 在**預覽值**中，Grafana 會顯示目前變數值的清單。檢閱它們以確保它們符合您的期望。 1. 選擇**新增**，將變數新增至儀表板。 ## 新增常數變數 若要定義隱藏常數，請使用*常*數變數。常數變數適用於您要共用之儀表板的指標路徑字首。匯出儀表板時，常數變數會轉換為匯入選項。 常數變數不靈活。每個常數變數只保留一個值。若要更新它，您必須更新變數設定。 當您有複雜的值必須包含在查詢中，但不想在每個單一查詢中重新輸入時，常數變數很有用。例如，如果您有名為 的伺服器路徑`i-0b6a61efe2ab843gg`，您可以將它取代為名為 的變數`$path_gg`。 ### 輸入一般選項 **輸入常數變數的一般選項** 1. 導覽至您要為其建立變數的儀表板，然後選擇頁面頂端的**儀表板設定** （齒輪） 圖示。 1. 在**變數**索引標籤上，選擇**新增**。 1. 輸入變數**的名稱**。 1. 在**類型**清單中，選取**常數**。 1. （選用） 針對**標籤**，輸入變數下拉式清單的顯示名稱。如果您未輸入顯示名稱，則下拉式清單將為變數名稱。 1. 選擇**隱藏**選項： + **變數** – 儀表板上不會顯示變數下拉式清單。這是預設值。 + **無選擇 （空白）** – 變數下拉式清單會顯示變數**名稱**或**標籤**值。 + **標籤** – 變數下拉式清單只會顯示選取的變數值和向下箭頭。 ### 輸入常數選項 **輸入常數變數的常數選項** 1. 在**值**欄位中，輸入變數值。您可以輸入字母、數字和符號。如果您使用進階變數格式選項，您甚至可以使用萬用字元。如需詳細資訊，請參閱[進階變數格式選項](templates-and-variables.md#advanced-variable-format-options)。 1. 在**預覽值**中，Grafana 工作區會顯示目前的變數值。檢閱它，以確保它符合您的期望。 1. 選擇**新增**，將變數新增至儀表板。 ## 新增資料來源變數 若要快速變更整個儀表板的資料來源，您可以使用*資料來源*變數。如果您有多個資料來源的執行個體，它們可能在不同的環境中很有用。 ### 輸入一般選項 **輸入資料來源變數的一般選項** 1. 導覽至您要為其建立變數的儀表板，然後選擇頁面頂端的**儀表板設定** （齒輪） 圖示。 1. 在**變數**索引標籤上，選擇**新增**。 1. 輸入變數**的名稱**。 1. 在**類型**清單中，選取**資料來源**。 1. （選用） 針對**標籤**，輸入變數下拉式清單的顯示名稱。如果您未輸入顯示名稱，下拉式清單標籤將是變數名稱。 1. 選擇**隱藏**選項： + **無選擇 （空白）** – 變數下拉式清單會顯示變數**名稱**或**標籤**值。這是預設值。 + **標籤** – 變數下拉式清單只會顯示選取的變數值和向下箭頭。 + **變數** – 儀表板上不會顯示變數下拉式清單。 ### 輸入資料來源選項 **輸入資料來源變數的資料來源選項** 1. 在**類型**清單中，選取變數的目標資料來源。如需資料來源的詳細資訊，請參閱 [連線至資料來源](AMG-data-sources.md)。 1. （選用） 針對**執行個體名稱篩選條件**，在變數值下拉式清單中輸入資料來源執行個體選擇的 regex 篩選條件。保持此欄位空白，以顯示所有執行個體。 1. （選用） 輸入**選擇選項**。如需詳細資訊，請參閱[輸入變數選取選項](templates-and-variables.md#enter-variable-selection-options)。 1. 在**預覽值**中，Grafana 會顯示目前變數值的清單。檢閱它們以確保它們符合您的期望。 1. 選擇**新增**，將變數新增至儀表板。 ## 新增間隔變數 使用*間隔*變數來表示時間範圍，例如 `1m`、`1h`、`1d`。您可以將它們視為全儀表板group-by-time命令。間隔變數會變更資料在視覺化中的分組方式。您也可以使用自動選項，傳回每個時間範圍的固定資料點數量。 您可以使用間隔變數做為依時間分組的參數 （適用於 InfluxDB)、日期長條圖間隔 （適用於 OpenSearch) 或摘要函數參數 （適用於 Graphite)。 ### 輸入一般選項 **輸入間隔變數的一般選項** 1. 導覽至您要為其建立變數的儀表板，然後選擇頁面頂端的**儀表板設定** （齒輪） 圖示。 1. 在**變數**索引標籤上，選擇**新增**。 1. 輸入變數**的名稱**。 1. 在**類型**清單中，選取**間隔**。 1. （選用） 針對**標籤**，輸入變數下拉式清單的顯示名稱。如果您未輸入顯示名稱，下拉式清單標籤將是變數名稱。 1. 選擇**隱藏**選項： + **無選擇 （空白）** – 變數下拉式清單會顯示變數**名稱**或**標籤**值。這是預設值。 + **標籤** – 變數下拉式清單只會顯示選取的變數值和向下箭頭。 + **變數** – 儀表板上不會顯示變數下拉式清單。 ### 輸入間隔選項 **輸入間隔變數的間隔選項** 1. 在**值**欄位中，輸入您要顯示在變數下拉式清單中的時間範圍間隔。支援下列時間單位：`s (seconds)`、`m (minutes)`、`h (hours)`、`d (days)`、`M (months)`、 `w (weeks)`和 `y (years)`。您也可以接受或編輯預設值：`1m,10m,30m,1h,6h,12h,1d,7d,14d,30d`。 1. （選用） 如果您想要將 **選項新增至清單，請開啟自動**`auto`選項。使用此選項指定應分割目前時間範圍的次數，以計算目前`auto`時間範圍。如果您將其開啟，則會顯示另外兩個選項： + **步驟計數** – 選取將分割目前時間範圍以計算值的次數，類似於**最大資料點**查詢選項。例如，如果目前可見的時間範圍是 30 分鐘，則`auto`間隔會將資料分組為 30 個一分鐘增量。預設值為 30 個步驟。 + **最小間隔** – 步驟計數間隔低於的最低閾值不會分割時間。若要繼續 30 分鐘的範例，如果最小間隔設定為 `2m`，Grafana 會將資料分組為 15 個 2 分鐘增量。 1. 在**預覽值**中，Grafana 會顯示目前變數值的清單。檢閱它們以確保它們符合您的期望。 1. 選擇**新增**，將變數新增至儀表板。 ### 間隔變數範例 在 Graphite 函數`myinterval`中使用範本變數的範例： ``` summarize($myinterval, sum, false) ``` 更複雜的 Graphite 範例： ``` groupByNode(summarize(movingAverage(apps.$app.$server.counters.requests.count, 5), '$interval', 'sum', false), 2, 'sum') ``` ## 新增臨機操作篩選條件 您可以使用一次性或*臨機*操作篩選條件來新增金鑰/值篩選條件，這些篩選條件會自動新增至使用指定資料來源的所有指標查詢。與其他變數不同，您不會在查詢中使用一次性篩選條件。反之，您可以使用它們來撰寫現有查詢的篩選條件。 **注意** **注意：**一次性或臨機操作，篩選條件變數僅適用於 InfluxDB、Prometheus 和 OpenSearch 資料來源。 ### 輸入一般選項 **輸入臨機操作篩選條件的一般選項** 1. 導覽至您要為其建立變數的儀表板，然後選擇頁面頂端的**儀表板設定** （齒輪） 圖示。 1. 在**變數**索引標籤上，選擇**新增**。 1. 輸入變數**的名稱**。 1. 在**類型**清單中，選取**臨機操作篩選條件**。 1. （選用） 針對**標籤**，輸入變數下拉式清單的顯示名稱。如果您未輸入顯示名稱，下拉式清單標籤將是變數名稱。 1. 選擇**隱藏**選項： + **無選擇 （空白）** – 變數下拉式清單會顯示變數**名稱**或**標籤**值。這是預設值。 + **標籤** – 變數下拉式清單只會顯示選取的變數值和向下箭頭。 + **變數** – 儀表板上不會顯示變數下拉式清單。 ### 輸入選項 **輸入臨機操作篩選條件的選項** 1. 在**資料來源**清單中，選取目標資料來源。如需資料來源的詳細資訊，請參閱 [連線至資料來源](AMG-data-sources.md)。 1. 選擇**新增**，將變數新增至儀表板。 ### 建立臨機操作篩選條件 臨機操作篩選條件是最複雜且靈活的變數選項之一。此變數會啟用全儀表板臨機操作查詢的建構，而不是變數選項的一般清單。您以此方式套用的篩選條件會套用至儀表板上的所有面板。 ## 鏈結變數 *鏈結變數*也稱為*連結變數*或*巢狀變數*，是在其變數查詢中具有一或多個其他變數的查詢變數。本節說明鏈結變數的運作方式，並提供使用鏈結變數的範例儀表板連結。 每個資料來源的鏈結變數查詢都不同，但所有 的 內部部署都相同。您可以在支援它們的任何資料來源中使用鏈結變數查詢。 您可以建置複雜的連結、範本儀表板、5 或 10 層深度。在技術上，您可以達到的深度或複雜程度沒有限制，但您擁有的連結越多，查詢負載越大。 ### 最佳實務和秘訣 下列實務可讓您更輕鬆地使用儀表板和變數。 #### 建立新的鏈結變數 + 鏈結變數會建立父子相依性。您可以將它們設想成梯子或樹。 + 建立新鏈結變數的最快速方法是複製要以新變數為基礎的變數。在變數清單中，選擇變數項目右側的**複製**變數圖示來建立複本。然後，您可以將 新增至父變數的查詢。 + 您以此方式建立的新鏈結變數會出現在清單底部。若要為清單提供邏輯順序，請將變數拖曳到清單中的不同位置。 #### 變數順序 若要變更儀表板變數清單中變數的順序，請選擇每個項目右側的向上和向下箭頭。Grafana 工作區會根據此清單列出由左至右的變數下拉式清單，並在最左方的清單上方顯示變數。 + 在子變數前面列出沒有相依性的變數。 + 每個變數都應遵循其相依的變數。 + UI 不會指出哪些變數具有相依性關係。以邏輯順序列出變數，讓最終使用者 （和您自己） 更清楚。 #### 複雜性考量 變數中的相依性層越多，變更變數後更新儀表板所需的時間就越長。 例如，如果您有一系列四個連結變數 （國家/地區、區域、伺服器、指標），而且您變更根變數值 （國家/地區），則 Grafana 工作區必須對所有相依變數執行查詢，才能更新儀表板中的視覺效果。 ## 全域變數 Grafana 具有全域內建變數，可用於查詢編輯器中的表達式。本主題依字母順序列出並加以定義。這些變數在查詢、儀表板連結、面板連結和資料連結中很有用。 ### $\_\_儀表板 此變數是目前儀表板的名稱。 ### $\_\_from 和 $\_\_to Grafana 有兩個內建的時間範圍變數： `$__from`和 `$__to`。根據預設，它們目前一律會插入為 epoch 毫秒，但您可以控制日期格式。 | 語法 | 範例結果 | Description | | --- | --- | --- | | ${\_\_from} | 1594671549254 | Unix 毫秒 epoch | | ${\_\_from:date} | 2020-07-13T20：19：09.254Z | 無 args，預設為 ISO 8601/RFC 3339 | | ${\_\_from:date:iso} | 2020-07-13T20：19：09.254Z | ISO 8601/RFC 3339 | | ${\_\_from:date:seconds} | 1594671549 | Unix 秒 epoch | | ${\_\_from:date:YYYY-MM} | 2020-07 | 任何自訂資料格式。如需詳細資訊，請參閱[顯示](https://momentjs.com/docs/#/displaying/)。 | 上述語法`${__to}`也適用於 。 您也可以在 URLs中使用此變數。例如，若要將最終使用者傳送到顯示從六個小時前到現在時間範圍的儀表板，請使用下列 URL：https：//https://play.grafana.org/d/000000012/grafana-play-home？viewPanel=2&orgId=1？from=now-6h&to=now ### $\_\_interval 您可以使用 `$__interval`變數做為依時間分組的參數 （適用於 InfluxDB、Myself、Postgres、MSSQL)、日期長條圖間隔 （適用於 OpenSearch)，或做為*摘要*函數參數 （適用於 Graphite)。 Grafana 工作區會自動計算間隔，可用於依查詢中的時間分組。當有比圖形上顯示的更多資料點時，可以透過按較大的間隔分組來提高查詢的效率。例如，查看 3 個月的資料時，分組 1 天比 10 天更有效率。圖形看起來會相同，而查詢會更快。的計算方式`$__interval`是使用時間範圍和圖形的寬度 （像素數）。 近似值計算： `(from - to) / resolution` 例如，當時間範圍為 1 小時且圖形為全螢幕時，間隔可能會計算為 `2m`；點會以 2 分鐘的間隔分組。如果時間範圍為 6 個月且圖形為全螢幕，則間隔可能是 `1d`(1 天）；點會依天分組。 在 InfluxDB 資料來源中，舊版變數`$interval`是相同的變數。請改用 `$__interval`。 InfluxDB 和 OpenSearch 資料來源具有用於硬式編碼間隔或使用`>`語法 -> 設定`$__interval`變數下限`Group by time interval`的欄位`>10m`。 ### $\_\_interval\_ms 此變數是以毫秒為單位的`$__interval`變數，而不是時間間隔格式的字串。例如，如果 `$__interval`是 `20m`，則 `$__interval_ms`是 `1200000`。 ### $\_\_name 此變數僅適用於 Singlestat 面板，也可用於**選項**索引標籤的字首或尾碼欄位。變數將取代為序列名稱或別名。 ### $\_\_org 此變數是目前組織的 ID。變數`${__org.name}`是目前組織的名稱。 ### $\_\_user 變數`${__user.id}`是目前使用者的 ID。變數`${__user.login}`是目前使用者的登入控制代碼。變數`${__user.email}`是目前使用者的電子郵件。 ### $\_\_range 此變數目前僅支援 Prometheus 資料來源。此變數代表目前儀表板的範圍。它由 計算`to - from`。它具有稱為 `$__range_ms`和 的毫秒和秒表示`$__range_s`法。 ### $timeFilter 或 $\_\_timeFilter `$timeFilter` 變數會傳回目前選取的時間範圍做為表達式。例如，時間範圍間隔`Last 7 days`表達式為 `time > now() - 7d`。 此變數用於多個地方，包括： + InfluxDB 資料來源的 WHERE 子句。在查詢編輯器模式下，Grafana 會自動將其新增至 InfluxDB 查詢。 ****您可以在**文字編輯器**模式中手動新增它：`WHERE $timeFilter`。 + Azure Monitor 資料來源中的日誌分析查詢。 + MySQL、Postgres 和 MSSQL 中的 SQL 查詢。 + `$__timeFilter` 變數用於 MySQL 資料來源。