Set up API access

Here's how to set up access to the Data Manager API with an SDK or REST.

Prerequisites

Before you can use the Data API, make sure you have the following:

  1. A Google Cloud project.
  2. A Google Account that meets both of the following criteria:
    1. Has been granted access to the Data Manager API, after you filled out the Data Manager API Interest Form. If you can see the API product details page, you have access.
    2. Has the serviceusage.services.enable permission on your Google Cloud project, or has a role that includes that permission. For example, roles/owner and roles/serviceusage.serviceUsageAdmin both include the serviceusage.services.enable permission. To check your permissions, see View current access.

Enable the API

If you haven't already, enable the Data Manager API.

If you can't find the Data Manager API, verify your Google Account meets the prerequisites.

Set up authentication

Select and set up an authentication method. We recommend that you Set up Application Default Credentials to automatically find credentials from the environment. This API doesn't use API keys.

The scope https://www.googleapis.com/auth/datamanager is required for any credential used with the Data Manager API. For an example of how to use scopes, see the documentation for the gcloud auth application-default login command.

To learn more about authentication and credentials for your app, see Authentication methods at Google and How Application Default Credentials works.

Set up operating account access

Grant the email associated with your user or service account access to the Destination.

Set up the SDK for your programming language

On your local machine, install the SDK of your choice:

REST

  1. Update the placeholders in the following sample, such as OPERATING_ACCOUNT_PRODUCT, OPERATING_ACCOUNT_ID, and AUDIENCE_ID, with the values for your account and destination.
  2. Replace PROJECT_ID with the ID of your Google Cloud.
  3. Copy the sample to the command line to send the request.

    Remove the linkedAccount attribute of the entry in the destinations if you aren't accessing the operationAccount using an established product link.

    #!/bin/bash
    
    # Uses gcloud to get an access token.
    DATA_MANAGER_ACCESS_TOKEN="$(gcloud auth application-default print-access-token --scopes=https://www.googleapis.com/auth/datamanager)"
    
    # Sends the request.
    curl -X POST "https://datamanager.googleapis.com/v1/audienceMembers:ingest" \
      --header "Authorization: Bearer ${DATA_MANAGER_ACCESS_TOKEN}" \
      --header "x-goog-user-project: PROJECT_ID" \
      --header "Content-Type: application/json" \
      --data @- <<EOF
    {
      "destinations": [
        {
          "operatingAccount": {
            "product": "OPERATING_ACCOUNT_PRODUCT",
            "accountId": "OPERATING_ACCOUNT_ID"
          },
          "loginAccount": {
            "product": "LOGIN_ACCOUNT_PRODUCT",
            "accountId": "LOGIN_ACCOUNT_ID"
          },
          "linkedAccount": {
            "product": "LINKED_ACCOUNT_PRODUCT",
            "accountId": "LINKED_ACCOUNT_ID"
          },
          "productDestinationId": "AUDIENCE_ID"
        }
      ],
      "audienceMembers": [
        {
          "userData": {
            "userIdentifiers": [
              {
                "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
              },
              {
                "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
              }
            ]
          }
        },
        {
          "userData": {
            "userIdentifiers": [
              {
                "emailAddress": "2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3"
              },
              {
                "emailAddress": "54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51"
              },
              {
                "emailAddress": "e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478"
              }
            ]
          }
        },
        {
          "userData": {
            "userIdentifiers": [
              {
                "emailAddress": "05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0"
              },
              {
                "emailAddress": "f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5"
              }
            ]
          }
        },
        {
          "userData": {
            "userIdentifiers": [
              {
                "emailAddress": "83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f"
              },
              {
                "emailAddress": "223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4"
              }
            ]
          }
        }
      ],
      "consent": {
        "adUserData": "CONSENT_GRANTED",
        "adPersonalization": "CONSENT_GRANTED"
      },
      "encoding": "HEX",
      "termsOfService": {
        "customerMatchTermsOfServiceStatus": "ACCEPTED"
      },
      "validateOnly": true
    }
    EOF
    

Java

  1. Download and extract google-cloud-ads-datamanager-v1-java.tar.gz.
  2. Navigate to the google-cloud-ads-datamanager-v1-java directory.
  3. Run the following command to build and publish the library to your local Maven repository for use with Maven or Gradle.

    ./gradlew -Pversion=0.1.0 install
    
  4. In your Java project, declare a dependency on the Data Manager API library.

    Gradle:

    implementation 'com.google.cloud:gapic-google-cloud-ads-datamanager-v1-java:0.1.0'
    

    Maven:

    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>gapic-google-cloud-ads-datamanager-v1-java</artifactId>
      <version>0.1.0</version>
    </dependency>
    
  5. Optional. Get the utility library and code samples.

    1. Download and extract data-manager-java.tar.gz.
    2. Navigate to the data-manager-java directory.
    3. For Maven or Gradle, run the following command. This command builds and publishes the utility library to your local Maven repository.

      ./gradlew data-manager-util:install
      
    4. In your Java project, declare a dependency on the utility library.

      Gradle:

      implementation 'com.google.api-ads:data-manager-util:0.1.0'
      

      Maven:

      <dependency>
         <groupId>com.google.api-ads</groupId>
         <artifactId>data-manager-util</artifactId>
         <version>0.1.0</version>
      </dependency>
      
    5. To format and encrypt the data, use the UserDataFormatter and Encrypter utilities in your Java project.

    6. Browse code samples in the data-manager-samples subdirectory. To run a sample from the command line, use the Gradle run task.

      For example, the following command runs the IngestAudienceMembers sample and prints a usage statement:

      ./gradlew data-manager-samples:run \
        --args='IngestAudienceMembers --help'
      

      To help you get started with some sample data, use the file at data-manager-samples/src/main/resources/sampledata/audience_members_1.csv.

Python

  1. Download ads-datamanager-v1-py.tar.gz.
  2. Navigate to the directory of the download.
  3. Run the following command to build the library and make it available to other projects in the same Python environment:

    pip install ./ads-datamanager-v1-py.tar.gz
    
  4. In your Python project, declare a dependency on the Data Manager API library. For example, if using a requirements.txt file in your project, add the following line to the file:

    google-ads-data-manager=0.1.0
    
  5. Optional. Get the utility library and code samples.

    1. Download and extract data-manager-python.tar.gz.
    2. Navigate to the data-manager-python directory.
    3. To install the utility library in your Python environment, run the following command:

      pip install .
      
    4. In your Python project, declare a dependency on the utility library. For example, if using a requirements.txt file in your project, add the following line to the file:

      google-ads-data-manager-util=0.1.0
      
    5. To format and encrypt the data, use the Formatter and Encrypter utilities in your Python project.

    6. Browse code samples in the samples subdirectory. Pass the --help argument when running a sample to print a usage statement with expected parameters.

      To help you get started with some sample data, use the file at samples/sampledata/audience_members_1.csv.

Node.js

  1. Download and extract ads-datamanager-v1-nodejs.tar.gz.
  2. Navigate to the ads-datamanager-v1-nodejs directory.
  3. Run the following commands to compile and pack the library into a .tgz file for use with npm.

    npm install
    npm pack
    

    The commands generate an archive named google-cloud-datamanager-0.1.0.tgz.

  4. In your Node.js project, declare a dependency on the Data Manager API library by adding a dependencies entry for the full path and filename of the google-cloud-datamanager-0.1.0.tgz file.

PHP

  1. Download and extract google-cloud-ads-datamanager-v1-php.tar.gz.
  2. Navigate to the google-cloud-ads-datamanager-v1-php directory.
  3. Run the following command to resolve dependencies for the library:

    composer update --prefer-dist
    
  4. In the composer.json file of your PHP project on the same host, declare a dependency on the Data Manager API library using the following steps:

    1. Add a repositories section that points to the location of the google-cloud-ads-datamanager-v1-php directory.

      "repositories" : [
         {
            "type" : "path",
            "url" : "PATH_TO_CLIENT_LIBRARY"
         }
      ]
      
    2. Declare a dependency on the Data Manager API library.

      "require": {
         "googleads/data-manager": "^0.1.0"
      }
      
  5. (Optional) Get the utility library and code samples.

    1. Download and extract data-manager-php.tar.gz.
    2. Navigate to the data-manager-php directory.
    3. Run the following command to resolve dependencies for the library:

      composer update --prefer-dist
      
    4. In the composer.json file of your PHP project on the same host, declare a dependency on the utility library using the following steps:

      1. Add an entry in the repositories section that points to the location of the data-manager-php directory.

        "repositories" : [
           {
              "type" : "path",
              "url" : "PATH_TO_UTILITY_LIBRARY"
           }
        ]
        
      2. Declare a dependency on the utility library.

        "require": {
           "googleads/data-manager-util": "@dev"
        }
        

      To format data, use the Formatter utility in your PHP project.

    5. Browse code samples in the samples subdirectory. Run the samples using the following steps:

      1. Navigate to the samples directory.

      2. Set the DATA_MANAGER_PHP_LIB environment variable to the path where you extracted the client library.

        export DATA_MANAGER_PHP_LIB="PATH_TO_CLIENT_LIBRARY"
        
      3. Run the following command to resolve dependencies for the library:

        composer update --prefer-dist
        
      4. Run the samples, passing any required arguments. Pass the --help argument when running a sample to print a usage statement with expected parameters.

      To help you get started with some sample data, use the file at samples/sampledata/audience_members_1.csv.