Übereinstimmungswahrscheinlichkeit anpassen

Mit Hotword-Regeln können Sie integrierte und benutzerdefinierte infoType-Detektoren durch leistungsstarke Kontextregeln erweitern. Ferner können Sie einen vorhandenen infoType-Detektor durch einen Regex- und Näherungsdetektor ergänzen und den Wert für die Übereinstimmungswahrscheinlichkeit entsprechend anpassen. Eine Hotword-Regel ist eine Art Prüfregel, die in Regelsätzen festgelegt wird. Jeder Regelsatz wird auf eine Reihe von infoTypes angewendet, die entweder benutzerdefiniert oder integriert sein können.

Anatomie einer Hotword-Regel

Ein infoType-Detektor kann keine oder mehrere Hotword-Regeln haben. Sie definieren jede Hotword-Regel (HotwordRule-Objekt) innerhalb einer Prüfregel (InspectionRule-Objekt). Jede Prüfregel wird innerhalb eines InspectionRuleSet-Objekt angegeben, das wiederum in einem InspectConfig-Objekt enthalten ist.

Eine einzelne Hotword-Regel sieht als JSON-Objekt innerhalb eines "inspectionRules"-Arrays so aus:

"inspectionRules":[
  {
    "hotwordRule":{
      "hotwordRegex":{
        "pattern":"[REGEX_PATTERN]"
      },
      "proximity":{
        "windowAfter":"[NUM_CHARS_TO_CONSIDER_AFTER_FINDING]",
        "windowBefore":"[NUM_CHARS_TO_CONSIDER_BEFORE_FINDING]"
      }
      "likelihoodAdjustment":{
        "fixedLikelihood":"[LIKELIHOOD_VALUE]"
             -- OR --
        "relativeLikelihood":"[LIKELIHOOD_ADJUSTMENT]"
      },
    }
  },
  ...
]

Jede Hotword-Regel besteht aus drei Komponenten:

  • "hotwordRegex": Ein Regex-Muster (Regex-Objekt), das definiert, was als Hotword gilt.
  • "proximity": In welcher Nähe zum Ergebnis das gesamte Hotword enthalten sein muss. Dieses Feld enthält ein Proximity-Objekt, das zwei Werte umfasst:

    • "windowBefore": Anzahl der Zeichen, die vor dem Ergebnis zu berücksichtigen sind.
    • "windowAfter": Anzahl der Zeichen, die nach dem Ergebnis zu berücksichtigen sind.
  • "likelihoodAdjustment": Die Anpassung der Wahrscheinlichkeit eines Ergebnisses. Dieses Feld enthält ein LikelihoodAdjustment-Objekt, das auf einen von zwei Werten festgelegt werden kann:

    • "fixedLikelihood": Ein fester Likelihood-Wert, auf den das Ergebnis gesetzt werden soll.
    • "relativeLikelihood": Eine Zahl, die die Anzahl der Ebenen angibt, um die die Wahrscheinlichkeit der Feststellung erhöht oder verringert werden soll. Beispiel: Wenn ein Ergebnis ohne die Erkennungsregel POSSIBLE wäre und relativeLikelihood 1 ist, erfolgt ein Heraufsetzen auf LIKELY. Bei einem Wert von -1 dagegen würde eine Herabstufung auf UNLIKELY erfolgen. Die Wahrscheinlichkeit darf niemals unter VERY_UNLIKELY fallen oder VERY_LIKELY übersteigen. Aus diesem Grunde ergibt sich beim Anwenden einer Anpassung von 1, gefolgt von einer Anpassung von -1 bei einer Grundwahrscheinlichkeit von VERY_LIKELY eine endgültige Wahrscheinlichkeit von LIKELY.

Hotword-Beispiel: Krankenaktennummern abgleichen

Angenommen, Sie möchten einen benutzerdefinierten infoType wie eine Krankenaktennummer im Format ###-#-##### erkennen und die Trefferwahrscheinlichkeit des Cloud DLP-Suchvorgangs erhöhen, wenn das Hotword "MRN" (kurz für engl."Medical Record Number", Krankenaktennummer) vor, aber nicht nach dieser Nummer steht. Dementsprechend wäre:

  • 123-4-56789 als Übereinstimmung POSSIBLE.
  • MRN 123-4-56789 als Übereinstimmung VERY_LIKELY.

Das folgende JSON-Codebeispiel und Code-Snippets zeigt den benutzerdefinierten regulären Ausdruck, der wie unter Regex-infoType-Detektor erstellen beschrieben definiert ist, aber zusätzlich die entsprechende Hotword-Regel aufweist:

Protokoll

Weitere Informationen zur Verwendung der Cloud DLP API mit JSON finden Sie im JSON-Schnellstart.

JSON-Eingabe:

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

{
  "item":{
    "value":"Patient's MRN 444-5-22222 and just a number 333-2-33333"
  },
  "inspectConfig":{
    "customInfoTypes":[
      {
        "infoType":{
          "name":"C_MRN"
        },
        "regex":{
          "pattern":"[0-9]{3}-[0-9]{1}-[0-9]{5}"
        },
        "likelihood":"POSSIBLE",
      }
    ],
    "ruleSet":[
        {
        "infoTypes": [{"name" : "C_MRN"}],
        "rules":[
          {
            "hotwordRule":{
              "hotwordRegex":{
                "pattern":"(?i)(mrn|medical)(?-i)"
              },
              "likelihoodAdjustment":{
                "fixedLikelihood":"VERY_LIKELY"
              },
              "proximity":{
                "windowBefore":10
              }
            }
          }
        ]
      }
    ]
  }
}

JSON-Ausgabe (abgekürzt):

{
  "result": {
    "findings": [
      {
        "infoType": {
          "name": "C_MRN"
        },
        "likelihood": "VERY_LIKELY",
        "location": {
          "byteRange": {
            "start": "14",
            "end": "25"
          },
          "codepointRange": { ... }
        }
      },
      {
        "infoType": {
          "name": "C_MRN"
        },
        "likelihood": "POSSIBLE",
          "byteRange": {
            "start": "44",
            "end": "55"
          },
          "codepointRange": { ... }
        }
      }
    ]
  }
}

Die Ausgabe zeigt, dass Cloud DLP mithilfe des benutzerdefinierten infoType-Detektors (den wir "C_MRN" genannt haben) und dem benutzerdefinierten regulären Ausdruck die Krankenaktennummer korrekt identifiziert hat. Aufgrund des Kontextabgleichs in der Hotword-Regel hat Cloud DLP dem ersten Ergebnis, das sich in der Nähe der MRN befand, eine Wahrscheinlichkeit von VERY_LIKELY zugewiesen, so wie dies konfiguriert wurde. Beim zweiten Ergebnis fehlte der Kontext, daher blieb die Wahrscheinlichkeit bei POSSIBLE.

Java

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud DLP finden Sie hier.


import com.google.cloud.dlp.v2.DlpServiceClient;
import com.google.privacy.dlp.v2.ByteContentItem;
import com.google.privacy.dlp.v2.ByteContentItem.BytesType;
import com.google.privacy.dlp.v2.ContentItem;
import com.google.privacy.dlp.v2.CustomInfoType;
import com.google.privacy.dlp.v2.CustomInfoType.DetectionRule.HotwordRule;
import com.google.privacy.dlp.v2.CustomInfoType.DetectionRule.LikelihoodAdjustment;
import com.google.privacy.dlp.v2.CustomInfoType.DetectionRule.Proximity;
import com.google.privacy.dlp.v2.CustomInfoType.Regex;
import com.google.privacy.dlp.v2.Finding;
import com.google.privacy.dlp.v2.InfoType;
import com.google.privacy.dlp.v2.InspectConfig;
import com.google.privacy.dlp.v2.InspectContentRequest;
import com.google.privacy.dlp.v2.InspectContentResponse;
import com.google.privacy.dlp.v2.InspectionRule;
import com.google.privacy.dlp.v2.InspectionRuleSet;
import com.google.privacy.dlp.v2.Likelihood;
import com.google.privacy.dlp.v2.LocationName;
import com.google.protobuf.ByteString;
import java.io.IOException;

public class InspectWithHotwordRules {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String textToInspect = "Patient's MRN 444-5-22222 and just a number 333-2-33333";
    String customRegexPattern = "[1-9]{3}-[1-9]{1}-[1-9]{5}";
    String hotwordRegexPattern = "(?i)(mrn|medical)(?-i)";
    inspectWithHotwordRules(projectId, textToInspect, customRegexPattern, hotwordRegexPattern);
  }

  // Inspects a BigQuery Table
  public static void inspectWithHotwordRules(
      String projectId, String textToInspect, String customRegexPattern, String hotwordRegexPattern)
      throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (DlpServiceClient dlp = DlpServiceClient.create()) {
      // Specify the type and content to be inspected.
      ByteContentItem byteItem =
          ByteContentItem.newBuilder()
              .setType(BytesType.TEXT_UTF8)
              .setData(ByteString.copyFromUtf8(textToInspect))
              .build();
      ContentItem item = ContentItem.newBuilder().setByteItem(byteItem).build();

      // Specify the regex pattern the inspection will look for.
      Regex regex = Regex.newBuilder().setPattern(customRegexPattern).build();

      // Construct the custom regex detector.
      InfoType infoType = InfoType.newBuilder().setName("C_MRN").build();
      CustomInfoType customInfoType =
          CustomInfoType.newBuilder().setInfoType(infoType).setRegex(regex).build();

      // Specify hotword likelihood adjustment.
      LikelihoodAdjustment likelihoodAdjustment =
          LikelihoodAdjustment.newBuilder().setFixedLikelihood(Likelihood.VERY_LIKELY).build();

      // Specify a window around a finding to apply a detection rule.
      Proximity proximity = Proximity.newBuilder().setWindowBefore(10).build();

      // Construct hotword rule.
      HotwordRule hotwordRule =
          HotwordRule.newBuilder()
              .setHotwordRegex(Regex.newBuilder().setPattern(hotwordRegexPattern).build())
              .setLikelihoodAdjustment(likelihoodAdjustment)
              .setProximity(proximity)
              .build();

      // Construct rule set for the inspect config.
      InspectionRuleSet inspectionRuleSet =
          InspectionRuleSet.newBuilder()
              .addInfoTypes(infoType)
              .addRules(InspectionRule.newBuilder().setHotwordRule(hotwordRule))
              .build();

      // Construct the configuration for the Inspect request.
      InspectConfig config =
          InspectConfig.newBuilder()
              .addCustomInfoTypes(customInfoType)
              .setIncludeQuote(true)
              .setMinLikelihood(Likelihood.POSSIBLE)
              .addRuleSet(inspectionRuleSet)
              .build();

      // Construct the Inspect request to be sent by the client.
      InspectContentRequest request =
          InspectContentRequest.newBuilder()
              .setParent(LocationName.of(projectId, "global").toString())
              .setItem(item)
              .setInspectConfig(config)
              .build();

      // Use the client to send the API request.
      InspectContentResponse response = dlp.inspectContent(request);

      // Parse the response and process results
      System.out.println("Findings: " + response.getResult().getFindingsCount());
      for (Finding f : response.getResult().getFindingsList()) {
        System.out.println("\tQuote: " + f.getQuote());
        System.out.println("\tInfo type: " + f.getInfoType().getName());
        System.out.println("\tLikelihood: " + f.getLikelihood());
      }
    }
  }
}

Python

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud DLP finden Sie hier.

def inspect_with_medical_record_number_w_custom_hotwords(
    project, content_string,
):
    """Uses the Data Loss Prevention API to analyze string with medical record
       number custom regex detector, with custom hotwords rules to boost finding
       certainty under some circumstances.
    Args:
        project: The Google Cloud project id to use as a parent resource.
        content_string: The string to inspect.
    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_v2.DlpServiceClient()

    # Construct a custom regex detector info type called "C_MRN",
    # with ###-#-##### pattern, where each # represents a digit from 1 to 9.
    # The detector has a detection likelihood of POSSIBLE.
    custom_info_types = [
        {
            "info_type": {"name": "C_MRN"},
            "regex": {"pattern": "[1-9]{3}-[1-9]{1}-[1-9]{5}"},
            "likelihood": google.cloud.dlp_v2.Likelihood.POSSIBLE,
        }
    ]

    # Construct a rule set with hotwords "mrn" and "medical", with a likelohood
    # boost to VERY_LIKELY when hotwords are present within the 10 character-
    # window preceding the PII finding.
    hotword_rule = {
        "hotword_regex": {"pattern": "(?i)(mrn|medical)(?-i)"},
        "likelihood_adjustment": {
            "fixed_likelihood": google.cloud.dlp_v2.Likelihood.VERY_LIKELY
        },
        "proximity": {"window_before": 10},
    }

    rule_set = [
        {"info_types": [{"name": "C_MRN"}], "rules": [{"hotword_rule": hotword_rule}]}
    ]

    # Construct the configuration dictionary with the custom regex info type.
    inspect_config = {
        "custom_info_types": custom_info_types,
        "rule_set": rule_set,
    }

    # Construct the `item`.
    item = {"value": content_string}

    # Convert the project id into a full resource id.
    parent = f"projects/{project}"

    # Call the API.
    response = dlp.inspect_content(
        request={"parent": parent, "inspect_config": inspect_config, "item": item}
    )

    # Print out the results.
    if response.result.findings:
        for finding in response.result.findings:
            try:
                if finding.quote:
                    print(f"Quote: {finding.quote}")
            except AttributeError:
                pass
            print(f"Info type: {finding.info_type.name}")
            print(f"Likelihood: {finding.likelihood}")
    else:
        print("No findings.")