Configuration

There are multiple different ways to configure the client.

Configuration using YAML file

You can specify a YAML file to use when initializing the client that contains the necessary authentication information needed to make requests. This file is accessed when a client is initialized using the load_from_storage method. The easiest way to generate this file is to copy the google-ads.yaml example from the GitHub repository and modify it to include your credentials, including your developer token, refresh token, client ID, and client secret.

If you don't provide a path, the library will look in your $HOME directory for the file:

from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

To specify a location where the google-ads.yaml file is located, you can pass the path as a string to the method when calling it:

from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

You can also specify the path by defining a specific environment variable:

import os

os.environ["GOOGLE_ADS_CONFIGURATION_FILE_PATH"] = "path/to/google-ads.yaml"
from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

If both values are provided—a path is passed into the method and the above environment variable is present—then the library will prioritize the path passed into the method.

Configuration using environment variables

You can store all of your client configuration as environment variables, which will be read when using the client's load_from_env method. Environment variables should have the same name as those defined in the google-ads.yaml file, but should be all uppercase and prefixed with the GOOGLE_ADS_ namespace. For example client_id should be stored as GOOGLE_ADS_CLIENT_ID.

Environment variables are commonly defined in a bash configuration file such as a .bashrc or .bash_profile file located in the $HOME directory. They can also be defined using the command line. Note that these instructions assume you're using bash, if you're using a different shell you may need to consult documentation on how to set environment variables in the shell you're using.

Here are some basic steps to define an environment variable using a .bashrc file using a terminal:

# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
$ echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc
# Update your bash environment to use the most recently updated
# version of your .bashrc file.
$ src ~/.bashrc

Environment variables can also be set in your terminal instance directly from the command line:

$ export GOOGLE_ADS_CLIENT_ID=1234567890
$ echo $GOOGLE_ADS_CLIENT_ID
1234567890

The load_from_env method loads configuration data from the environ attribute on Python's built-in os module. For example: os.environ["GOOGLE_ADS_CLIENT_ID"]

Here's an example of how to initialize a client instance with configuration from environment variables:

from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()

In order to configure logging through environment variables, the configuration value must be a JSON object that matches the structure of the YAML keys in the sample google-ads.yaml configuration file.

Here's an example of how this could be set using a .bashrc file:

export GOOGLE_ADS_LOGGING='{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "default_fmt": {
      "format": "[%(asctime)s - %(levelname)s] %(message).5000s",
      "datefmt": "%Y-%m-%d %H:%M:%S"
    }
  },
  "handlers": {
    "default_handler": {
      "class": "logging.StreamHandler",
      "formatter": "default_fmt"
    }
  },
  "loggers": {
    "": {
      "handlers": ["default_handler"],
      "level": "INFO"
    }
  }
}'

Configuration using a YAML string

If you have read a YAML file into memory you can provide it directly to the client on initialization. To do this just use the load_from_string method.

from google.ads.googleads.client import GoogleAdsClient

with open("/path/to/yaml", "rb") as handle:
    yaml = handle.read()

client = GoogleAdsClient.load_from_string(yaml)

Configuration using a dict

You can pass a dict directly to the load_from_dict method. For example:

from google.ads.googleads.client import GoogleAdsClient

credentials = {
    "developer_token": "abcdef123456",
    "refresh_token": "1//0abcdefghijklABCDEF",
    "client_id": "123456-abcdef.apps.googleusercontent.com",
    "client_secret": "aBcDeFgHiJkL"}

client = GoogleAdsClient.load_from_dict(credentials)

Configuration Fields

The client library configuration supports the following fields.

General fields (these names are the same whether you're using a YAML or dict configuration):

  • refresh_token: Your OAuth refresh token.
  • client_id: Your OAuth client ID.
  • client_secret: Your OAuth client secret.
  • developer_token: Your developer token for accessing the API.
  • login_customer_id: See the login-customer-id documentation.
  • linked_customer_id: See the linked-customer-id documentation.
  • json_key_file_path (formerly path_to_private_key_file): A path to a local private key file. This is used for authenticating using a service account. See the OAuth2 Service Account documentation.
  • impersonated_email (formerly delegate_account): An account email used as a delegate. This is used for authenticating using a service account. See the OAuth2 Service Account documentation.
  • logging: Logging configuration. Logging fields are described below.
  • http_proxy: See the Proxy documentation.
  • use_proto_plus: Whether or not to use proto-plus messages. See the Protobuf messages documentation.

General fields as environment variables:

  • GOOGLE_ADS_CONFIGURATION_FILE_PATH
  • GOOGLE_ADS_REFRESH_TOKEN
  • GOOGLE_ADS_CLIENT_ID
  • GOOGLE_ADS_CLIENT_SECRET
  • GOOGLE_ADS_DEVELOPER_TOKEN
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID
  • GOOGLE_ADS_LINKED_CUSTOMER_ID
  • GOOGLE_ADS_JSON_KEY_FILE_PATH (formerly GOOGLE_ADS_PATH_TO_PRIVATE_KEY_FILE)
  • GOOGLE_ADS_IMPERSONATED_EMAIL (formerly GOOGLE_ADS_DELEGATE_ACCOUNT)
  • GOOGLE_ADS_LOGGING
  • GOOGLE_ADS_HTTP_PROXY
  • GOOGLE_ADS_USE_PROTO_PLUS

Logging fields, which are fields underneath the logging configuration field, are derived directly from the logging.config built-in module because the library will pass all fields under the logging namespace directly to the logging.config.dictConfig method. See the logging guide for complete details.

  • version: An integer value representing a schema version.
  • disable_existing_loggers: Whether loggers configured elsewhere in the application should be disabled.
  • formatters: Dictionaries defining different kinds of formatters.
  • handlers: Dictionaries defining different handlers, which control where logs are written to and which formatters should be used.
  • loggers: Dictionaries defining different types of loggers, which include a handler and a log level.