以切面形式将检查结果发送到 Dataplex Universal Catalog

本文档介绍了如何检查 BigQuery 表中是否存在敏感数据，并将检查结果发送到 Dataplex Universal Catalog。此操作会自动向与您的 BigQuery 表关联的 Dataplex Universal Catalog 条目添加一个方面。

本文档还提供了一些示例查询，您可以使用这些查询在组织和项目中查找具有特定方面值的数据。

如果您想通过 Sensitive Data Protection 检查作业中的敏感数据分类来丰富 Dataplex Universal Catalog 中的元数据，此功能会非常有用。

生成的方面包括以下详细信息：

• 检查作业的名称
• 在表格中检测到的信息类型 (infoTypes)

Dataplex Universal Catalog 简介

Dataplex Universal Catalog 提供 Google Cloud 资源的统一清单。

借助 Dataplex Universal Catalog，您可以使用切面向数据添加业务和技术元数据，以捕获有关资源的上下文和知识。然后，您可以在组织内搜索和发现数据，并对数据资产启用数据治理。如需了解详情，请参阅切面。

工作原理

如需根据检查作业结果自动创建 Dataplex Universal Catalog 方面，请按照以下高级别工作流程操作：

1. 创建或修改用于检查 BigQuery 表的检查作业。 如需查看相关说明，请参阅检查 BigQuery 表。

2. 在添加操作步骤中，启用发布到 Dataplex Universal Catalog。

Sensitive Data Protection 会添加或更新与 BigQuery 表关联的 Dataplex Universal Catalog 条目的 Sensitive Data Protection job result 方面。然后，您可以在 Dataplex Universal Catalog 中搜索组织或项目内具有特定切面值的所有数据。如需查看示例查询，请参阅本文档中的示例搜索查询。

生成的 Dataplex Universal Catalog 方面存储在与 BigQuery 表相同的项目和区域中。

方面字段

Sensitive Data Protection job result 方面具有以下字段：

作业名称

检查作业的完整资源名称，例如 projects/example-project/locations/us/dlpJobs/i-8992079400000000000。

InfoType 数量

检查作业搜索的 infoType 名称（如检查配置中所指定）以及每个 infoType 的发现结果数量。 如果某个 infoType 没有发现结果，则其数量为 0。

结束时间

检查作业结束的日期和时间。

是否为全面扫描

检查作业是否扫描了表中的所有行。如果检查作业中启用了抽样，则此字段的值为 False。

有发现结果

检查作业是否检测到其扫描的任何 infoType。

启用 Dataplex API

您必须在包含要添加方面的数据的每个项目中启用 Dataplex API。本部分介绍了如何在单个项目中或在组织或文件夹中的所有项目中启用 Dataplex API。

在单个项目中启用 Dataplex API

1. 选择要在其中启用 Dataplex API 的项目。

   转到“项目选择器”

2. Enable the Dataplex API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

在组织或文件夹中的所有项目中启用 Dataplex API

此部分提供了一个脚本，用于搜索组织或文件夹中的所有项目，并在每个项目中启用 Dataplex API。

如需获得在组织或文件夹中的所有项目中启用 Dataplex API 所需的权限，请让管理员向您授予以下 IAM 角色：

• 组织或文件夹的 Cloud Asset Viewer (roles/cloudasset.viewer)
• 针对您要在其中启用 Dataplex API 的每个项目的 DLP User (roles/dlp.user)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色包含在组织或文件夹中的所有项目中启用 Dataplex API 所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需在组织或文件夹中的所有项目中启用 Dataplex API，您必须拥有以下权限：

• 如需搜索组织或文件夹中的所有项目，请执行以下操作： 点击组织或文件夹中的 cloudasset.assets.searchAllResources
• 如需启用 Dataplex API，请在您要启用 Dataplex API 的每个项目中执行以下操作： serviceusage.services.use

您也可以使用自定义角色或其他预定义角色来获取这些权限。

如需在组织或文件夹中的所有项目中启用 Dataplex API，请按以下步骤操作：

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

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 角色：

• Dataplex Catalog Viewer (roles/dataplex.catalogViewer)
• BigQuery Data Viewer (roles/bigquery.dataViewer)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色包含搜索与 BigQuery 表相关联的方面所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需搜索与 BigQuery 表相关联的方面，您需要具备以下权限：

• 查看 Dataplex Universal Catalog 条目：
  • dataplex.entries.list
  • dataplex.entries.get
• 查看 BigQuery 数据集和表：
  • bigquery.datasets.get
  • bigquery.tables.get

您也可以使用自定义角色或其他预定义角色来获取这些权限。

如需详细了解使用 Dataplex Universal Catalog 所需的权限，请参阅 Dataplex Universal Catalog IAM 权限。

配置并运行 Sensitive Data Protection 检查作业

您可以使用 Google Cloud 控制台或 DLP API 配置并运行 Sensitive Data Protection 检查作业。

控制台

1. 在 Google Cloud 控制台中，前往创建作业或作业触发器页面。

   转到“创建作业或作业触发器”

2. 选择您的项目。
3. 输入所需的检查作业详细信息以及要检查的 BigQuery 表的详细信息。如需查看相关说明，请参阅检查 BigQuery 表。如需查看 Sensitive Data Protection 可以检查的信息类型的完整列表，请参阅 InfoType 检测器参考文档。
4. 对于添加操作，请启用发布到 Dataplex Universal Catalog。
5. 点击创建。作业会立即运行。

REST

以下示例发送 projects.locations.dlpJobs.create 请求，以检查 BigQuery 表并将结果发送到 Dataplex Universal 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": {}
                  }
                ]
              }
            }

如需发送您的请求，请展开以下选项之一：

curl（Linux、macOS 或 Cloud Shell）

将请求正文保存在名为 inspect-request.json 的文件中，然后执行以下命令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @inspect-request.json \
     "https://dlp.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/dlpJobs"

PowerShell (Windows)

将请求正文保存在名为 inspect-request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile inspect-request.json `
    -Uri "https://dlp.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/dlpJobs" | Select-Object -Expand Content

您应该收到类似以下内容的 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 获取检查作业结果，请参阅获取作业。

搜索查询示例

本部分提供了一些示例搜索查询，您可以在 Dataplex Universal Catalog 中使用这些查询来查找组织或项目中具有特定切面值的数据。

您只能找到自己有权访问的数据。数据访问权限通过 IAM 权限进行控制。如需了解详情，请参阅本文档中的查看切面的角色和权限。

您可以在 Dataplex Universal Catalog 搜索页面上的搜索字段中输入这些示例查询。

转到搜索

如需了解如何构建查询，请参阅 Dataplex Universal Catalog 的搜索语法。

查找具有敏感数据保护作业结果方面特征的所有表的条目

aspect:sensitive-data-protection-job-result

查找检查过的表中存在发现结果的条目

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

查找检查过的表中没有发现结果的条目

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

查找已完全检查的表的条目

以下查询返回了敏感数据保护逐行检查的表的条目。

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

查找未完全检查的表的条目

以下查询会返回 Sensitive Data Protection 通过抽样检查的表的条目。

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