일치 가능성 맞춤설정

핫워드 규칙을 사용하면 강력한 컨텍스트 규칙으로 기본 제공 및 커스텀 infoType 감지기를 더 확장할 수 있습니다. 핫워드 규칙을 사용하여 기존 infoType 감지기에 정규식 및 근접 감지기를 추가하고 일치 가능성 값을 적절히 조정할 수 있습니다. 핫워드 규칙은 규칙 세트에 지정된 검사 규칙의 한 유형입니다. 각 규칙 세트는 커스텀 또는 기본 제공 infoType 집합에 적용됩니다.

핫워드 규칙 심층 분석

infoType 감지기에는 핫워드 규칙이 없거나 여러 개일 수 있습니다. 각 핫워드 규칙(HotwordRule 객체)은 검사 규칙(InspectionRule 객체) 내에서 정의합니다. 각 검사 규칙은 InspectConfig 객체에 포함된 InspectionRuleSet 객체 내에 지정됩니다.

"inspectionRules" 배열 내의 단일 핫워드 규칙은 JSON 객체로서 그 형태는 다음과 같습니다.

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

각 핫워드 규칙에는 다음과 같은 세 가지 구성요소가 있습니다.

  • "hotwordRegex": 핫워드의 자격을 정의하는 정규식 패턴(Regex 객체)
  • "proximity": 그 안에 전체 핫워드가 포함되어야 하는 결과의 근접도. 이 필드에는 다음 두 가지 값으로 구성되는 Proximity 객체가 포함됩니다.

    • "windowBefore": 고려할 결과 앞의 문자 수
    • "windowAfter": 고려할 결과 뒤의 문자 수
  • "likelihoodAdjustment": 결과의 가능성 조정. 이 필드에는 다음 두 값 중 하나로 설정 가능한 LikelihoodAdjustment 객체가 포함됩니다.

    • "fixedLikelihood": 결과를 설정할 고정된 Likelihood
    • "relativeLikelihood": 결과의 가능성을 높이거나 낮출 수준을 나타내는 수. 예를 들어 감지 규칙이 없고 relativeLikelihood가 1인 상태에서 결과가 POSSIBLE인 경우 결과는 LIKELY로 업그레이드되며, 값이 -1이면 UNLIKELY로 다운그레이드됩니다. 가능성은 VERY_UNLIKELY 아래로 내려가거나 VERY_LIKELY를 초과할 수 없으므로 기본 가능성이 VERY_LIKELY일 때 1 조정을 적용한 다음 -1 조정을 적용하면 최종 가능성은 LIKELY가 됩니다.

핫워드 예시: 의료 레코드 번호 대조

###-#-##### 형식의 의료 레코드 번호와 같은 커스텀 infoType을 검색하고 Cloud DLP의 검색 결과 항목에서 이 번호 앞에(뒤가 아님) 핫워드 'MRN'이 있을 때 일치 가능성을 높인다고 가정해 보겠습니다. 따라서 다음과 같습니다.

  • 123-4-56789의 일치 가능성은 POSSIBLE입니다.
  • MRN 123-4-56789의 일치 가능성은 VERY_LIKELY입니다.

아래 JSON 예시 및 코드 스니펫에서는 정규식 infoType 감지기 만들기에 설명된 대로 정의된 커스텀 정규식을 보여주지만 핫워드 규칙이 추가됩니다.

프로토콜

JSON과 Cloud DLP API 사용법에 대한 자세한 내용은 JSON 빠른 시작을 참조하세요.

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

JSON 출력(축약형):

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

이 출력은 C_MRN 이름을 지정한 커스텀 infoType 감지기와 커스텀 정규식을 사용하여 Cloud DLP가 의료 레코드 번호를 올바르게 식별한 것으로 나타납니다. 또한 핫워드 규칙에 사용된 컨텍스트 일치로 인해 Cloud DLP가 구성된 VERY_LIKELY 확신도를 첫 번째 결과(MRN 바로 옆)에 할당했습니다. 두 번째 결과는 컨텍스트가 없었기 때문에 확신도가 POSSIBLE로 유지되었습니다.

자바

Cloud DLP용 클라이언트 라이브러리를 설치하고 사용하는 방법은 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

Cloud DLP용 클라이언트 라이브러리를 설치하고 사용하는 방법은 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.")