创建存储的自定义字典检测器

如果您想要在您的内容中扫描一个包含多达数万个敏感字词或短语的列表,那么常规的自定义字典检测器就足够了。如果您要针对更多的字词或短语进行扫描,或者您的字词或短语列表经常更改,请考虑创建一个存储的自定义字典,该字典可用于扫描多达数千万个字词或短语

本主题介绍了如何创建和重建存储的自定义字典,同时还介绍了多种错误场景。

对存储的自定义字典的剖析

您可能熟悉如何创建常规字典自定义 infoType正则表达式自定义 infoType:配置自定义 infoType,然后使用它来设置检查或去标识化扫描。但存储的自定义字典不同于这些自定义 infoType,因为每个存储的自定义字典都由两部分组成:

  • 您创建和定义的短语列表。该列表以文本文件的形式存储在 Cloud Storage 中或以列的形式存储在 BigQuery 表中。
  • 生成的字典文件,由 Cloud DLP 根据您的短语列表生成。字典文件存储在 Cloud Storage 中,由源短语数据的副本和布隆过滤器组成,有助于进行搜索和匹配。 您无法直接修改这些文件。

新建存储的自定义字典

本部分介绍如何创建、修改和重建存储的自定义字典。

创建短语列表

创建存储的自定义字典的第一步是创建字词和短语列表。您有以下两种选择:

  • 将每个字词或短语各自位于一行的文本文件放在 Cloud Storage 存储分区中。
  • 将 BigQuery 表的一列指定为短语的容器。在列中为每个短语提供自己的行。只要所有字典字词和短语都位于一列中,您就可以使用现有 BigQuery 表。

请注意,您可能会组建出过大的 Cloud DLP 无法处理的术语列表。如果您看到错误消息,请参阅本主题后面的排查错误

创建字典

创建术语列表后,使用 Cloud DLP 创建字典:

控制台

  1. 在 Cloud Storage 存储分区中为字典创建一个新文件夹。 Cloud DLP 会在您指定的位置创建包含字典文件的文件夹。
  2. 在 Cloud Console 中,打开 Cloud DLP。

    转到 Cloud DLP 界面

  3. 创建菜单中,选择存储的 infoType

    选择了“创建”菜单 >“存储的 infoType”的 DLP 界面的屏幕截图。

    或者,点击以下按钮:

    创建新的 infoType

“创建 infoType”页面包含以下部分:

配置 infoType

您可以在配置 infoType 部分中对存储的自定义字典 infoType 进行命名和描述。

  • InfoType ID 字段中,输入自定义 infoType 的标识符。 在配置检查和去标识化作业时,您将通过该标识符引用 infoType。您可以在名称中使用字母、数字、连字符和下划线。
  • InfoType 显示名字段中,输入自定义 infoType 的名称。您可以在名称中使用空格和标点符号。
  • 说明字段中,输入有关自定义 infoType 所检测到内容的说明。

选择数据位置

您可以在选择数据位置部分指定从何处查找用于创建存储的自定义字典的字词和短语列表。

  • 如果要搜索的字词和短语列于 BigQuery 表中,请选择 BigQuery。请注意,您最多只能指定表中的一列。在指定字段中输入项目 ID、数据集 ID 和表 ID。在字段名称字段中,输入列标识符。
  • 如果要搜索的字词和短语列于 Cloud Storage 的文本文件中,请选择 Google Cloud Storage。在指定字段中输入该文件的路径。

在最后一部分中指定 Cloud DLP 的位置,用以保存压缩后存储的自定义字典。

输出存储分区或文件夹字段中,输入要将字典保存到的路径。

点击创建以创建存储的自定义字典。此时会显示 infoType 详情屏幕。

如果状态为“准备就绪”,则表示存储的自定义字典已生成,且新的自定义 infoType 可供使用。

协议

  1. 在 Cloud Storage 存储分区中为字典创建一个新文件夹。 Cloud DLP 会在您指定的位置创建包含字典文件的文件夹。
  2. 使用 Cloud DLP API 的 storedInfoTypes.create 方法创建字典。create 方法采用以下参数:
    • StoredInfoTypeConfig 对象,该对象包含存储的 infoType 的配置。具体内容如下:
      • description:字典的说明。
      • displayName:您要为字典指定的名称。
      • LargeCustomDictionaryConfig:包含存储的自定义字典的配置。具体内容如下:
        • BigQueryField:如果您的术语列表存储在 BigQuery 中,则指定此参数。 包括对存储列表的表的引用以及含有每个字典短语的字段。
        • CloudStorageFileSet:如果您的术语列表存储在 Cloud Storage 中,则指定此参数。 包含 Cloud Storage 中来源位置的网址,格式如下:"gs://[PATH_TO_GS]"。 支持使用通配符。
        • outputPath:Cloud Storage 存储分区中用于存储所创建字典的位置的路径。
    • storedInfoTypeId:存储的自定义 infoType 的标识符。在重建或删除存储的自定义 infoType 时,您将通过此值引用该 infoType;此外,您也可以在检查或去标识化作业中使用此值。如果将此字段留空,系统会为您生成一个标识符。

请考虑以下示例 JSON。如果将该 JSON 发送到 storedInfoTypes.create 方法,则会新建一个存储的自定义字典。在此示例中,我们已指示 Cloud DLP 根据一个存储在公共 BigQuery 数据库中的术语列表 (bigquery-public-data.samples.github_nested) 创建存储的自定义字典,该数据库包含提交中使用的所有 GitHub 用户名。生成字典的输出路径设置为名为 dlptesting 的 Cloud Storage 存储分区,且存储的自定义字典命名为 github-usernames

JSON 输入

POST https://dlp.googleapis.com/v2/projects/[PROJECT_ID]/storedInfoTypes?key={YOUR_API_KEY}

{
  "config":{
    "displayName":"GitHub usernames",
    "description":"Dictionary of github usernames used in commits",
    "largeCustomDictionary":{
      "outputPath":{
        "path":"gs://[PATH_TO_GS]"
      },
      "bigQueryField":{
        "table":{
          "datasetId":"samples",
          "projectId":"bigquery-public-data",
          "tableId":"github_nested"
        }
      }
    }
  },
  "storedInfoTypeId":"github-usernames"
}

重建字典

如果要在字典中添加或移除术语或短语,请首先更新源术语列表,然后指示 Cloud DLP 重建字典。

  1. 更新 Cloud Storage 或 BigQuery 中的现有源术语列表。根据需要添加、移除或更改术语或短语。
  2. 使用 Cloud Console 或 Cloud DLP 的 storedInfoTypes.patch 方法“重建”字典,以创建其新版本。执行此操作会创建字典的新版本,该版本将取代旧版字典。

如需重建存储的自定义字典,请执行以下操作:

控制台

  1. 更新并保存 Cloud Storage 或 BigQuery 中的术语列表。
  2. 在 Cloud Console 中,打开 Cloud DLP。
  3. 点击配置标签页,然后点击 InfoType
  4. 在 infoType 屏幕上,点击自定义标签页。存储的自定义 infoType 会显示在此处。

    转到自定义 infoType 列表

  5. 点击您要更新的存储的 infoType 所在的行。

  6. 在 infoType 详情屏幕上,点击重新构建数据

Cloud DLP 会使用您对源术语列表所做的更改重新构建存储的自定义字典。自定义 infoType 的状态为“准备就绪”后,您就可以使用它了。任何使用该自定义 infoType 的模板或作业触发器都将自动使用重新构建的自定义 infoType。

协议

如果您只是要在存储的自定义字典中添加新术语,或者删除或更改现有术语,则只需单独调用 storedInfoTypes.patch 方法即可重新构建字典。请务必将组织或项目的资源名称以及要重新构建的存储的自定义 infoType 的资源名称填充到 name 字段中。在创建存储的 infoType 时,您已在 storedInfoTypeId 参数中提供其名称。如果您忘记要重新构建的存储的自定义 infoType 的标识符,请调用 storedInfoTypes.list 方法来查看所有当前存储的 infoType 的列表。

以下模式表示 name 字段的有效条目:

  • organizations/[ORG_ID]/storedInfoTypes/[STORED_INFOTYPE_ID]
  • projects/[PROJECT_ID]/storedInfoTypes/[STORED_INFOTYPE_ID]

将存储的自定义字典重新构建为新版本后,系统会删除该存储的自定义字典的旧版本。在 Cloud DLP 正在更新存储的自定义字典时,字典处于“待处理”状态。如果字典的新版本处于“待处理”状态,那么字典的旧版本仍然存在。在重新构建字典期间运行的所有扫描都将使用字典的旧版本运行。

您可以将现有存储的自定义字典的源术语列表从存储在 BigQuery 表中更改为存储在 Cloud Storage 存储分区中,反之亦然。使用 storedInfoTypes.patch 方法,但要在 LargeCustomDictionaryConfig 中(您之前在其中使用过 BigQueryField 对象)包含一个 CloudStorageFileSet 对象,反之亦然。您还必须采用 FieldMask 格式指定 updateMask 参数,并将其设置为已重新创建的存储的自定义字典参数。例如,将以下 JSON 发送到 storedInfoTypes.patch 方法时,该 JSON 会在 updateMask 参数中声明 Cloud Storage 路径的网址已更新 (large_custom_dictionary.cloud_storage_file_set.url):

PATCH https://dlp.googleapis.com/v2/projects/[PROJECT_ID]/storedInfoTypes/github-usernames?key={YOUR_API_KEY}

{
  "config":{
    "largeCustomDictionary":{
      "cloudStorageFileSet":{
        "url":"gs://[BUCKET_NAME]/[PATH_TO_FILE]"
      }
    }
  },
  "updateMask":"large_custom_dictionary.cloud_storage_file_set.url"
}

使用存储的自定义字典检测器扫描内容

使用存储的自定义字典检测器扫描内容类似于使用任何其他自定义 infoType 检测器扫描内容。

控制台

您可以在创建新作业、作业触发器或模板时使用自定义字典检测器。在作业或模板创建工作流的配置检测部分中,您可以在自定义 infoType 子部分中指定存储的自定义字典 infoType:

  1. 点击添加自定义 infoType,然后点击存储的 infoType

    DLP 界面中“自定义 infoType”部分的创建作业触发器工作流的屏幕截图。

  2. 添加自定义 infoType 部分的 InfoType 字段中,输入 infoType 名称。您可以使用字母、数字和下划线。

  3. 点击存储的 infoType 名称字段,随即该字段下方会显示一个菜单,其中包含指向存储的自定义字典 infoType 的路径,如下所示:

    DLP 界面中“添加自定义 infoType”部分的创建作业触发器工作流的屏幕截图。

  4. 选择所需的存储的自定义字典,然后点击完成

您添加的自定义 infoType 如以下屏幕截图所示。请注意,如果需要,您可以添加其他自定义 infoType。

DLP 界面的创建作业触发器工作流的屏幕截图,其中添加了自定义 infoType。

您现在可以继续执行作业、作业触发器或模板创建过程。

协议

将以下 JSON 发送到 content.inspect 方法时,该 JSON 会使用指定的存储的自定义字典检测器扫描指定的文本片段。请注意,infoType 为必需参数,因为所有自定义 infoType(包括存储的自定义字典)的名称都不得与内置的 infoType 或其他自定义 infoType 冲突。storedType 参数包含存储的自定义 infoType 的完整资源路径。

JSON 输入

POST https://dlp.googleapis.com/v2/projects/[PROJECT_ID]/content:inspect?key={YOUR_API_KEY}

{
  "inspectConfig":{
    "customInfoTypes":[
      {
        "infoType":{
          "name":"GITHUB_LOGINS"
        },
        "storedType":{
          "name":"projects/[PROJECT_ID]/storedInfoTypes/github-logins"
        }
      }
    ]
  },
  "item":{
    "value":"The commit was made by githubuser."
  }
}

排查错误

如果您在尝试创建存储的自定义字典时看到错误,且该错误说明 Cloud DLP 无法从基于 Cloud Storage 的术语列表创建字典,则可能的原因如下:

  • 您已经达到存储的自定义字典的上限。根据具体的问题,您可以选择多种解决方法:
    • 如果已达到 Cloud Storage 中单个存储的自定义字典的大小上限 (200 MB),您可以尝试将文件拆分为多个文件。您仍然可以使用这些文件来组建单个自定义字典,只要文件的总大小不超过 Cloud Storage 中所有存储的自定义字典文件的总大小上限 (1 GB) 即可。
    • BigQuery 与 Cloud Storage 的限制不同。请考虑将术语移动到 BigQuery 表中,但要注意 BigQuery 中自定义字典列的大小上限 (1 GB) 和最大行数 (5000000)。
    • 如果您的术语列表文件超出了自定义字典源术语列表的所有适用限制,您必须将术语列表文件拆分为 Cloud Storage 中的多个文件,并为每个文件创建一个字典,然后为创建的每个字典创建不同的扫描作业。
  • 您有一条或多条术语未包含至少一个字母或数字。 Cloud DLP 无法扫描仅包含空格或符号的术语。术语必须至少含有一个字母或数字。请查看您的术语列表是否包含任何此类术语,如果有,请进行更正或将其删除。
  • 您的术语列表包含一个含有太多“成分”的短语。此处所述的“成分”是指仅包含字母、仅包含数字或仅包含非字母和非数字字符(如空格或符号)的连续序列。请查看您的术语列表是否包含任何此类术语,如果有,请进行更正或将其删除。
  • DLP 服务帐号无权访问字典源数据或用于存储字典文件的 Cloud Storage 存储分区。要解决此问题,请为 DLP 服务帐号授予 Cloud Storage 的管理员角色或授予 BigQuery 的 dataOwner 角色和 jobUser 角色。

API 概览

存储的自定义字典因其大小和复杂性而被视为存储的 infoType。目前,存储的自定义字典是唯一的存储的 infoType 类型。

存储的 infoType 在 Cloud DLP 中由 StoredInfoType 对象表示,并附带以下相关对象:

  • StoredInfoTypeConfig 包含存储的 infoType 的配置,其中包括名称和说明等详细信息。
  • StoredInfoTypeVersion 包含存储的 infoType 的详情(例如其创建日期和时间),以及创建当前存储的 infoType 版本时出现的最近五条错误消息。
  • StoredInfoTypeState 包含存储的 infoType 的最新版本以及任何待处理版本的状态。状态信息包括存储的 infoType 是正在重新构建、可供使用还是无效。

如需创建、修改或删除存储的 infoType,请使用以下方法:

  • storedInfoTypes.create:通过您指定的 StoredInfoTypeConfig,新建存储的 infoType。
  • storedInfoTypes.patch:使用您指定的新 StoredInfoTypeConfig 重新构建存储的 infoType;如果未指定,则使用现有 StoredInfoTypeConfig 创建存储的 infoType 的新版本。
  • storedInfoTypes.get:检索指定存储的 infoType 的 StoredInfoTypeConfig 和任何待处理版本。
  • storedInfoTypes.list:列出所有当前存储的 infoType。
  • storedInfoTypes.delete:删除指定的存储的 infoType。

除了此处所述的存储的 infoType API 之外,以下对象专用于存储的自定义字典:

  • LargeCustomDictionaryConfig 指定以下两项:
    • Cloud Storage 或 BigQuery 中存储短语列表的位置。
    • Cloud Storage 中用于存储生成的字典文件的位置。

字典匹配详情

以下是关于 Cloud DLP 如何与字典字词和短语进行匹配的指南。这些要点同时适用于常规自定义字典和存储的自定义字典:

  • 字典字词不区分大小写。如果您的字典包含 Abby,将匹配 abbyABBYAbby 等。
  • 扫描匹配项时,字典或要扫描的内容中,除了 Unicode 基本多语言平面中包含的字母和数字外,其他所有字符一律被视为空格。如果您的字典扫描 Abby Abernathy,将匹配 abby abernathyAbby, AbernathyAbby (ABERNATHY) 等。
  • 任何匹配项两侧的字符均必须与字词中相邻字符的类型(字母或数字)不同。如果您的字典扫描 Abi,将匹配 Abi904 的前三个字符,但不匹配 Abigail 的前三个字符。
  • 如果字典字词包含大量非字母或数字的字符,则可能导致意外结果,因为这些字符均被视为空格。