Como personalizar a probabilidade de correspondência

As regras de hotword permitem estender ainda mais os detectores de infoType integrados e personalizados com regras de contexto avançadas. Essas regras permitem adicionar um detector de regex e de proximidade a um detector de InfoType existente e ajustar adequadamente o valor de probabilidade de correspondência. Uma regra de hotword é um tipo de regra de inspeção, que é especificada em conjuntos de regras. Cada conjunto de regras é aplicado a um conjunto de InfoTypes, que podem ser personalizados ou integrados.

Anatomia da regra de hotword

O detector de InfoType pode ter zero ou mais regras de hotword. Você define cada regra de hotword (objeto HotwordRule) dentro de uma regra de inspeção (objeto InspectionRule). Cada regra de inspeção é especificada em um objeto InspectionRuleSet, que, por sua vez, está contido em um objeto InspectConfig.

Como um objeto JSON, uma única regra de hotword dentro de uma matriz "inspectionRules" tem esta aparência:

"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 regra de hotword tem três componentes:

  • "hotwordRegex": um padrão de regex (objeto Regex) que define o que se qualifica como hotword.
  • "proximity": a proximidade da descoberta dentro da qual a hotword precisa estar contida. Este campo contém um objeto Proximity, composto de dois valores:

    • "windowBefore": número de caracteres antes da descoberta a ser considerada.
    • "windowAfter": número de caracteres depois da descoberta a ser considerada.
  • "likelihoodAdjustment": o ajuste na probabilidade de uma descoberta. Esse campo contém um objeto LikelihoodAdjustment, que pode ser definido como um dos dois valores:

    • "fixedLikelihood": um valor fixo Likelihood para o qual a descoberta será definida.
    • "relativeLikelihood": um número que indica os níveis pelos quais será aumentada ou diminuída a probabilidade da descoberta. Por exemplo, se uma descoberta fosse POSSIBLE sem a regra de detecção e relativeLikelihood for 1, seria feito upgrade dela para LIKELY, enquanto um valor de -1 faria downgrade para UNLIKELY. A probabilidade nunca pode cair abaixo de VERY_UNLIKELY ou exceder VERY_LIKELY. Portanto, aplicar um ajuste de 1 seguido por um ajuste de -1 quando a probabilidade básica for VERY_LIKELY resultará em uma probabilidade final de LIKELY.

Exemplo de hotword: correspondência com números de registros médicos

Suponha que você quisesse detectar um InfoType personalizado, como um número de registro médico no formato "###-#-#####", e quisesse aumentar a probabilidade de correspondência da descoberta do Cloud DLP quando a hotword "MRN" estivesse antes, mas não depois, desse número. Assim:

  • 123-4-56789 corresponderia a POSSIBLE;
  • MRN 123-4-56789 corresponderia a VERY_LIKELY.

O exemplo de JSON a seguir mostra o regex personalizado definido conforme explicado em Como criar um detector de InfoType regex, mas com a regra de hotword apropriada incluída em:

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

Saída JSON (abreviada):

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

A saída mostra que o Cloud DLP identificou corretamente o número do registro médico ao usar o detector de InfoType personalizado com o nome C_MRN e o regex personalizado. Além disso, devido à correspondência de contexto na regra de hotword, o Cloud DLP atribuiu ao primeiro resultado (que tinha MRN por perto) uma certeza de VERY_LIKELY, conforme configurado. A segunda descoberta não tinha o contexto, por isso a certeza permaneceu em POSSIBLE.