Quickstart: Using a JSON request

This page shows you how to perform basic tasks in the Cloud Data Loss Prevention API by making calls directly to the API.

Before you begin

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

4. Enable the DLP API.

   Enable the API

5. Create a service account:

   1. In the Cloud Console, go to the Create service account page.

      Go to Create service account
   2. Select a project.

   3. In the Service account name field, enter a name. The Cloud Console fills in the Service account ID field based on this name.

      In the Service account description field, enter a description. For example, Service account for quickstart.

   4. Click Create and continue.

   5. Click the Select a role field.

      Under Quick access, click Basic, then click Owner.

      Note: The Role field affects which resources your service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
   6. Click Continue.

   7. Click Done to finish creating the service account.

      Do not close your browser window. You will use it in the next step.

6. Create a service account key:

   1. In the Cloud Console, click the email address for the service account that you created.
   2. Click Keys.
   3. Click Add key, then click Create new key.
   4. Click Create. A JSON key file is downloaded to your computer.
   5. Click Close.

7. Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your service account key. This variable only applies to your current shell session, so if you open a new session, set the variable again.

   Example: Linux or macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your service account key.

   For example:

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   Example: Windows

   For PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your service account key.

   For example:

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   For command prompt:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   Replace KEY_PATH with the path of the JSON file that contains your service account key.

8. Install and initialize the Cloud SDK.

9. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

10. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

11. Enable the DLP API.

    Enable the API

12. Create a service account:

    1. In the Cloud Console, go to the Create service account page.

       Go to Create service account
    2. Select a project.

    3. In the Service account name field, enter a name. The Cloud Console fills in the Service account ID field based on this name.

       In the Service account description field, enter a description. For example, Service account for quickstart.

    4. Click Create and continue.

    5. Click the Select a role field.

       Under Quick access, click Basic, then click Owner.

       Note: The Role field affects which resources your service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
    6. Click Continue.

    7. Click Done to finish creating the service account.

       Do not close your browser window. You will use it in the next step.

13. Create a service account key:

    1. In the Cloud Console, click the email address for the service account that you created.
    2. Click Keys.
    3. Click Add key, then click Create new key.
    4. Click Create. A JSON key file is downloaded to your computer.
    5. Click Close.

14. Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your service account key. This variable only applies to your current shell session, so if you open a new session, set the variable again.

    Example: Linux or macOS

    export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

    Replace KEY_PATH with the path of the JSON file that contains your service account key.

    For example:

    export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

    Example: Windows

    For PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

    Replace KEY_PATH with the path of the JSON file that contains your service account key.

    For example:

    $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

    For command prompt:

    set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

    Replace KEY_PATH with the path of the JSON file that contains your service account key.

15. Install and initialize the Cloud SDK.

Permissions

Inspecting content requires the serviceusage.services.use permission for the project that's specified in parent. The roles/editor, roles/owner, and roles.dlp.user roles contain the required permission or you can define your own custom role.

To give your user the dlp.admin role at the project level, choose one of the following tabs and complete the steps.

Console

1. Open the Identity and Access Management page in the Google Cloud Console.

   Go to IAM

2. If a project hasn't already been selected, click the project selector, then select your project.

   

3. On the Identity and Access Management page, click Add.

4. In the Add principals pane, follow these steps:

   1. In the New principals field, type the user email: [e-mail].
   2. Click Select a role and choose Cloud DLP > DLP User.

5. Click Add.

gcloud

1. To add a single binding to the project's IAM policy, type the following command, replacing [PROJECT_ID] with your project ID.

   gcloud projects add-iam-policy-binding [PROJECT_ID] --member user:[e-mail] --role roles/dlp.user

2. The command writes the updated policy to the console window:

   bindings:
   - members:
   - user:[e-mail]
   role: roles/dlp.user

Inspect a string for sensitive information

This section shows you how to ask the service to scan sample text using the projects.content.inspect REST method.

1. Create a JSON request file with the following text, and save it as inspect-request.json.

   {
     "item":{
       "value":"My phone number is [phone]."
     },
     "inspectConfig":{
       "infoTypes":[
         {
           "name":"PHONE_NUMBER"
         },
         {
           "name":"US_TOLLFREE_PHONE_NUMBER"
         }
       ],
       "minLikelihood":"POSSIBLE",
       "limits":{
         "maxFindingsPerItem":0
       },
       "includeQuote":true
     }
   }

   In this JSON request, the item field contains a ContentItem object, and the inspectConfig field contains an InspectConfig object. After completing this quickstart, try adding your own string to the item, and try modifying some of the inspectConfig fields to see their effects.

2. Activate the service account:

   gcloud auth activate-service-account SERVICE_ACCOUNT \
      --key-file=PATH_TO_SERVICE_ACCOUNT_KEY \
      --project=PROJECT_ID

   Replace the following:

   • SERVICE_ACCOUNT: the ID of your service account.
   • PATH_TO_SERVICE_ACCOUNT_KEY: the path to the JSON file containing your service account's private key. You downloaded this JSON file when you set up authentication in the Before you begin section.
   • PROJECT_ID: the project that you set up to use Cloud DLP.

3. Obtain an authorization token:

   gcloud auth print-access-token

4. Use curl to make a content:inspect request, passing it the access token you printed and the filename of the JSON request you set up in step 1:

   curl -s \
   -H "Authorization: Bearer ACCESS_TOKEN" \
   -H "Content-Type: application/json" \
   https://dlp.googleapis.com/v2/projects/[PROJECT_ID]/content:inspect \
   -d @inspect-request.json

   To pass a filename to curl, you use the -d option (for "data") and precede the filename with an @ sign. This file must be in the same directory where you execute the curl command.

Cloud DLP responds to your request with the following JSON:

{
  "result":{
    "findings":[
      {
        "quote":"[phone]",
        "infoType":{
          "name":"PHONE_NUMBER"
        },
        "likelihood":"LIKELY",
        "location":{
          "byteRange":{
            "start":"19",
            "end":"33"
          },
          "codepointRange":{
            "start":"19",
            "end":"33"
          }
        },
        "createTime":"2018-11-30T01:01:30.883Z"
      }
    ]
  }
}

Congratulations! You've sent your first request to Cloud DLP!

What's next

• Work through How-to guides to get started with inspecting text and images for sensitive data, as well as redacting sensitive data from text and images.
• Learn about concepts to better understand inspection, redaction, infoTypes, and likelihood.
• Refer to the API Reference.