儲存及共用 SQL 查詢

本文說明如何儲存及共用在可觀測性分析中建立的查詢。

本文假設您已熟悉 Observability Analytics，以及如何使用 Observability Analytics 頁面查詢記錄資料。如果您不熟悉這些主題，請參閱「查詢及分析記錄檔」。

如要瞭解如何將查詢結果繪製成圖表，以及如何將這些圖表儲存到自訂資訊主頁，請參閱「將 SQL 查詢結果繪製成圖表」。

已儲存查詢與數據分析檢視畫面的差異

已儲存的查詢是指您使用 Observability Analytics 頁面執行，然後儲存為查詢的查詢。儲存後，您就能在方便的時間重新執行這項查詢。儲存查詢時，您可以選擇設為私人查詢，也可以設為公開查詢，讓有權使用可觀測性分析的其他使用者查看。您無法撰寫 SQL 查詢，其中 FROM 子句指定已儲存的查詢。

資料分析檢視畫面包含查詢，您可以隨時重新執行。您可以針對記錄檢視表編寫 SQL 查詢，然後將結果儲存為檢視表，藉此建立 Analytics 檢視表。與已儲存的查詢不同，您無法將數據分析檢視畫面設為私人檢視畫面。 您可以查詢 Analytics 檢視畫面。這項功能可將 LogEntry 格式的記錄資料轉換為更適合您的其他格式。然後，您會查詢分析檢視畫面，而不是針對記錄檢視畫面撰寫查詢。

您可以儲存查詢記錄檢視區或數據分析檢視區的查詢。

事前準備

本節說明使用可觀測性分析前必須完成的步驟。

設定記錄檔 bucket

確認記錄檔 bucket 已升級為使用 Observability Analytics：

1. 在 Google Cloud 控制台中，前往「Logs Storage」(記錄檔儲存空間) 頁面：

   前往「Logs Storage」(記錄檔儲存空間)

   如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

2. 針對每個含有要查詢記錄檔檢視的記錄檔 bucket，請確認「可使用 Observability Analytics」欄顯示「開啟」。如果顯示「升級」，請按一下「升級」並完成對話方塊。

設定 IAM 角色和權限

本節說明使用可觀測性分析所需的 IAM 角色或權限：

• 如要取得使用可觀測性分析和查詢記錄檔檢視畫面所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

  • 如要查詢 _Required 和 _Default 記錄檔值區： 記錄檢視器 (roles/logging.viewer)
  • 如要查詢專案中的所有記錄檢視區塊： 記錄檢視區塊存取者 (roles/logging.viewAccessor)

  如要將主體限制為特定記錄檢視畫面，請在專案層級授予記錄檢視畫面存取者角色時新增 IAM 條件，或在記錄檢視畫面的政策檔案中新增 IAM 繫結。詳情請參閱「控管記錄檢視畫面的存取權」。

  您必須具備這些權限，才能在「記錄探索器」頁面查看記錄項目。如要瞭解查詢使用者定義 bucket 中的檢視區塊，或查詢 _Default 記錄檔 bucket 的 _AllLogs 檢視區塊時，需要哪些額外角色，請參閱「Cloud Logging 角色」。

• 如要取得查詢 Analytics 檢視畫面所需的權限，請要求管理員授予您專案的「可觀測性 Analytics 使用者 」(roles/observability.analyticsUser) IAM 角色。

選取要使用的介面

控制台

使用 Google Cloud 控制台存取 Google Cloud 服務和 API 時，無須設定驗證。

gcloud

在 Google Cloud 控制台中啟用 Cloud Shell。

啟用 Cloud Shell

控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。 Google Cloud Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已針對您目前的專案設定好相關值。工作階段可能要幾秒鐘的時間才能初始化。

REST

如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」。

儲存查詢

系統會自動儲存您執行的所有查詢 30 天，選取「Observability Analytics」頁面上的「最近」分頁標籤即可存取。您可以搜尋、查看、執行及分享「近期」分頁中列出的查詢。

如要重複使用查詢、新增自訂說明或與隊友共用查詢，請儲存查詢。您可以依名稱、說明和顯示標籤搜尋及排序已儲存的查詢。您也可以編輯及刪除這些查詢。儲存的查詢會保留到您刪除為止。

每個專案最多可儲存 10,000 個查詢。 Google Cloud

注意： 使用 Google Cloud 控制台儲存的查詢會儲存在 global 位置。如要指定查詢的儲存位置，請使用 Google Cloud CLI 或 Cloud Logging API。

控制台

如要儲存查詢，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，前往 「Observability Analytics」(觀測能力分析) 頁面：

   前往「Observability Analytics」(觀測能力分析) 頁面

   如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

2. 在「Query」(查詢) 窗格中填入查詢。

   您可以輸入新查詢、從「近期」分頁選取查詢，或從「已儲存」分頁選取查詢，藉此填入「查詢」窗格。

   查詢可包含任何有效的檢視畫面、多個檢視畫面和數據分析檢視畫面。

   如果「Query」(查詢) 窗格中的查詢有效，系統會啟用「save」(儲存)「Save」(儲存) 按鈕。

3. 按一下「儲存」，選取「儲存查詢」，然後填寫「名稱」和「說明」欄位。您為這些欄位設定的值會顯示在「已儲存」分頁中。

4. 選用：如要讓有權存取專案 Google Cloud 「可觀測性分析」頁面的使用者查看及執行已儲存的查詢，請啟用「與專案共用」切換鈕。

   根據預設，這個切換按鈕會停用，且只有你能查看。

5. 按一下 [Save query] (儲存查詢)。

6. 選用：如要查看、排序及執行您可見的已儲存查詢，請選取「已儲存」分頁標籤。

   您可以依據名稱、說明和顯示狀態標籤，排序及篩選已儲存的查詢。你也可以依查詢內容篩選。

您可以使用「已儲存」分頁中的選項，編輯及刪除您建立的查詢：

• 如要編輯查詢，請按一下「更多選項」，然後選取「編輯」。 您可以修改「名稱」和「說明」欄位的值，但無法修改查詢本身。

• 如要刪除已儲存的查詢，請按一下「更多選項」，然後選取「刪除」。

gcloud

如要建立及儲存查詢，請按照下列步驟操作：

1. 使用下方的任何指令資料之前，請先替換以下項目：

   • DISPLAY_NAME：已儲存的查詢的顯示名稱。
   • LOCATION：儲存查詢的位置。
   • VISIBILITY：設為 private 或 shared。
   • SQL_QUERY：SQL 查詢。如果路徑或路徑中的欄位以單一反引號 (`) 包住，則必須逸出這些反引號：

         "SELECT * FROM \`PROJECT_ID.LOCATION.my-log-bucket._AllLogs\`"
         

     或

         "SELECT * FROM \`PROJECT_ID.LOCATION._Trace.Spans._AllSpans\`"
         

     如果路徑元素包含半形句號 (.) 字元，就必須使用反引號 (`)。

   • ID：已儲存的查詢 ID。這個 ID 是必要輸入項，用於描述、更新或刪除已儲存的查詢的指令。如果您在建立已儲存的查詢時未提供 ID，系統就會產生數字 ID。
   • DESCRIPTION：查詢的文字說明。選填。
   • PROJECT_ID：專案的 ID。

   執行 gcloud logging saved-queries create 指令：

   Linux、macOS 或 Cloud Shell

   gcloud logging saved-queries create --display-name=DISPLAY_NAME \
    --location=LOCATION --visibility=VISIBILITY --sql-query-text=SQL_QUERY \
    --id=ID --description=DESCRIPTION --project=PROJECT_ID

   Windows (PowerShell)

   gcloud logging saved-queries create --display-name=DISPLAY_NAME `
    --location=LOCATION --visibility=VISIBILITY --sql-query-text=SQL_QUERY `
    --id=ID --description=DESCRIPTION --project=PROJECT_ID

   Windows (cmd.exe)

   gcloud logging saved-queries create --display-name=DISPLAY_NAME ^
    --location=LOCATION --visibility=VISIBILITY --sql-query-text=SQL_QUERY ^
    --id=ID --description=DESCRIPTION --project=PROJECT_ID

   以下是指令中提供的 ID 為 my-saved-query 時的回應範例：

   Created saved query [projects/PROJECT_ID/locations/LOCATION/savedQueries/my-saved-query].
   

   create 指令的回應會列出查詢的全名，包括查詢的 ID。查詢 ID (在本例中為 my-saved-query) 是 Google Cloud CLI 指令的必要輸入內容，可用於說明、刪除或更新已儲存的查詢。

2. 如要檢查已儲存的查詢，請執行下列指令：

    gcloud logging saved-queries list --location=- --project=PROJECT_ID
   

   在上述運算式中，位置的值是連字號 (-)，可做為萬用字元。你也可以提供特定地點。

您可以使用 Google Cloud CLI 指令刪除、列出、說明及更新已儲存的查詢。詳情請參閱 gcloud logging saved-queries 總覽。

REST

您可以使用 Cloud Logging API 儲存查詢。如要儲存查詢，請使用 savedQueries.create 方法。

如要執行這個方法，請按照下列步驟操作：

1. 選取 savedQueries.create。
2. 在參考頁面上，使用 APIs Explorer 發出指令。您必須指定 opsAnalyticsQuery 欄位。

下列範例說明範例要求主體，其中包含 SavedQuery 的例項：

{
   "parent": "projects/my-project/locations/global"
   "saved_query":
   {
      "ops_analytics_query":
      {
         "sql_query_text" :
            "SELECT
            timestamp, log_name, severity, json_payload, resource, labels
            FROM
            `VIEW`
            WHERE
            timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
            ORDER BY timestamp ASC
            LIMIT 100"
      }
   "visibility": "PRIVATE"
   }
}

共用查詢

您可以與所有有權存取Google Cloud 專案的使用者分享已儲存的查詢。不過，主體的 IAM 角色會決定查詢是否可以執行，以及查詢傳回的資料。

控制台

排解問題或發現異常結果時，您可能想與隊友分享查詢和結果。在「可觀測性分析」頁面查看查詢結果時，您可以複製網址，開啟該網址即可顯示您執行的查詢和結果。

如要與隊友共用查詢和結果，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，前往 「Observability Analytics」(觀測能力分析) 頁面：

   前往「Observability Analytics」(觀測能力分析) 頁面

   如果您是使用搜尋列尋找這個頁面，請選取子標題為「Logging」的結果。

2. 在「查詢」窗格中填入查詢，然後點選「執行查詢」。

   您可以輸入新查詢、從「近期」分頁選取查詢，或從「已儲存」分頁選取查詢，藉此填入「查詢」窗格。

3. 按一下「分享連結」圖示 。

4. 將連結傳送給隊友。

   當隊友開啟連結時，系統會開啟「可觀測性分析」頁面並顯示查詢，但不會執行查詢。隊友必須手動執行查詢。

   如果查詢在 BigQuery 引擎上執行，且查詢的資源不在同一個擁有權界線內，可觀測性分析頁面就會顯示警告對話方塊。擁有權界線取決於多項因素，其中一項是查詢使用的資源階層。

   如要順利開啟網址，您隊友在 Google Cloud 專案中的 IAM 角色必須包含查看「可觀測性分析」頁面所需的權限。

gcloud

如要建立可供他人執行的已儲存的查詢，請將 visibility 欄位的值設為 shared：

--visibility=shared

如要變更現有已儲存查詢的顯示設定，請使用 update 指令。如要進一步瞭解可用指令，請參閱 gcloud logging saved-queries 總覽。

REST

您可以使用 Logging API 的 savedQueries.create 方法建立共用查詢，並在 visibility 欄位中指定 SHARED 值。詳情請參閱 savedQueries.create 的參考頁面。

查看及執行近期或已儲存的查詢

如要查看或重新執行查詢，請選取「可觀測性分析」頁面上的「最近」分頁標籤，然後找出查詢：

• 點選「執行」執行查詢。
• 如要查看查詢，請使用「 更多選項」選單中的選項。

如要查看、編輯或執行已儲存的查詢，請選取「可觀測性分析」頁面上的「已儲存」分頁，然後找出查詢：

• 點選「執行」執行查詢。
• 如要編輯、查看或刪除查詢，請使用「更多選項」選單中的選項。

後續步驟

• 建立及查詢數據分析檢視區塊
• SQL 查詢示例
• 繪製 SQL 查詢結果圖表
• 在 BigQuery 中查詢連結的 BigQuery 資料集