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.

    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.
    5. Click the Select a role field.

      Under Quick access, click Basic, then click Owner.

    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.

  8. 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.

Web UI

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

    Open the IAM page

  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 members dialog:

    • For Members type the user email: test@example.com.
    • For Roles, click Select a role and choose Cloud DLP > DLP User.

  5. Click Add.

Command-line

  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:test@example.com --role roles/dlp.user

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

    bindings:
    - members:
    - user:test@example.com
    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 (206) 555-0123."
      },
      "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. This is the JSON file that you downloaded 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":"(206) 555-0123",
        "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?

  • Read How-to guides to get started with inspecting text and images for sensitive data, as well as redacting sensitive data from text and images.
  • Read Concepts to better understand inspection, redaction, infoTypes, and likelihood.
  • Take a look at the API Reference.