Creating Cloud DLP inspection templates

This topic describes in detail how to create a new inspection template. For a quick walkthrough of how to create a new inspection template using the Cloud Data Loss Prevention (DLP) UI, see Quickstart: Creating a Cloud DLP inspection template.

About templates

You can use templates to create and persist configuration information to use with Cloud DLP. Templates are useful for decoupling configuration information—such as what you inspect for and how you de-identify it—from the implementation of your requests. Templates provide a way to re-use configuration and enable consistency across users and datasets. In addition, whenever you update a template, it's updated for any job trigger that uses it.

Cloud DLP supports inspection templates, which are discussed in this topic, and de-identification templates, which are discussed in Creating Cloud DLP de-identification templates.

For conceptual information about templates in Cloud DLP, see Templates.

Create a new inspection template

To create a new Cloud DLP template:

Console

  1. In the GCP Console, open Cloud DLP.

    Go to Cloud DLP UI Beta

  2. From the Create menu, choose Template.

    Screenshot of DLP UI with Create menu > Templates
        selected.

    Alternatively, click the following button:

    Create new template

The Create template page contains the following sections:

  1. Naming
  2. InfoTypes
  3. Confidence threshold

Naming

Under Naming, enter an identifier for the inspection template. This is how you'll refer to the template when you run a job, create a job trigger, and so on. You can use letters, numbers, and hyphens. If you want, you can also enter a description to better remember what the template does.

InfoTypes

Next, you configure what Cloud DLP detects in your content by choosing an infoType and other options.

InfoType detectors find sensitive data of a certain type. For example, the Cloud DLP US_SOCIAL_SECURITY_NUMBER infoType detector finds US Social Security numbers. In addition to the built-in infoType detectors, you can create your own custom infoType detectors.

Under InfoTypes, choose the infoType detector that corresponds to a data type you want to scan for. You can also leave this field blank to scan for all default infoTypes. More information about each detector is provided in InfoType detector reference.

You can also add custom infoType detectors in the Custom infoTypes section, and customize both built-in and custom infoType detectors in the Inspection rulesets section.

Custom infoTypes

To add a custom infoType detector:

  1. Click Add custom infoType.
  2. Choose the type of custom infoType detector you want to create:
    • Words or phrases: Matches on one or more words or phrases that you enter into the field. Use this custom infoType when you have just a few words or phrases to search for. Give your custom infoType a name, and then, under List of words or phrases, type the word or phrase you want Cloud DLP to match on. To search on multiple words or phrases, press Enter after each one. For more information, see Creating a regular custom dictionary detector.
    • Dictionary path: Searches your content for items in a list of words and phrases. The list is stored in a text file in Cloud Storage. Use this custom infoType when you have anywhere from a few to several hundred thousand words or phrases to search for. This method is also useful if your list contains sensitive elements and you don't want to store them inside of a job or template. Give your custom infoType a name, and then, under Dictionary location, enter or browse to the Cloud Storage path where the dictionary file is stored. For more information, see Creating a regular custom dictionary detector.
    • Regex: Matches content based on a regular expression. Give your custom infoType a name, and then, in the Regex field, enter a regex pattern to match words and phrases. See the supported regex syntax.
    • Stored infoType: This option adds a stored custom dictionary detector, which is a kind of dictionary detector that is built from either a large text file stored in Cloud Storage or a single column of a BigQuery table. Use this kind of custom infoType when you have anywhere from several hundred thousand to tens of millions of words or phrases to search for. Be aware that this is the only option in this menu for which you must have already created the stored infoType to use it. Give your custom infoType a name (different from the name you gave the stored infoType), and then, in the Stored infoType field, enter the name of the stored infoType. For more information about creating stored custom dictionaries, see Creating a stored custom dictionary detector.

Click Add custom infoType again to add additional custom infoType detectors.

Inspection rulesets

Inspection rulesets allow you to customize both built-in and custom infoType detectors using context rules. The two types of inspection rules are:

To add a new ruleset, first specify one or more built-in or custom infoType detectors in the InfoTypes section. These are the infoType detectors that your rulesets will be modifying. Then, do the following:

  1. Click in the Choose infoTypes field. The infoType or infoTypes you specified previously appear below the field in a menu, as shown here:
  2. Screenshot of the DLP UI's inspection rulesets configuration.
  3. Choose an infoType from the menu, and then click Add rule. A menu appears with the two options Hotword rule and Exclusion rule.

For hotword rules, choose Hotword rules. Then, do the following:

  1. In the Hotword field, enter a regular expression that Cloud DLP should look for.
  2. From the Hotword proximity menu, choose whether the hotword you entered is found before or after the chosen infoType.
  3. In Hotword distance from infoType, enter the approximate number of characters between the hotword and the chosen infoType.
  4. In Confidence level adjustment, choose whether to assign matches a fixed likelihood level, or to increase or decrease the default likelihood level by a certain amount.

For exclusion rules, choose Exclusion rules. Then, do the following:

  1. In the Exclude field, enter a regular expression (regex) that Cloud DLP should look for.
  2. From the Matching type menu, choose one of the following:
    • Full match: The finding must completely match the regex.
    • Partial match: A substring of the finding can match the regex.
    • Inverse match: The finding doesn't match the regex.

You can add additional hotword or exclusion rules and rulesets to further refine your scan results.

Confidence threshold

Every time Cloud DLP detects a potential match for sensitive data, it assigns it a likelihood value on a scale from "Very unlikely" to "Very likely." When you set a likelihood value here, you are instructing Cloud DLP to only match on data that corresponds to that likelihood value or higher.

The default value of "Possible" is sufficient for most purposes. If you routinely get matches that are too broad, move the slider up. If you get too few matches, move the slider down.

When you're done, click Create to create the template. The template's summary information page appears.

To return to the main Cloud DLP page, click the Back arrow in the GCP Console.

Protocol

An inspection template is a reusable inspection configuration plus some metadata. In API terms, the InspectTemplate object is effectively an InspectConfig object that includes a few more fields of metadata, such as a display name and a description. Therefore, to create a new inspection template, the basic steps are:

  1. Start with an InspectConfig object.
  2. Call or POST the create method of either the projects.inspectTemplates or organizations.inspectTemplates resource, including in your request an InspectTemplate object that contains a display name, a description, and that InspectConfig object.

The returned InspectTemplate will be ready for use immediately. You can reference it in other calls or jobs by its name. You can list the existing templates by calling the *.inspectTemplates.list method. To view a specific template, call the *.inspectTemplates.get method. Note that the limit for the number of templates you can create is 1000.

If you've already had some experience inspecting text, images, or structured content for sensitive content using Cloud DLP, you've already created an InspectConfig object. One additional step turns it into an InspectTemplate object.

The following JSON is an example of what you can send to the projects.inspectTemplates.create method. (Try it for yourself in APIs Explorer.) This JSON creates a new template with the given display name and description, and scans for matches on the infoTypes PHONE_NUMBER and US_TOLLFREE_PHONE_NUMBER. It will include in its findings up to 100 matches whose likelihoods are at least POSSIBLE, and will include a snippet of context for each.

JSON input:

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

{
  "inspectTemplate":{
    "displayName":"Phone number inspection",
    "description":"Scans for phone numbers",
    "inspectConfig":{
      "infoTypes":[
        {
          "name":"PHONE_NUMBER"
        },
        {
          "name":"US_TOLLFREE_PHONE_NUMBER"
        }
      ],
      "minLikelihood":"POSSIBLE",
      "limits":{
        "maxFindingsPerRequest":100
      },
      "includeQuote":true
    }
  }
}

JSON output:

The response JSON looks like the following:

{
  "name":"projects/[PROJECT_ID]/inspectTemplates/[JOB_ID]",
  "displayName":"Phone number inspection",
  "description":"Scans for phone numbers",
  "createTime":"2018-11-30T07:26:28.164136Z",
  "updateTime":"2018-11-30T07:26:28.164136Z",
  "inspectConfig":{
    "infoTypes":[
      {
        "name":"PHONE_NUMBER"
      },
      {
        "name":"US_TOLLFREE_PHONE_NUMBER"
      }
    ],
    "minLikelihood":"POSSIBLE",
    "limits":{
      "maxFindingsPerRequest":100
    },
    "includeQuote":true
  }
}

Java

/**
 * Create a new DLP inspection configuration template.
 *
 * @param displayName (Optional) The human-readable name to give the template
 * @param projectId Google Cloud Project ID to call the API under
 * @param templateId (Optional) The name of the template to be created
 * @param infoTypeList The infoTypes of information to match
 * @param minLikelihood The minimum likelihood required before returning a match
 * @param maxFindings The maximum number of findings to report per request (0 = server maximum)
 */
private static void createInspectTemplate(
    String displayName,
    String templateId,
    String description,
    String projectId,
    List<InfoType> infoTypeList,
    Likelihood minLikelihood,
    int maxFindings) {
  try (DlpServiceClient dlpServiceClient = DlpServiceClient.create()) {

    FindingLimits findingLimits =
        FindingLimits.newBuilder().setMaxFindingsPerRequest(maxFindings).build();

    // Construct the inspection configuration for the template
    InspectConfig inspectConfig =
        InspectConfig.newBuilder()
            .addAllInfoTypes(infoTypeList)
            .setMinLikelihood(minLikelihood)
            .setLimits(findingLimits)
            .build();

    InspectTemplate inspectTemplate =
        InspectTemplate.newBuilder()
            .setInspectConfig(inspectConfig)
            .setDisplayName(displayName)
            .setDescription(description)
            .build();

    CreateInspectTemplateRequest createInspectTemplateRequest =
        CreateInspectTemplateRequest.newBuilder()
            .setParent(ProjectName.of(projectId).toString())
            .setInspectTemplate(inspectTemplate)
            .setTemplateId(templateId)
            .build();

    InspectTemplate response =
        dlpServiceClient.createInspectTemplate(createInspectTemplateRequest);
    System.out.printf("Template created: %s", response.getName());
  } catch (Exception e) {
    System.out.printf("Error creating template: %s", e.getMessage());
  }
}

Node.js

// Imports the Google Cloud Data Loss Prevention library
const DLP = require('@google-cloud/dlp');

// Instantiates a client
const dlp = new DLP.DlpServiceClient();

// The project ID to run the API call under
// const callingProjectId = process.env.GCLOUD_PROJECT;

// The minimum likelihood required before returning a match
// const minLikelihood = 'LIKELIHOOD_UNSPECIFIED';

// The maximum number of findings to report per request (0 = server maximum)
// const maxFindings = 0;

// The infoTypes of information to match
// const infoTypes = [{ name: 'PHONE_NUMBER' }, { name: 'EMAIL_ADDRESS' }, { name: 'CREDIT_CARD_NUMBER' }];

// Whether to include the matching string
// const includeQuote = true;

// (Optional) The name of the template to be created.
// const templateId = 'my-template';

// (Optional) The human-readable name to give the template
// const displayName = 'My template';

// Construct the inspection configuration for the template
const inspectConfig = {
  infoTypes: infoTypes,
  minLikelihood: minLikelihood,
  includeQuote: includeQuote,
  limits: {
    maxFindingsPerRequest: maxFindings,
  },
};

// Construct template-creation request
const request = {
  parent: dlp.projectPath(callingProjectId),
  inspectTemplate: {
    inspectConfig: inspectConfig,
    displayName: displayName,
  },
  templateId: templateId,
};

try {
  const [response] = await dlp.createInspectTemplate(request);
  const templateName = response.name;
  console.log(`Successfully created template ${templateName}.`);
} catch (err) {
  console.log(`Error in createInspectTemplate: ${err.message || err}`);
}

Python

def create_inspect_template(project, info_types,
                            template_id=None, display_name=None,
                            min_likelihood=None, max_findings=None,
                            include_quote=None):
    """Creates a Data Loss Prevention API inspect template.
    Args:
        project: The Google Cloud project id to use as a parent resource.
        info_types: A list of strings representing info types to look for.
            A full list of info type categories can be fetched from the API.
        template_id: The id of the template. If omitted, an id will be randomly
            generated.
        display_name: The optional display name of the template.
        min_likelihood: A string representing the minimum likelihood threshold
            that constitutes a match. One of: 'LIKELIHOOD_UNSPECIFIED',
            'VERY_UNLIKELY', 'UNLIKELY', 'POSSIBLE', 'LIKELY', 'VERY_LIKELY'.
        max_findings: The maximum number of findings to report; 0 = no maximum.
        include_quote: Boolean for whether to display a quote of the detected
            information in the results.
    Returns:
        None; the response from the API is printed to the terminal.
    """

    # Import the client library
    import google.cloud.dlp

    # Instantiate a client.
    dlp = google.cloud.dlp.DlpServiceClient()

    # Prepare info_types by converting the list of strings into a list of
    # dictionaries (protos are also accepted).
    info_types = [{'name': info_type} for info_type in info_types]

    # Construct the configuration dictionary. Keys which are None may
    # optionally be omitted entirely.
    inspect_config = {
        'info_types': info_types,
        'min_likelihood': min_likelihood,
        'include_quote': include_quote,
        'limits': {'max_findings_per_request': max_findings},
    }

    inspect_template = {
        'inspect_config': inspect_config,
        'display_name': display_name,
    }

    # Convert the project id into a full resource id.
    parent = dlp.project_path(project)

    # Call the API.
    response = dlp.create_inspect_template(
        parent, inspect_template=inspect_template, template_id=template_id)

    print('Successfully created template {}'.format(response.name))

Go


// createInspectTemplate creates a template with the given configuration.
func createInspectTemplate(w io.Writer, client *dlp.Client, project string, minLikelihood dlppb.Likelihood, maxFindings int32, templateID, displayName, description string, infoTypes []string) {
	// Convert the info type strings to a list of InfoTypes.
	var i []*dlppb.InfoType
	for _, it := range infoTypes {
		i = append(i, &dlppb.InfoType{Name: it})
	}

	// Create a configured request.
	req := &dlppb.CreateInspectTemplateRequest{
		Parent:     "projects/" + project,
		TemplateId: templateID,
		InspectTemplate: &dlppb.InspectTemplate{
			DisplayName: displayName,
			Description: description,
			InspectConfig: &dlppb.InspectConfig{
				InfoTypes:     i,
				MinLikelihood: minLikelihood,
				Limits: &dlppb.InspectConfig_FindingLimits{
					MaxFindingsPerRequest: maxFindings,
				},
			},
		},
	}
	// Send the request.
	resp, err := client.CreateInspectTemplate(context.Background(), req)
	if err != nil {
		log.Fatalf("error creating inspect template: %v", err)
	}
	// Print the result.
	fmt.Fprintf(w, "Successfully created inspect template: %v", resp.GetName())
}

PHP

/**
 * Create a new DLP inspection configuration template.
 */
use Google\Cloud\Dlp\V2\DlpServiceClient;
use Google\Cloud\Dlp\V2\InfoType;
use Google\Cloud\Dlp\V2\InspectConfig;
use Google\Cloud\Dlp\V2\InspectTemplate;
use Google\Cloud\Dlp\V2\Likelihood;
use Google\Cloud\Dlp\V2\InspectConfig\FindingLimits;

/** Uncomment and populate these variables in your code */
// $callingProjectId = 'The project ID to run the API call under';
// $templateId = 'The name of the template to be created';
// $displayName = ''; // (Optional) The human-readable name to give the template
// $description = ''; // (Optional) A description for the trigger to be created
// $maxFindings = 0;  // (Optional) The maximum number of findings to report per request (0 = server maximum)

// Instantiate a client.
$dlp = new DlpServiceClient();

// ----- Construct inspection config -----
// The infoTypes of information to match
$personNameInfoType = (new InfoType())
    ->setName('PERSON_NAME');
$phoneNumberInfoType = (new InfoType())
    ->setName('PHONE_NUMBER');
$infoTypes = [$personNameInfoType, $phoneNumberInfoType];

// Whether to include the matching string in the response
$includeQuote = true;

// The minimum likelihood required before returning a match
$minLikelihood = likelihood::LIKELIHOOD_UNSPECIFIED;

// Specify finding limits
$limits = (new FindingLimits())
    ->setMaxFindingsPerRequest($maxFindings);

// Create the configuration object
$inspectConfig = (new InspectConfig())
    ->setMinLikelihood($minLikelihood)
    ->setLimits($limits)
    ->setInfoTypes($infoTypes)
    ->setIncludeQuote($includeQuote);

// Construct inspection template
$inspectTemplate = (new InspectTemplate())
    ->setInspectConfig($inspectConfig)
    ->setDisplayName($displayName)
    ->setDescription($description);

// Run request
$parent = $dlp->projectName($callingProjectId);
$template = $dlp->createInspectTemplate($parent, [
    'inspectTemplate' => $inspectTemplate,
    'templateId' => $templateId
]);

// Print results
printf('Successfully created template %s' . PHP_EOL, $template->getName());

C#

public static string CreateInspectTemplate(
    string projectId,
    string templateId,
    string displayName,
    string description,
    string likelihood,
    int maxFindings,
    bool includeQuote)
{
    DlpServiceClient client = DlpServiceClient.Create();

    var request = new CreateInspectTemplateRequest
    {
        Parent = $"projects/{projectId}",
        InspectTemplate = new InspectTemplate
        {
            DisplayName = displayName,
            Description = description,
            InspectConfig = new InspectConfig
            {
                MinLikelihood = (Likelihood)Enum.Parse(typeof(Likelihood), likelihood),
                Limits = new InspectConfig.Types.FindingLimits
                {
                    MaxFindingsPerRequest = maxFindings
                },
                IncludeQuote = includeQuote
            },
        },
        TemplateId = templateId
    };

    var response = client.CreateInspectTemplate(request);

    Console.WriteLine($"Successfully created template {response.Name}.");

    return response.Name;
}

หน้านี้มีประโยชน์ไหม โปรดแสดงความคิดเห็น