儲存及共用查詢

您可以在 Observability Analytics 中儲存及分享 SQL 查詢，以便重新執行常用的追蹤調查，並與專案中的團隊成員協作。您可以將儲存的查詢設為私人用途，或與其他專案成員共用。如果您尚未在 Observability Analytics 中編寫查詢，請先參閱「查詢及分析追蹤記錄」。

事前準備

設定專案、IAM 角色，然後選取您打算使用的介面。

設定專案和角色

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Observability API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

1. 如要取得載入「可觀測性分析」頁面、在追蹤資料上撰寫、執行及儲存私人查詢所需的權限，請要求管理員授予您下列 IAM 角色：

   • 在要查詢的觀測檢視畫面中，選取「觀測檢視畫面存取者」 (roles/observability.viewAccessor)。這個角色支援 IAM 條件，可讓您將授權限制在特定檢視區塊。如果未在角色授予作業中附加條件，主體就能存取所有可觀測性檢視畫面。
   • 專案的「Observability Analytics User」(觀測能力分析使用者) (roles/observability.analyticsUser) 權限。這個角色具備儲存及執行私人查詢，以及執行共用查詢所需的權限。

   如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

   您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

   注意：如要建立及管理共用查詢，上述 IAM 角色並不夠用。如要建立及管理共用查詢，您的 IAM 角色必須包含 logging.queries.{share, updateShared, deleteShared} 權限。

選取要使用的介面

控制台

使用 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. 在「Query」(查詢) 窗格中填入查詢，然後按一下「Run query」(執行查詢)。

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

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 的參考頁面。

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

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

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

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

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

後續步驟

• 繪製 SQL 查詢結果圖表
• SQL 查詢示例
• 在 BigQuery 中查詢連結的 BigQuery 資料集