Personaliza la probabilidad de coincidencia

Las reglas de palabra clave permiten ampliar aún más los detectores de infotipo integrados o personalizados con reglas de contexto avanzadas. Las reglas de palabra clave te permiten agregar una regex y un detector de proximidad a un detector de Infotipo existente y definir el valor de probabilidad de coincidencia de manera adecuada. Una regla de palabra clave es un tipo de regla de inspección que se especifica en conjuntos de reglas. Cada conjunto de reglas se aplica a un conjunto de Infotipos, que pueden ser personalizados o integrados.

Anatomía de una regla de palabra clave

Un detector de Infotipo puede tener cero o más reglas de palabra clave. Tú defines cada regla de palabra clave (objeto HotwordRule) dentro de una regla de inspección (objeto InspectionRule). Cada regla de inspección se especifica dentro de un objeto InspectionRuleSet, que a su vez está contenido en un objeto InspectConfig.

Como objeto JSON, una sola regla de palabra clave dentro de un arreglo "inspectionRules" se ve de la siguiente manera:

"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]"
      },
    }
  },
  ...
]

Cada regla de palabra clave consta de tres componentes:

  • "hotwordRegex": un patrón de regex (objeto Regex) que define lo que califica como palabra clave
  • "proximity": la proximidad del resultado dentro del cual se debe contener toda la palabra clave. Este campo contiene un objeto Proximity, que consta de dos valores:

    • "windowBefore": la cantidad de caracteres antes del resultado que se debe considerar
    • "windowAfter": la cantidad de caracteres después del resultado que se debe considerar
  • "likelihoodAdjustment": el ajuste de la probabilidad de un resultado. Este campo contiene un objeto LikelihoodAdjustment, que se puede configurar como uno de dos valores:

    • "fixedLikelihood": un valor Likelihood fijo para configurar el resultado.
    • "relativeLikelihood": un número que indica los niveles para aumentar o disminuir la probabilidad del resultado. Por ejemplo, si un resultado sería POSSIBLE sin la regla de detección y relativeLikelihood es 1, entonces se actualiza a LIKELY, mientras que un valor de -1 lo cambia a un valor menor: UNLIKELY. La probabilidad nunca puede ser inferior a VERY_UNLIKELY o superior a VERY_LIKELY, por lo que aplicar un ajuste de 1 seguido de un ajuste de -1 cuando la probabilidad base es VERY_LIKELY dará como resultado una probabilidad final de LIKELY.

Ejemplo de palabra clave: coincidencia de los números de historias clínicas

Supongamos que deseas detectar un Infotipo personalizado, como un número de registro médico con el formato “###-#-#####”, y quieres aumentar la probabilidad de encontrar coincidencias de Cloud DLP cuando la palabra clave “MRN” era antes, pero no después, este número. Por lo tanto, esto es lo que ocurre:

  • 123-4-56789 coincidiría con POSSIBLE.
  • MRN 123-4-56789 coincidiría con VERY_LIKELY.

En los fragmentos de código y ejemplo de JSON a continuación, se muestra la regex personalizada definida como se explica en Crea un detector de infotipo de regex, pero con la regla de palabra clave adecuada que se agrega en:

Protocolo

Para obtener más información sobre el uso de la API de Cloud DLP con JSON, consulta la guía de inicio rápido de JSON.

Entrada de JSON:

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
              }
            }
          }
        ]
      }
    ]
  }
}

Resultado de JSON (abreviado):

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

El resultado muestra que con el uso del detector de infotipo personalizado le dimos el nombre C_MRN y la regex personalizada, y que Cloud DLP identificó de forma correcta el número de historia clínica. Además, debido a la coincidencia de contexto en la regla de palabra clave, Cloud DLP asignó al primer resultado (que tenía un valor MRN cercano) una certeza de VERY_LIKELY, como se configuró. El segundo resultado no tenía el contexto, por lo que la certeza permaneció en POSSIBLE.

Java

Si deseas obtener información para instalar y usar la biblioteca cliente de Cloud DLP, consulta las Bibliotecas cliente de Cloud DLP.


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

Si deseas obtener información para instalar y usar la biblioteca cliente de Cloud DLP, consulta las Bibliotecas cliente de Cloud DLP.

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.")