將檢查結果以切面形式傳送至 Knowledge Catalog

本文說明如何檢查 BigQuery 資料表是否含有機密資料，並將檢查結果傳送至 Knowledge Catalog。這項動作會自動將切面新增至與 BigQuery 資料表相關聯的 Knowledge Catalog 項目。

這份文件也提供範例查詢，可用於在貴機構和專案中，找出具有特定層面值的資料。

如果您想透過 Sensitive Data Protection 檢查工作，將敏感資料分類資訊新增至 Knowledge Catalog 的中繼資料，這項功能就非常實用。

產生的層面包括下列詳細資料：

  • 檢查工作名稱
  • 系統在資料表中偵測到的資訊類型 (infoTypes)

關於 Knowledge Catalog

Knowledge Catalog 提供統一的 Google Cloud 資源目錄。

您可以使用 Knowledge Catalog 的切面，在資料中新增業務和技術中繼資料，擷取資源的脈絡和相關知識。然後，您就可以在整個機構中搜尋及探索資料，並對資料資產啟用資料治理功能。詳情請參閱「層面」。

運作方式

如要根據檢查作業結果自動建立 Knowledge Catalog 構面，請按照下列高階工作流程操作：

  1. 建立或編輯檢查工作，檢查 BigQuery 資料表。 如需操作說明，請參閱「檢查 BigQuery 資料表」。

  2. 在「新增動作」步驟中，啟用「發布至 Dataplex Universal Catalog」。

Sensitive Data Protection 會新增或更新與 BigQuery 資料表相關聯的 Knowledge Catalog 項目的 Sensitive Data Protection job result 切面。然後，您可以在 Knowledge Catalog 中搜尋機構或專案的所有資料，並指定特定層面值。如需查詢範例，請參閱本文中的「搜尋查詢範例」。

產生的 Knowledge Catalog 構面會儲存在與 BigQuery 資料表相同的專案和區域。

坡向欄位

Sensitive Data Protection job result 方面具有下列欄位：

工作名稱
檢查工作的完整資源名稱，例如： projects/example-project/locations/us/dlpJobs/i-8992079400000000000。
InfoType 數量
檢查工作搜尋的 InfoType 名稱 (如檢查設定中所指定)，以及每種 InfoType 的發現項目數量。如果 infoType 沒有發現項目，計數會是 0。
結束時間
檢查工作的結束日期和時間。
Is Full Scan
檢查工作是否掃描資料表中的所有資料列。舉例來說，如果檢查工作已啟用取樣功能，這個欄位的值就會是 False。
有發現項目
檢查工作是否偵測到任何掃描的 infoType。

啟用 Dataplex API

您必須在每個包含要新增層面資料的專案中啟用 Dataplex API。本節說明如何在單一專案中啟用 Dataplex API，或在機構或資料夾中的所有專案中啟用。

在單一專案中啟用 Dataplex API

  1. 選取要啟用 Dataplex API 的專案。

    前往專案選取器

  2. 啟用 Dataplex API。

    啟用 API 時所需的角色

    如要啟用 API，您必須具備 serviceusage.services.enable 權限。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「服務使用情形管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

    啟用 API

在機構或資料夾的所有專案中啟用 Dataplex API

本節提供一個指令碼，可搜尋機構或資料夾中的所有專案，並在每個專案中啟用 Dataplex API。

如要在機構或資料夾的所有專案中啟用 Dataplex API，請要求管理員授予您下列 IAM 角色：

  • 機構或資料夾的「Cloud Asset 檢視者」 (roles/cloudasset.viewer)
  • DLP 使用者 (roles/dlp.user) 在您要啟用 Dataplex API 的每個專案中

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

這些預先定義的角色具備在組織或資料夾的所有專案中啟用 Dataplex API 的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要在機構或資料夾的所有專案中啟用 Dataplex API，您必須具備下列權限：

  • 如要搜尋機構或資料夾中的所有專案： cloudasset.assets.searchAllResources 在機構或資料夾上
  • 如要啟用 Dataplex API，請在要啟用 Dataplex API 的每個專案中執行下列步驟： serviceusage.services.use

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

如要在機構或資料夾中的所有專案啟用 Dataplex API，請按照下列步驟操作：

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

    啟用 Cloud Shell

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

  2. 執行下列指令碼：

    #!/bin/bash

RESOURCE_ID="RESOURCE_ID"

gcloud asset search-all-resources \
    --scope="RESOURCE_TYPE/$RESOURCE_ID" \
    --asset-types="cloudresourcemanager.googleapis.com/Project" \
    --format="value(name)" |
    while read project_name; do
      project_id=$(echo "$project_name" | sed 's|.*/||')
      gcloud services enable "dataplex.googleapis.com" --project="$project_id"
    done

    更改下列內容：

    • RESOURCE_ID：包含專案的資源所屬機構或資料夾編號
    • RESOURCE_TYPE：包含專案的資源類型，即 organizations 或 folders

查看各個層面的角色和權限

如要取得搜尋與 BigQuery 資料表相關聯的構面所需的權限，請要求管理員授予您資料表的下列 IAM 角色：

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

這些預先定義的角色具備搜尋與 BigQuery 資料表相關聯的層面所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要搜尋與 BigQuery 資料表相關聯的構面，您必須具備下列權限：

  • 查看 Knowledge Catalog 項目：
    • dataplex.entries.list
    • dataplex.entries.get
  • 查看 BigQuery 資料集和資料表：
    • bigquery.datasets.get
    • bigquery.tables.get

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

如要進一步瞭解使用 Knowledge Catalog 時所需的權限，請參閱「Knowledge Catalog IAM 權限」。

設定及執行 Sensitive Data Protection 檢查工作

您可以使用 Google Cloud 控制台或 DLP API，設定及執行 Sensitive Data Protection 檢查工作。

控制台

  1. 前往 Google Cloud 控制台的「Create job or job trigger」(建立工作或工作觸發條件) 頁面。

    前往「建立工作或工作觸發條件」

  2. 選取專案。
  3. 輸入必要的檢查工作詳細資料，以及要檢查的 BigQuery 資料表詳細資料。如需操作說明，請參閱「檢查 BigQuery 資料表」。如需 Sensitive Data Protection 可檢查的資訊類型完整清單，請參閱 InfoType 偵測工具參考資料。
  4. 在「新增動作」中，啟用「發布至 Dataplex Universal Catalog」。
  5. 點選「建立」。工作會立即執行。

REST

下列範例會傳送 projects.locations.dlpJobs.create 要求，檢查 BigQuery 資料表並將結果傳送至 Knowledge Catalog。

使用任何要求資料之前，請先修改下列項目的值：

  • PROJECT_ID：您的 Google Cloud 專案 ID。專案 ID 為英數字串，
  • LOCATION：要處理要求的區域或多區域，例如 europe-west1 或 us。如要查看適用位置，請參閱「Sensitive Data Protection 位置」。
  • BIGQUERY_DATASET_NAME：BigQuery 資料集的名稱，其中包含要檢查的資料表
  • BIGQUERY_TABLE_NAME：要檢查的 BigQuery 資料表名稱

HTTP 方法和網址：

POST https://dlp.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/dlpJobs

JSON 要求主體：

{
              "inspectJob":
              {
                "storageConfig":
                {
                  "bigQueryOptions":
                  {
                    "tableReference":
                    {
                      "projectId": "PROJECT_ID",
                      "datasetId": "BIGQUERY_DATASET_NAME",
                      "tableId": "BIGQUERY_TABLE_NAME"
                    }
                  }
                },
                "inspectConfig":
                {
                  "infoTypes":
                  [
                    {
                      "name": "EMAIL_ADDRESS"
                    },
                    {
                      "name": "PERSON_NAME"
                    },
                    {
                      "name": "US_SOCIAL_SECURITY_NUMBER"
                    },
                    {
                      "name": "PHONE_NUMBER"
                    }
                  ],
                  "includeQuote": true,
                  "minLikelihood": "UNLIKELY",
                  "limits":
                  {
                    "maxFindingsPerRequest": 100
                  }
                },
                "actions":
                [
                  {
                    "publishFindingsToDataplexCatalog": {}
                  }
                ]
              }
            }

請展開以下其中一個選項，以傳送要求：

您應該會收到如下的 JSON 回覆：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/dlpJobs/JOB_ID",
  "type": "INSPECT_JOB",
  "state": "PENDING",
  "inspectDetails": {
    "requestedOptions": {
      "snapshotInspectTemplate": {},
      "jobConfig": {
        "storageConfig": {
          "bigQueryOptions": {
            "tableReference": {
              "projectId": "PROJECT_ID",
              "datasetId": "BIGQUERY_DATASET_NAME",
              "tableId": "BIGQUERY_TABLE_NAME"
            }
          }
        },
        "inspectConfig": {
          "infoTypes": [
            {
              "name": "EMAIL_ADDRESS"
            },
            {
              "name": "PERSON_NAME"
            },
            {
              "name": "US_SOCIAL_SECURITY_NUMBER"
            },
            {
              "name": "PHONE_NUMBER"
            }
          ],
          "minLikelihood": "UNLIKELY",
          "limits": {
            "maxFindingsPerRequest": 100
          },
          "includeQuote": true
        },
        "actions": [
          {
            "publishFindingsToDataplexCatalog": {}
          }
        ]
      }
    },
    "result": {}
  },
  "createTime": "2025-09-09T00:29:55.951374Z",
  "lastModified": "2025-09-09T00:29:58.022967Z"
}

如要瞭解如何使用 DLP API 取得檢查工作結果，請參閱取得工作。

搜尋查詢範例

本節提供範例搜尋查詢，您可以在 Knowledge Catalog 中使用這些查詢，在貴機構或專案中尋找具有特定面向值的資料。

您只能找到自己有權存取的資料。資料存取權由 IAM 權限控管。詳情請參閱本文的「查看層面的角色和權限」。

您可以在 Knowledge Catalog 的「Search」(搜尋) 頁面，於「Search」(搜尋) 欄位中輸入這些範例查詢。

前往「Search」(搜尋) 頁面

如要瞭解如何設計查詢，請參閱「Knowledge Catalog 的搜尋語法」。

找出所有具有 Sensitive Data Protection 工作結果層面的資料表項目

aspect:sensitive-data-protection-job-result

找出有發現項目的檢查資料表項目

aspect:sensitive-data-protection-job-result.hasFindings=True

找出沒有發現項目的受檢資料表項目

aspect:sensitive-data-protection-job-result.hasFindings=False

找出已完整檢查的資料表項目

下列查詢會傳回 Sensitive Data Protection 逐列檢查的資料表項目。

aspect:sensitive-data-protection-job-result.isFullScan=True

找出未完全檢查的表格項目

下列查詢會傳回 Sensitive Data Protection 透過取樣檢查的資料表項目。

aspect:sensitive-data-protection-job-result.isFullScan=False

遷移至「發布至 Dataplex Universal Catalog」動作

如要遷移已設定為使用已淘汰「發布至 Data Catalog」動作的工作觸發條件，請按照下列步驟操作：

  1. 編輯設定為將檢查結果發布至 Data Catalog 的工作觸發條件。如要瞭解如何開啟及編輯工作觸發條件，請參閱「更新現有工作觸發條件」。
  2. 在「動作」部分，停用「發布至 Data Catalog」。
  3. 啟用「發布至 Dataplex Universal Catalog」。
  4. 按一下「儲存」。