本主题介绍如何创建和重新构建大型自定义字典。还介绍了几种错误场景。
何时选择较大的自定义字典,而不是常规自定义字典
如果您想要扫描内容中的成千上万个敏感字词或短语,常规自定义字典检测器就足够了。如果您的术语列表较多或者经常更改,请考虑创建可支持数千万个术语的大型自定义字典。
自定义字典与其他自定义 infoType 的大小差异
大型自定义字典与其他自定义 infoType 的不同之处在于,每个大型自定义字典由两部分组成:
- 您创建和定义的短语列表。该列表以文本文件的形式存储在 Cloud Storage 中或以列的形式存储在 BigQuery 表中。
- 字典文件,由敏感数据保护生成并存储在 Cloud Storage 中。字典文件由术语列表的副本和布隆过滤器组成,有助于搜索和匹配。
创建大型自定义字典
本部分介绍如何创建、修改和重新构建大型自定义字典。
创建术语列表
创建一个列表,其中包含您希望新的 infoType 检测器搜索的所有字词和短语。执行下列其中一项操作:
- 将每个字词或短语各自位于一行的文本文件放在 Cloud Storage 存储桶中。
- 将 BigQuery 表的一列指定为字词和短语的容器。在列中为每个条目提供单独的行。只要所有字典字词和短语都在一列中,您就可以使用现有 BigQuery 表。
您可能会组合出过大的敏感数据保护无法处理的术语列表。如果您看到错误消息,请参阅本主题后面的排查错误。
创建存储的 infoType
创建术语列表后,请使用敏感数据保护创建字典:
控制台
在 Cloud Storage 存储桶中,创建一个新的文件夹,敏感数据保护将存储生成的字典。
敏感数据保护会在您指定的位置创建包含字典文件的文件夹。
在 Google Cloud 控制台中,转到创建 infoType 页面。
在类型部分,选择大型自定义字典。
对于 InfoType ID,输入存储的 infoType 的标识符。
在配置检查和去标识化作业时,您将使用此标识符。您可以在名称中使用字母、数字、连字符和下划线。
对于 InfoType 显示名称,输入存储的 infoType 的名称。
您可以在名称中使用空格和标点符号。
在说明部分,输入存储的 infoType 检测内容的说明。
对于存储类型,请选择术语列表的位置:
- BigQuery:输入项目 ID、数据集 ID 和表 ID。 在字段名称字段中,输入列标识符。您最多只能指定表格中的一列。
- Google Cloud Storage:输入文件的路径。
在输出存储桶或文件夹部分,输入您在第 1 步中创建的文件夹的 Cloud Storage 位置。
点击创建。
系统会显示存储的 infoType 的摘要。生成字典后,如果存储的新 infoType 可供使用,则 infoType 的状态会显示 Ready。
C#
如需了解如何安装和使用用于敏感数据保护的客户端库,请参阅敏感数据保护客户端库。
如需向敏感数据保护服务进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Go
如需了解如何安装和使用用于敏感数据保护的客户端库,请参阅敏感数据保护客户端库。
如需向敏感数据保护服务进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需了解如何安装和使用用于敏感数据保护的客户端库,请参阅敏感数据保护客户端库。
如需向敏感数据保护服务进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需了解如何安装和使用用于敏感数据保护的客户端库,请参阅敏感数据保护客户端库。
如需向敏感数据保护服务进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
PHP
如需了解如何安装和使用用于敏感数据保护的客户端库,请参阅敏感数据保护客户端库。
如需向敏感数据保护服务进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Python
如需了解如何安装和使用用于敏感数据保护的客户端库,请参阅敏感数据保护客户端库。
如需向敏感数据保护服务进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
REST
- 在 Cloud Storage 存储桶中为字典创建一个新文件夹。 敏感数据保护会在您指定的位置创建包含字典文件的文件夹。
- 使用
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
方法时,它会创建新的存储 infoType,具体而言就是大型自定义字典检测器。此示例根据存储在公开提供的 BigQuery 数据库 (bigquery-public-data.samples.github_nested
) 中的术语列表创建存储的 infoType。该数据库包含提交中使用的所有 GitHub 用户名。生成的字典的输出路径设置为名为 dlptesting
的 Cloud Storage 存储桶,存储的 infoType 名为 github-usernames
。
JSON 输入
POST https://dlp.googleapis.com/v2/projects/PROJECT_ID/storedInfoTypes
{
"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"
}
重建字典
如果要更新字典,请先更新来源术语列表,然后指示敏感数据保护重新构建存储的 infoType。
更新 Cloud Storage 或 BigQuery 中的现有源术语列表。
根据需要添加、移除或更改字词或短语。
使用 Google Cloud 控制台或
storedInfoTypes.patch
方法“重新构建”存储的 infoType,以创建它的新版本。重新构建会创建字典的新版本,该版本将取代旧字典。
将存储的 infoType 重新构建为新版本时,旧版本会被删除。 在敏感数据保护更新存储的 infoType 时,其状态为“待处理”。在此期间,存储的 infoType 的旧版本仍然存在。在存储的 infoType 处于待处理状态时运行的任何扫描都将使用旧版存储的 infoType。
如需重新构建存储的 infoType,请执行以下操作:
控制台
- 更新并保存 Cloud Storage 或 BigQuery 中的术语列表。
在 Google Cloud 控制台中,转到存储的 infoType 列表。
点击要更新的存储的 infoType 的 ID。
在 InfoType 详情页面上,点击重新构建数据。
敏感数据保护会根据您对来源术语列表所做的更改重新构建存储的 infoType。存储的 infoType 的状态为“就绪”后,您就可以使用它了。任何使用存储的 infoType 的模板或作业触发器都将自动使用重新构建的版本。
C#
如需了解如何安装和使用用于敏感数据保护的客户端库,请参阅敏感数据保护客户端库。
如需向敏感数据保护服务进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Go
如需了解如何安装和使用用于敏感数据保护的客户端库,请参阅敏感数据保护客户端库。
如需向敏感数据保护服务进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需了解如何安装和使用用于敏感数据保护的客户端库,请参阅敏感数据保护客户端库。
如需向敏感数据保护服务进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需了解如何安装和使用用于敏感数据保护的客户端库,请参阅敏感数据保护客户端库。
如需向敏感数据保护服务进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
PHP
如需了解如何安装和使用用于敏感数据保护的客户端库,请参阅敏感数据保护客户端库。
如需向敏感数据保护服务进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Python
如需了解如何安装和使用用于敏感数据保护的客户端库,请参阅敏感数据保护客户端库。
如需向敏感数据保护服务进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
REST
更新术语列表
如果您只更新大型自定义字典中的字词列表,则 storedInfoTypes.patch
请求仅需要 name
字段。提供要重新构建的存储的 infoType 的完整资源名称。
以下模式表示 name
字段的有效条目:
organizations/ORGANIZATION_ID/storedInfoTypes/STORED_INFOTYPE_ID
projects/PROJECT_ID/storedInfoTypes/STORED_INFOTYPE_ID
将 STORED_INFOTYPE_ID 替换为您要重新构建的已存储 infoType 的标识符。
如果您不知道存储的 infoType 的标识符,请调用 storedInfoTypes.list
方法查看所有当前存储的 infoType 的列表。
示例
PATCH https://dlp.googleapis.com/v2/projects/PROJECT_ID/storedInfoTypes/STORED_INFOTYPE_ID
在这种情况下,不需要提供请求正文。
切换源术语列表
您可以将存储的 infoType 的源术语列表从存储在 BigQuery 中的列表更改为存储在 Cloud Storage 中的术语列表。使用 storedInfoTypes.patch
方法,但在之前使用过 BigQueryField
对象的 LargeCustomDictionaryConfig
中添加一个 CloudStorageFileSet
对象。然后,将 updateMask
参数设置为您重新构建的存储的 infoType 参数(采用 FieldMask
格式)。例如,updateMask
参数中的以下 JSON 状态表明 Cloud Storage 路径的网址已更新 (large_custom_dictionary.cloud_storage_file_set.url
):
示例
PATCH https://dlp.googleapis.com/v2/projects/PROJECT_ID/storedInfoTypes/github-usernames
{
"config":{
"largeCustomDictionary":{
"cloudStorageFileSet":{
"url":"gs://[BUCKET_NAME]/[PATH_TO_FILE]"
}
}
},
"updateMask":"large_custom_dictionary.cloud_storage_file_set.url"
}
同样,您可以将术语列表从存储在 BigQuery 表中的术语列表切换为存储在 Cloud Storage 存储桶中的术语列表。
使用大型自定义字典检测器扫描内容
使用大型自定义字典检测器扫描内容与使用任何其他自定义 infoType 检测器扫描内容类似。
此过程假定您已有存储的 infoType。如需了解详情,请参阅本页面上的创建存储的 infoType。
控制台
您可以在执行以下操作时应用大型自定义字典检测器:
在该页面的配置检测部分的 InfoType 子部分中,您可以指定大型自定义字典 infoType。
- 点击管理 infoType。
- 在 InfoTypes 窗格中,点击InfoTypes标签页。
- 点击添加自定义 infoType。
在添加自定义 infoType 窗格中,执行以下操作:
- 在类型部分,选择存储的 infoType。
- 对于 InfoType,输入自定义 infoType 的名称。您可以使用字母、数字和下划线。
对于可能性,选择要分配给与此自定义 infoType 匹配的所有发现结果的默认可能性级别。您可以使用热词规则进一步微调单个发现结果的可能性级别。
如果您未指定默认值,则默认可能性级别会设置为
VERY_LIKELY
。如需了解详情,请参阅匹配可能性。对于敏感度,选择要分配给与此自定义 infoType 匹配的所有发现结果的敏感度级别。如果您未指定值,这些发现结果的敏感度级别将设置为
HIGH
。敏感度得分用于数据分析文件。剖析数据时,敏感数据保护使用 infoType 的敏感度分数计算敏感度级别。
在存储的 infoType 名称部分,选择存储新自定义 infoType 的 infoType。
点击完成,关闭添加自定义 infoType 窗格。
可选:在内置标签页上,修改所选的内置 infoType。
点击完成以关闭 InfoType 窗格。
自定义 infoType 会添加到敏感数据保护扫描的 infoType 列表中。但是,在您保存作业、作业触发器、模板或扫描配置之前,这种选择并非最终选择。
创建或修改完配置后,点击保存。
C#
如需了解如何安装和使用用于敏感数据保护的客户端库,请参阅敏感数据保护客户端库。
如需向敏感数据保护服务进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Go
如需了解如何安装和使用用于敏感数据保护的客户端库,请参阅敏感数据保护客户端库。
如需向敏感数据保护服务进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需了解如何安装和使用用于敏感数据保护的客户端库,请参阅敏感数据保护客户端库。
如需向敏感数据保护服务进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需了解如何安装和使用用于敏感数据保护的客户端库,请参阅敏感数据保护客户端库。
如需向敏感数据保护服务进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
PHP
如需了解如何安装和使用用于敏感数据保护的客户端库,请参阅敏感数据保护客户端库。
如需向敏感数据保护服务进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Python
如需了解如何安装和使用用于敏感数据保护的客户端库,请参阅敏感数据保护客户端库。
如需向敏感数据保护服务进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
REST
以下示例在发送到 content.inspect
方法后,会使用指定的存储的 infoType 检测器扫描给定文本。infoType
参数是必需的,因为所有自定义 infoType 的名称必须与内置 infoType 或其他自定义 infoType 不冲突。storedType
参数包含存储的 infoType 的完整资源路径。
JSON 输入
POST https://dlp.googleapis.com/v2/projects/PROJECT_ID/content:inspect
{
"inspectConfig":{
"customInfoTypes":[
{
"infoType":{
"name":"GITHUB_LOGINS"
},
"storedType":{
"name":"projects/PROJECT_ID/storedInfoTypes/github-logins"
}
}
]
},
"item":{
"value":"The commit was made by githubuser."
}
}
排查错误
如果您在尝试根据 Cloud Storage 中存储的术语列表创建存储的 infoType 时收到错误消息,可能有以下原因:
- 您遇到了存储的 infoType 的上限。根据具体问题,您可以选择多种解决方法:
- 如果达到 Cloud Storage 中单个输入文件的大小上限 (200 MB),请尝试将文件拆分为多个文件。您可以使用多个文件来组建一个自定义字典,前提是所有文件的总大小不超过 1 GB。
- BigQuery 与 Cloud Storage 的限制不同。请考虑将这些术语移动到 BigQuery 表中。在 BigQuery 中,自定义字典列的大小上限为 1 GB,行数上限为 500 万行。
- 如果您的术语列表文件超出了源术语列表的所有适用限制,则必须将术语列表文件拆分为多个文件,并为每个文件创建一个字典。然后,为每个字典创建一个单独的扫描作业。
- 您有一条或多条术语未包含至少一个字母或数字。 敏感数据保护无法扫描仅包含空格或符号的字词。术语必须至少含有一个字母或数字。请查看您的术语列表是否包含任何此类术语,如果有,请进行更正或将其删除。
- 您的术语列表包含一个含有太多“成分”的短语。此处所述的“成分”是指仅包含字母、仅包含数字或仅包含非字母和非数字字符(如空格或符号)的连续序列。请查看您的术语列表是否包含任何此类术语,如果有,请进行更正或将其删除。
- 敏感数据保护服务代理无权访问字典源数据或用于存储字典文件的 Cloud Storage 存储桶。如需解决此问题,请向敏感数据保护服务代理授予 Storage Admin (
roles/storage.admin
) 角色或 BigQuery Data Owner (roles/bigquery.dataOwner
) 和 BigQuery Job User (roles/bigquery.jobUser
) 角色。
API 概览
如果要创建大型自定义字典检测器,则必须创建存储的 infoType。
存储的 infoType 在敏感数据保护中由 StoredInfoType
对象表示。它包含以下相关对象:
StoredInfoTypeVersion
包含创建日期和时间,以及创建当前版本时出现的最后五条错误消息。StoredInfoTypeConfig
包含存储的 infoType 的配置,包括其名称和说明。对于大型自定义字典,type
必须是LargeCustomDictionaryConfig
。LargeCustomDictionaryConfig
会指定以下两项:- Cloud Storage 或 BigQuery 中存储短语列表的位置。
- Cloud Storage 中用于存储生成的字典文件的位置。
StoredInfoTypeState
包含存储的 infoType 的最新版本以及任何待处理版本的状态。状态信息包括存储的 infoType 是正在重新构建、可供使用还是无效。
字典匹配详情
以下是有关敏感数据保护如何与字典字词和短语匹配的指南。以下要点适用于常规自定义字典和大型自定义字典:
- 字典字词不区分大小写。如果您的字典包含
Abby
,将匹配abby
、ABBY
、Abby
等。 - 扫描匹配项时,字典或要扫描的内容中,除了 Unicode 基本多语言平面中包含的字母和数字外,其他所有字符一律被视为空格。如果您的字典扫描
Abby Abernathy
,将匹配abby abernathy
、Abby, Abernathy
、Abby (ABERNATHY)
等。 - 任何匹配项两侧的字符均必须与字词中相邻字符的类型(字母或数字)不同。如果您的字典扫描
Abi
,将匹配Abi904
的前三个字符,但不匹配Abigail
的前三个字符。 - 如果字典字词包含 Unicode 标准的补充多语言平面中的字符,可能会产生意外结果。此类字符的示例包括中文、日语、韩语和表情符号。
如需创建、修改或删除存储的 infoType,请使用以下方法:
storedInfoTypes.create
:通过您指定的StoredInfoTypeConfig
,新建存储的 infoType。storedInfoTypes.patch
:使用您指定的新StoredInfoTypeConfig
重新构建存储的 infoType。如果未指定,则此方法会使用现有StoredInfoTypeConfig
创建新版存储的 infoType。storedInfoTypes.get
:检索指定存储的 infoType 的StoredInfoTypeConfig
和任何待处理版本。storedInfoTypes.list
:列出所有当前存储的 infoType。storedInfoTypes.delete
:删除指定的存储的 infoType。