Specifying processing locations
With the ability to specify a region in which to perform your Sensitive Data Protection operations, you can control where your potentially sensitive data is processed. This document explains the concept of Sensitive Data Protection processing location and shows you how to specify a region.
To see a list of supported regions and multi-regions, see Sensitive Data Protection locations.
About regions and multi-regions
A region is a specific geographic place, such as the western United States or northeast Asia. A multi-region location (or just multi-region) is a large geographic area, such as the European Union, that contains two or more geographic regions.
Location considerations
A good location balances latency, availability, and bandwidth costs.
Use a region to help optimize latency and network bandwidth.
Use a multi-region when you want to process data from outside of the Google network and distributed across large geographic areas, or when you want the higher availability that comes with being redundant across regions.
Generally, you should process your data in a location that is convenient or contains the majority of the users of your data.
If your organization is required to keep in-transit data within a specified location, then use only the regions or multi-regions that support regional endpoints (REP). In this case, you need to use the Cloud Data Loss Prevention API, because the regional endpoints for Sensitive Data Protection aren't available for use with the Google Cloud console.
Specify a region
How you specify the processing region depends on the type of endpoint you are sending the request to—the global endpoint or a regional endpoint. The type of endpoint you choose depends on whether you're required to keep in-transit data within a specified region. For more information, see Global and regional endpoints for Sensitive Data Protection.
Specify a region in a request to the global endpoint
Console
Choose a region when setting up your Sensitive Data Protection operation.
For example, when creating a job trigger, choose a location from the Resource location menu, as shown here:
If the processing location is not a concern, use the Global region and Google chooses the location where processing should take place. Global is the default region choice.
REST
Insert region information into the request endpoint URL. If the processing location is
not a concern, use the global region and Google chooses the location where
processing should take place. Note that any resources created by a request that
specifies the global region are stored under the global region.
The following are some example requests to the global endpoint.
Using the global region
The following two requests have the same effect. Not including a region is the
same as specifying locations/global/.
POST https://www.googleapis.com/dlp/v2/projects/PROJECT_ID/locations/global/content:inspect
POST https://www.googleapis.com/dlp/v2/projects/PROJECT_ID/content:inspect
Using a specific region
To specify a region for processing, within the resource URL, insert
locations/ and then the region name.
POST https://www.googleapis.com/dlp/v2/projects/PROJECT_ID/locations/us-west2/content:inspect
Specify a region in a request to a regional endpoint
Console
For Sensitive Data Protection, regional endpoints aren't available for use with the Google Cloud console.
C#
To learn how to install and use the client library for Sensitive Data Protection, see Sensitive Data Protection client libraries.
To authenticate to Sensitive Data Protection, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
usingSystem;
usingSystem.Collections.Generic;
usingSystem.Linq;
usingGoogle.Api.Gax.ResourceNames ;
usingGoogle.Cloud.Dlp.V2 ;
usingstaticGoogle.Cloud.Dlp.V2.InspectConfig.Types;
publicclassInspectStringRep
{
publicstaticInspectContentResponseInspect(
stringprojectId,
stringrepLocation,
stringdataValue,
stringminLikelihood,
intmaxFindings,
boolincludeQuote,
IEnumerable<InfoType>infoTypes,
IEnumerable<CustomInfoType>customInfoTypes)
{
varinspectConfig=newInspectConfig
{
MinLikelihood=(Likelihood )Enum.Parse(typeof(Likelihood ),minLikelihood,true),
Limits=newFindingLimits
{
MaxFindingsPerRequest=maxFindings
},
IncludeQuote=includeQuote,
InfoTypes={infoTypes},
CustomInfoTypes={customInfoTypes}
};
varrequest=newInspectContentRequest
{
Parent=newLocationName (projectId,repLocation).ToString(),
Item=newContentItem
{
Value=dataValue
},
InspectConfig=inspectConfig
};
vardlp=newDlpServiceClientBuilder
{
Endpoint=$"dlp.{repLocation}.rep.googleapis.com"
}.Build ();
varresponse=dlp.InspectContent(request);
PrintResponse(includeQuote,response);
returnresponse;
}
privatestaticvoidPrintResponse(boolincludeQuote,InspectContentResponse response)
{
varfindings=response.Result .Findings;
if(findings.Any())
{
Console.WriteLine("Findings:");
foreach(varfindinginfindings)
{
if(includeQuote)
{
Console.WriteLine($" Quote: {finding.Quote}");
}
Console.WriteLine($" InfoType: {finding.InfoType}");
Console.WriteLine($" Likelihood: {finding.Likelihood}");
}
}
else
{
Console.WriteLine("No findings.");
}
}
}Go
To learn how to install and use the client library for Sensitive Data Protection, see Sensitive Data Protection client libraries.
To authenticate to Sensitive Data Protection, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
import(
"context"
"fmt"
"io"
dlp"cloud.google.com/go/dlp/apiv2"
"cloud.google.com/go/dlp/apiv2/dlppb"
"google.golang.org/api/option"
)
// inspectString inspects the a given string, and prints results.
funcinspectStringRep(wio.Writer,projectID,repLocation,textToInspectstring)error{
// projectID := "my-project-id"
// textToInspect := "My name is Gary and my email is gary@example.com"
ctx:=context.Background()
// Assemble the regional endpoint url using provided rep location
repEndpoint:=fmt.Sprintf("dlp.%s.rep.googleapis.com:443",repLocation)
// Initialize client.
client,err:=dlp.NewClient (ctx,option.WithEndpoint(repEndpoint))
iferr!=nil{
returnerr
}
deferclient.Close ()// Closing the client safely cleans up background resources.
// Create and send the request.
req:=&dlppb.InspectContentRequest{
Parent:fmt.Sprintf("projects/%s/locations/%s",projectID,repLocation),
Item:&dlppb.ContentItem{
DataItem:&dlppb.ContentItem_Value{
Value:textToInspect,
},
},
InspectConfig:&dlppb.InspectConfig{
InfoTypes:[]*dlppb.InfoType{
{Name:"PHONE_NUMBER"},
{Name:"EMAIL_ADDRESS"},
{Name:"CREDIT_CARD_NUMBER"},
},
IncludeQuote:true,
},
}
resp,err:=client.InspectContent(ctx,req)
iferr!=nil{
returnerr
}
// Process the results.
result:=resp.Result
fmt.Fprintf(w,"Findings: %d\n",len(result.Findings))
for_,f:=rangeresult.Findings{
fmt.Fprintf(w,"\tQuote: %s\n",f.Quote)
fmt.Fprintf(w,"\tInfo type: %s\n",f.InfoType.Name)
fmt.Fprintf(w,"\tLikelihood: %s\n",f.Likelihood)
}
returnnil
}
Java
To learn how to install and use the client library for Sensitive Data Protection, see Sensitive Data Protection client libraries.
To authenticate to Sensitive Data Protection, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
importcom.google.cloud.dlp.v2.DlpServiceClient ;
importcom.google.cloud.dlp.v2.DlpServiceSettings ;
importcom.google.privacy.dlp.v2.ByteContentItem ;
importcom.google.privacy.dlp.v2.ByteContentItem.BytesType ;
importcom.google.privacy.dlp.v2.ContentItem ;
importcom.google.privacy.dlp.v2.Finding ;
importcom.google.privacy.dlp.v2.InfoType ;
importcom.google.privacy.dlp.v2.InspectConfig ;
importcom.google.privacy.dlp.v2.InspectContentRequest ;
importcom.google.privacy.dlp.v2.InspectContentResponse ;
importcom.google.privacy.dlp.v2.LocationName ;
importcom.google.protobuf.ByteString ;
importjava.io.IOException;
importjava.util.ArrayList;
importjava.util.List;
publicclass InspectStringRep{
publicstaticvoidmain(String[]args)throwsException{
// TODO(developer): Replace these variables before running the sample.
StringprojectId="your-project-id";
StringrepLocation="regional-endpoint-location-to-use";
StringtextToInspect="My name is Gary and my email is gary@example.com";
inspectString(projectId,repLocation,textToInspect);
}
// Inspects the provided text.
publicstaticvoidinspectString(StringprojectId,StringrepLocation,StringtextToInspect)
throwsIOException{
// Assemble the regional endpoint url using provided rep location
StringrepEndpoint=String.format("dlp.%s.rep.googleapis.com:443",repLocation);
DlpServiceSettings settings=DlpServiceSettings .newBuilder()
.setEndpoint(repEndpoint)
.build();
// 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(settings)){
// 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 type of info the inspection will look for.
List<InfoType>infoTypes=newArrayList<>();
// See https://cloud.google.com/dlp/docs/infotypes-reference for complete list of info types
for(StringtypeName:newString[]{"PHONE_NUMBER","EMAIL_ADDRESS","CREDIT_CARD_NUMBER"}){
infoTypes.add(InfoType .newBuilder().setName(typeName).build());
}
// Construct the configuration for the Inspect request.
InspectConfig config=
InspectConfig .newBuilder().addAllInfoTypes(infoTypes).setIncludeQuote (true).build();
// Construct the Inspect request to be sent by the client.
InspectContentRequest request=
InspectContentRequest .newBuilder()
.setParent(LocationName .of(projectId,repLocation).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());
}
}
}
}REST
The following example sends a content.inspect request to a regional endpoint.
Any data attached to this request remains in the specified region while in
transit, in use, and at rest.
Before using any of the request data, make the following replacements:
-
REP_REGION: a region where a regional endpoint (REP) for Sensitive Data Protection is available—for example,us-west2. For a full list of regions, see Sensitive Data Protection locations. -
PROJECT_ID: your Google Cloud project ID. Project IDs are alphanumeric strings, likeexample-project.
HTTP method and URL:
POST https://dlp.REP_REGION.rep.googleapis.com/v2/projects/PROJECT_ID/locations/REP_REGION/content:inspect
Request JSON body:
{
"inspectConfig": {
"infoTypes": [
{
"name": "CREDIT_CARD_NUMBER"
}
]
},
"item": {
"value": "hi, my ccn is 4111111111111111"
}
}
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
Save the request body in a file named inspect-request.json,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "x-goog-user-project: PROJECT_ID" \
-H "Content-Type: application/json; charset=utf-8" \
-d @inspect-request.json \
"https://dlp.REP_REGION.rep.googleapis.com/v2/projects/PROJECT_ID/locations/REP_REGION/content:inspect"
PowerShell (Windows)
Save the request body in a file named inspect-request.json,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile inspect-request.json `
-Uri "https://dlp.REP_REGION.rep.googleapis.com/v2/projects/PROJECT_ID/locations/REP_REGION/content:inspect" | Select-Object -Expand Content
You should receive a JSON response similar to the following:
{
"result": {
"findings": [
{
"infoType": {
"name": "CREDIT_CARD_NUMBER",
"sensitivityScore": {
"score": "SENSITIVITY_HIGH"
}
},
"likelihood": "LIKELY",
"location": {
"byteRange": {
"start": "14",
"end": "30"
},
"codepointRange": {
"start": "14",
"end": "30"
}
},
"createTime": "2024-08-09T19:54:13.348Z",
"findingId": "2024-08-09T19:54:13.352163Z4747901452516738787"
}
]
}
}Co-location considerations
When you scan a storage repository such as Cloud Storage or
BigQuery, you should specify the same location in your
Sensitive Data Protection request as the location of the repository you're
scanning. For example, if the BigQuery dataset is in the European
Union multi-region location, specify the European Union multi-region (europe)
when configuring the Sensitive Data Protection job.
If you do not co-locate your Sensitive Data Protection request with the storage repository you're scanning, processing of your request may be split between the location of the data and the location specified in the request.
What's next
- Learn more about geography and zones.
- See a list of supported regions and multi-regions.
- Learn more about Global and regional endpoints for Sensitive Data Protection.