Configurazione

Puoi configurare la libreria client Python utilizzando un file YAML, variabili di ambiente, una stringa YAML o un dict.

Configurazione autenticazione

Esistono diversi modi per gestire le credenziali OAuth necessarie per accedere all'API Google Ads. L'approccio scelto influisce sui campi di configurazione utilizzati. Per saperne di più, consulta la guida all'autenticazione.

Configurazione tramite file YAML

Puoi specificare un file YAML da utilizzare durante l'inizializzazione del client che contiene le informazioni necessarie per effettuare richieste all'API Google Ads. Si accede a questo file quando un client viene inizializzato utilizzando il metodo load_from_storage. Il modo più semplice per generare questo file è copiare l'esempio google-ads.yaml dal repository GitHub e modificarlo in modo da includere le tue credenziali, tra cui il token di aggiornamento, l'ID client e il client secret.

Se non fornisci un percorso, la libreria cerca il file nella directory $HOME:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

Per specificare una posizione in cui si trova il file google-ads.yaml, puoi passare il percorso come stringa al metodo quando lo chiami:

from google.ads.googleads.client import GoogleAdsClient

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

Puoi anche specificare il percorso definendo una variabile di ambiente specifica:

import os
from google.ads.googleads.client import GoogleAdsClient

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

Se vengono forniti entrambi i valori, ovvero un percorso viene passato al metodo e la variabile di ambiente è presente, la libreria assegna la priorità al percorso passato al metodo.

Configurazione tramite variabili di ambiente

Puoi memorizzare tutta la configurazione del client come variabili di ambiente, che vengono lette quando utilizzi il metodo load_from_env del client. Le variabili di ambiente devono avere lo stesso nome di quelle definite nel file google-ads.yaml, ma devono essere tutte in maiuscolo e avere come prefisso lo spazio dei nomi GOOGLE_ADS_. Ad esempio, client_id deve essere memorizzato come GOOGLE_ADS_CLIENT_ID.

Le variabili di ambiente vengono comunemente definite in un file di configurazione Bash, ad esempio un file .bashrc o .bash_profile che si trova nella directory $HOME. Possono essere definiti anche utilizzando la riga di comando.

Ecco alcuni passaggi di base per definire una variabile di ambiente utilizzando un file .bashrc in un terminale:

# 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.
source ~/.bashrc

Le variabili di ambiente possono essere impostate anche nell'istanza del terminale direttamente dalla riga di comando:

export GOOGLE_ADS_CLIENT_ID=1234567890
echo $GOOGLE_ADS_CLIENT_ID

Il metodo load_from_env carica i dati di configurazione dall'attributo environ nel modulo os integrato di Python. Ad esempio: os.environ["GOOGLE_ADS_CLIENT_ID"]

Ecco un esempio di come inizializzare un'istanza client con la configurazione delle variabili di ambiente:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

Per configurare logging tramite variabili di ambiente, il valore di configurazione deve essere un oggetto JSON che corrisponda alla struttura delle chiavi YAML nel file di configurazione di esempio google-ads.yaml.

Ecco un esempio di come potrebbe essere impostato utilizzando un file .bashrc:

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"
    }
  }
}'

Punto chiave: se la variabile di ambiente GOOGLE_ADS_CONFIGURATION_FILE_PATH è impostata quando viene chiamato il metodo load_from_env, i valori di configurazione vengono recuperati dal file google-ads.yaml che si trova nel percorso specificato, non dalle variabili di ambiente descritte in precedenza.

Configurazione tramite una stringa YAML

Se hai letto un file YAML in memoria, puoi fornirlo direttamente al client durante l'inizializzazione. Per farlo, utilizza il metodo load_from_string:

from google.ads.googleads.client import GoogleAdsClient

with open("/path/to/yaml", "r", encoding="utf-8") as handle:
    yaml_content = handle.read()

client = GoogleAdsClient.load_from_string(yaml_content)

Configurazione tramite un dict

Puoi passare un dict direttamente al metodo load_from_dict. Ad esempio:

from google.ads.googleads.client import GoogleAdsClient

credentials = {
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "use_proto_plus": True,
}

client = GoogleAdsClient.load_from_dict(credentials)

Campi di configurazione

La configurazione della libreria client supporta i seguenti campi.

Autenticazione

Utilizza solo uno di questi gruppi di campi, a seconda dell'approccio di autenticazione che stai utilizzando:

  • Utente singolo con credenziali predefinite dell'applicazione (documentazione)
    • use_application_default_credentials: indica se la libreria deve utilizzare le credenziali predefinite dell'applicazione (ADC) per l'autenticazione (supportate in google-ads v28.3.0 e versioni successive).
  • Utente singolo con token OAuth (documentazione)
    • client_id: il tuo ID client OAuth.
    • client_secret: il client secret OAuth.
    • refresh_token: il token di aggiornamento OAuth.
  • Service Account (documentazione)
    • json_key_file_path: un percorso di un file di chiave privata locale. Viene utilizzato per l'autenticazione tramite un service account.
    • impersonated_email: Indirizzo email facoltativo dell'account da rappresentare quando utilizzi la delega a livello di dominio di Google Workspace.

Comportamento della libreria

Questi campi determinano il comportamento della libreria:

Configurazione a livello di richiesta

Variabili di ambiente

Per configurare la libreria utilizzando le variabili di ambiente, utilizza quanto segue:

  • GOOGLE_ADS_ADS_ASSISTANT
  • GOOGLE_ADS_CLIENT_ID
  • GOOGLE_ADS_CLIENT_SECRET
  • GOOGLE_ADS_CONFIGURATION_FILE_PATH
  • GOOGLE_ADS_ENDPOINT
  • GOOGLE_ADS_HTTP_PROXY
  • GOOGLE_ADS_IMPERSONATED_EMAIL
  • GOOGLE_ADS_JSON_KEY_FILE_PATH
  • GOOGLE_ADS_LINKED_CUSTOMER_ID
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID
  • GOOGLE_ADS_LOGGING
  • GOOGLE_ADS_REFRESH_TOKEN
  • GOOGLE_ADS_USE_PROTO_PLUS
  • GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS (supportato in v28.3.0 e versioni successive)

Configurazione log

I campi di log, che si trovano sotto il campo di configurazione logging, sono derivati direttamente dal modulo integrato logging.config perché la libreria passa tutti i campi dello spazio dei nomi logging direttamente al metodo logging.config.dictConfig. Per informazioni dettagliate, consulta la guida alla registrazione.

  • version: un valore intero che rappresenta una versione dello schema.
  • disable_existing_loggers: indica se i logger configurati altrove nell'applicazione devono essere disattivati.
  • formatters: Dizionari che definiscono diversi tipi di formattatori.
  • handlers: dizionari che definiscono diversi gestori, che controllano dove vengono scritti i log e quali formattatori devono essere utilizzati.
  • loggers: dizionari che definiscono diversi tipi di logger, che includono un gestore e un livello di log.