Übereinstimmungswahrscheinlichkeit anpassen

Mit Hotword-Regeln können Sie integrierte und benutzerdefinierte infoType-Detektoren durch leistungsstarke Kontextregeln erweitern. Eine Hotword-Regel weist Cloud DLP an, die Wahrscheinlichkeit eines Ergebnisses anzupassen, je nachdem, ob ein Hotword in der Nähe dieses Ergebnisses auftritt. Eine Hotword-Regel ist eine Art Prüfregel, die in Regelsätzen festgelegt wird. Jede Regel wird auf eine Reihe von integrierten oder benutzerdefinierten infoTypes angewendet.

Anatomie einer Hotword-Regel

Ein infoType-Detektor kann keine oder mehrere Hotword-Regeln haben. In Ihrer Inspektionskonfiguration definieren Sie jedes HotwordRule-Objekt innerhalb des Arrays rules so:

"rules":[
  {
    "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"
      },
    }
  },
  ...
]

Dabei gilt:

  • REGEX_PATTERN: ein regulärer Ausdruck (Regex-Objekt), der definiert, was als Hotword gilt.
  • NUM_CHARS_TO_CONSIDER_AFTER_FINDING: ein Zeichenbereich nach dem Ergebnis. Cloud DLP analysiert diesen Bereich, um festzustellen, ob ein Hotword in der Nähe des Ergebnisses auftritt.
  • NUM_CHARS_TO_CONSIDER_BEFORE_FINDING: ein Zeichenbereich vor dem Ergebnis. Cloud DLP analysiert diesen Bereich, um festzustellen, ob ein Hotword in der Nähe des Ergebnisses auftritt.

  • LIKELIHOOD_VALUE: eine feste Likelihood-Stufe, auf die das Ergebnis gesetzt werden soll.

  • LIKELIHOOD_ADJUSTMENT: Eine Zahl, die angibt, wie viel Cloud DLP die Wahrscheinlichkeit des Ergebnisses erhöhen oder verringern muss. Eine positive Ganzzahl erhöht die Wahrscheinlichkeitsstufe und eine negative Ganzzahl verringert sie. Beispiel: Wenn ein Ergebnis ohne die Erkennungsregel POSSIBLE wäre und relativeLikelihood 1 ist, erfolgt ein Upgrade auf LIKELY. Wenn relativeLikelihood -1 ist, wird das Ergebnis auf UNLIKELY herabgestuft. Die Wahrscheinlichkeit darf niemals unter VERY_UNLIKELY fallen oder VERY_LIKELY überschreiten. In diesen Fällen bleibt die Wahrscheinlichkeitsstufe gleich. Wenn die Basiswahrscheinlichkeit beispielsweise VERY_LIKELY ist und der relativeLikelihood 1 ist, bleibt die endgültige Wahrscheinlichkeit VERY_LIKELY.

Hotword-Beispiel: Krankenaktennummern abgleichen

Angenommen, Sie möchten einen benutzerdefinierten infoType wie eine Krankenaktennummer (Medical Record Number, MRN) im Format "###-#-#####" erkennen. Außerdem soll Cloud DLP die Übereinstimmungswahrscheinlichkeit für jedes Ergebnis, das auf das Hotword "MRN" folgt, erhöhen.

Beispielwerte:

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

Das folgende JSON-Beispiel und die Code-Snippets zeigen, wie Sie die Hotword-Regel konfigurieren. In diesem Beispiel wird ein benutzerdefinierter Detektor für reguläre Ausdrücke verwendet.

Beachten Sie in diesem Beispiel Folgendes:

  • Die Anfrage definiert den benutzerdefinierten infoType C_MRN, bei dem es sich um einen Detektor für jeden String handelt, der mit dem regulären Ausdruck [0-9]{3}-[0-9]{1}-[0-9]{5} übereinstimmt.
  • Der reguläre Ausdruck (?i)(mrn|medical)(?-i) definiert das Hotword. Cloud DLP sucht nach diesem Hotword im Feld, das im Feld proximity definiert ist.
  • Für jedes C_MRN-Ergebnis, das ein Hotword innerhalb der festgelegten proximity hat, legt Cloud DLP die Wahrscheinlichkeitsstufe auf VERY_LIKELY fest.

Protokoll

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

HTTP-Methode und URL:

POST https://dlp.googleapis.com/v2/projects/PROJECT_ID/content:inspect

Ersetzen Sie PROJECT_ID durch die Projekt-ID.

JSON-Eingabe:

{
  "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 die Krankenaktennummer mit dem benutzerdefinierten infoType-Detektor C_MRN korrekt identifiziert hat. Aufgrund des Kontextabgleichs in der Hotword-Regel hat Cloud DLP das erste Ergebnis, das eine MRN innerhalb des festgelegten proximity hatte, eine Wahrscheinlichkeit von VERY_LIKELY zugewiesen, so wie dies konfiguriert wurde. Beim zweiten Ergebnis fehlte der Kontext, daher blieb likelihood bei POSSIBLE.

Java

Informationen zum Installieren und Verwenden der Clientbibliothek für Cloud DLP finden Sie unter Cloud DLP-Clientbibliotheken.


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 unter Cloud DLP-Clientbibliotheken.

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,
        "include_quote": True,
    }

    # 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:
            print(f"Quote: {finding.quote}")
            print(f"Info type: {finding.info_type.name}")
            print(f"Likelihood: {finding.likelihood}")
    else:
        print("No findings.")

Hotword-Beispiel: Übereinstimmungswahrscheinlichkeit einer Tabellenspalte festlegen

In diesem Beispiel wird gezeigt, wie Sie die Übereinstimmungswahrscheinlichkeit einer gesamten Datenspalte festlegen können. Dieser Ansatz ist beispielsweise nützlich, wenn Sie eine Datenspalte aus Inspektionsergebnissen ausschließen möchten.

Sehen Sie sich die folgende Tabelle an. Eine Spalte enthält Platzhalter-Sozialversicherungsnummern (Social Security numbers, SSNs) und eine andere echte SSNs.

Gefälschte Sozialversicherungsnummer Echte Sozialversicherungsnummer
111-11-1111 222-22-2222

Schließen Sie alle Ergebnisse in der Spalte Fake Social Security Number aus, um falsch positive Meldungen in Inspektionsergebnissen zu minimieren. Weisen Sie dieser Spalte eine niedrige Wahrscheinlichkeitsstufe zu. Konfigurieren Sie dann die Anfrage so, dass sie mit dieser Wahrscheinlichkeitsstufe aus den Ergebnissen ausgeschlossen wird.

Beachten Sie in diesem Beispiel Folgendes:

  • Die Hotword-Regel wird auf den infoType US_SOCIAL_SECURITY_NUMBER angewendet.
  • Der reguläre Hotword-Ausdruck (Fake Social Security Number) enthält den Namen der Spalte mit den Platzhalterwerten.
  • Für jedes US_SOCIAL_SECURITY_NUMBER-Ergebnis in dieser Spalte legt Cloud DLP die Wahrscheinlichkeitsstufe auf VERY_UNLIKELY fest.
  • Das Attribut minLikelihood ist auf POSSIBLE gesetzt. Das bedeutet, dass jedes Ergebnis mit einer Wahrscheinlichkeitsstufe von unter POSSIBLE aus den Prüfergebnissen ausgeschlossen wird.

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

HTTP-Methode und URL:

POST https://dlp.googleapis.com/v2/projects/PROJECT_ID/content:inspect

Ersetzen Sie PROJECT_ID durch die Projekt-ID.

JSON-Eingabe:

{
  "item": {
    "table": {
      "headers": [
        {
          "name": "Fake Social Security Number"
        },
        {
          "name": "Real Social Security Number"
        }
      ],
      "rows": [
        {
          "values": [
            {
              "stringValue": "111-11-1111"
            },
            {
              "stringValue": "222-22-2222"
            }
          ]
        }
      ]
    }
  },
  "inspectConfig": {
    "infoTypes": [
      {
        "name": "US_SOCIAL_SECURITY_NUMBER"
      }
    ],
    "includeQuote": true,
    "ruleSet": [
      {
        "infoTypes": [
          {
            "name": "US_SOCIAL_SECURITY_NUMBER"
          }
        ],
        "rules": [
          {
            "hotwordRule": {
              "hotwordRegex": {
                "pattern": "(Fake Social Security Number)"
              },
              "likelihoodAdjustment": {
                "fixedLikelihood": "VERY_UNLIKELY"
              },
              "proximity": {
                "windowBefore": 1
              }
            }
          }
        ]
      }
    ],
    "minLikelihood": "POSSIBLE"
  }
}

JSON-Ausgabe:

{
  "result": {
    "findings": [
      {
        "quote": "222-22-2222",
        "infoType": {
          "name": "US_SOCIAL_SECURITY_NUMBER"
        },
        "likelihood": "VERY_LIKELY",
        "location": {
          "byteRange": {
            "end": "11"
          },
          "codepointRange": {
            "end": "11"
          },
          "contentLocations": [
            {
              "recordLocation": {
                "fieldId": {
                  "name": "Real Social Security Number"
                },
                "tableLocation": {}
              }
            }
          ]
        },
        "createTime": "TIMESTAMP",
        "findingId": "TIMESTAMP"
      }
    ]
  }
}

Der Wert 111-11-1111, der sich in der Spalte Fake Social Security Number befindet, entsprach der Hotword-Regel, sodass Cloud DLP ihm die Wahrscheinlichkeitsstufe VERY_UNLIKELY zugewiesen hat. Diese Stufe liegt unter der Mindestwahrscheinlichkeit, die in der Prüfungskonfiguration (POSSIBLE) festgelegt ist. Dieses Ergebnis wird daher aus dem Prüfergebnis ausgeschlossen.

Sie können mit diesem Beispiel experimentieren, indem Sie den Regelsatz entfernen. Beachten Sie, dass Cloud DLP 111-11-1111 in den Ergebnissen enthält.