Integrazione con Google Ads

Questa pagina descrive le configurazioni richieste per importare i dati da Google Ads come origine dati del carico di lavoro di marketing di Cortex Framework Data Foundation.

Google Ads è una piattaforma pubblicitaria online che consente alle attività di pubblicizzare i propri prodotti o servizi su varie proprietà Google. Cortex Framework combina i tuoi dati pubblicitari di Google Ads con altri canali di marketing, li analizza in modo completo e utilizza l'AI per migliorare i risultati delle campagne.

Il seguente diagramma descrive come i dati pubblicitari di Google Ads sono disponibili tramite il workload di marketing di Cortex Framework Data Foundation:

Origine dati Google Ads

Figura 1. Origine dati Google Ads.

File di configurazione

Il file config.json configura le impostazioni necessarie per trasferire i dati da qualsiasi origine dati, inclusa Google Ads. Questo file contiene i seguenti parametri per Google Ads:

  "marketing": {
          "deployGoogleAds": true,
          "GoogleAds": {
              "deployCDC": true,
              "lookbackDays": 180,
              "datasets": {
                  "cdc": "",
                  "raw": "",
                  "reporting": "REPORTING_GoogleAds"
                    }
                  }
                 }

La seguente tabella descrive il valore di ciascun parametro di marketing di Google Ads:

Parametro	Significato	Valore predefinito	Descrizione
`marketing.deployGoogleAds`	Implementare Google Ads	`true`	Esegui il deployment per l'origine dati Google Ads.
`marketing.GoogleAds.deployCDC`	Esegui il deployment di CDC per Google Ads	`true`	Genera script di elaborazione CDC di Google Ads da eseguire come DAG in Managed Airflow.
`marketing.GoogleAds.lookbackDays`	Giorni di intervallo per Google Ads	`180`	Numero di giorni per iniziare a recuperare i dati dall'API Google Ads.
`marketing.GoogleAds.datasets.cdc`	Set di dati CDC per Google Ads		Set di dati CDC per Google Ads.
`marketing.GoogleAds.datasets.raw`	Set di dati non elaborati per Google Ads		Set di dati non elaborati per Google Ads.
`marketing.GoogleAds.datasets.reporting`	Set di dati dei report per Google Ads	`"REPORTING_GoogleAds"`	Set di dati dei report per Google Ads.

Modello dati

Questa sezione descrive il modello di dati di Google Ads utilizzando il diagramma delle relazioni tra entità (ERD).

Figura 2. Google Ads: diagramma delle relazioni tra entità.

Visualizzazioni di base

Si tratta degli oggetti blu nel diagramma ERD e sono viste delle tabelle CDC senza trasformazioni, ad eccezione di alcuni alias dei nomi delle colonne. Vedi gli script in src/marketing/src/GoogleAds/src/reporting/ddls.

Viste report

Si tratta degli oggetti verdi nel diagramma ER e sono viste dei report che contengono metriche aggregate. Vedi gli script in src/marketing/src/GoogleAds/src/reporting/ddls.

Connessione API

I modelli di importazione di Cortex Framework utilizzano l'API Google Ads per recuperare attributi e metriche dei report da Google Ads. I modelli attuali di Cortex Framework utilizzano l'API Google Ads versione 17.1. Tieni presente le limitazioni dell'API Google Ads:

Operazioni di accesso di base al giorno: 15.000 (le richieste impaginate contenenti next_page_token validi non vengono conteggiate).
Dimensioni massime della pagina:10.000 righe per pagina.
Parametri predefiniti consigliati: le dimensioni della pagina sono pari a 10.000 righe per pagina.

Per saperne di più sulla connessione API, consulta la documentazione dell'API Google Ads.

Autenticazione account

Per configurare l'autenticazione dell'account:

Nella Google Cloud console, fai clic su Menu di navigazione > API e servizi > Credenziali > Crea credenziali.
Crea una credenziale ID client OAuth con le seguenti caratteristiche. Per saperne di più, consulta Utilizzare OAuth 2.0 per accedere alle API di Google.
```
Application type: "Web Application"
Name: CHOSEN_NAME #(For example,"Cortex Authentication Client").
Authorized redirect URIs: http://127.0.0.1
```
Sostituisci CHOSEN_NAME con il nome scelto per l'account delle credenziali dell'ID client OAuth.
Salva Client ID e Client secret dopo aver configurato la credenziale. Ti servirà in un secondo momento.
Genera un nuovo token utilizzando OAuth 2.0 per accedere alle API di Google. Cortex Data Foundation rileva e acquisisce automaticamente i dati di tutti i clienti (account) accessibili alle credenziali utilizzate per generare il token.
Crea un secret utilizzando Secret Manager:
- Nella Google Cloud console, fai clic su Secret Manager.
- Crea un secret denominato cortex-framework-google-ads-yaml utilizzando il seguente formato e modificando i valori in base alle tue impostazioni:
```
{"developer_token": "DEVELOPER_TOKEN_VALUE", "refresh_token": "REFRESH_TOKEN_VALUE", "client_id": "CLIENT_ID_VALUE", "client_secret": "CLIENT_SECRET_VALUE", "use_proto_plus": False}
```

Sostituisci quanto segue:

DEVELOPER_TOKEN_VALUE con il valore del token dello sviluppatore disponibile nell'account Google Ads.
REFRESH_TOKEN_VALUE con il valore del token di aggiornamento ottenuto nel passaggio 4.
CLIENT_ID_VALUE con il valore dell'ID client ottenuto nella configurazione OAuth nel passaggio 2.
CLIENT_SECRET_VALUE con il valore del client secret ottenuto dalla configurazione OAuth nel passaggio 2.

Aggiornamento e ritardo dei dati

Come regola generale, l'aggiornamento dei dati per le origini dati di Cortex Framework è limitato da ciò che consente la connessione upstream, nonché dalla frequenza di esecuzione del DAG. Modifica la frequenza di esecuzione del DAG in modo che sia in linea con la frequenza upstream, i vincoli delle risorse e le esigenze aziendali.

I dati recuperati utilizzando l'API Google Ads sono generalmente disponibili con una latenza di almeno 3 ore. Potrebbero essere aggiustati in un secondo momento a causa delle conversioni e del rilevamento del traffico non valido. Per saperne di più, consulta il seguente articolo Informazioni sull'aggiornamento dei dati nel Centro assistenza Google Ads.

Autorizzazioni per le connessioni di Managed Service for Apache Airflow

Crea le seguenti connessioni in Managed Airflow. Per maggiori dettagli, consulta la documentazione sulla gestione delle connessioni Airflow.

Nome connessione	Purpose
`googleads_raw_dataflow`	Per l'API Google Ads > Set di dati BigQuery non elaborati.
`googleads_cdc_bq`	Per il set di dati non elaborati > trasferimento del set di dati CDC.
`googleads_reporting_bq`	Per il trasferimento del set di dati CDC > set di dati dei report.

Autorizzazioni del account di servizio di Managed Airflow

Concedi le autorizzazioni Dataflow al account di servizio utilizzato in Managed Airflow (come configurato nella connessione googleads_raw_dataflow). Consulta le istruzioni nella documentazione di Dataflow.

Impostazioni di importazione

Controlla le pipeline di dati Source to Raw e Raw to CDC tramite le impostazioni nel file src/GoogleAds/config/ingestion_settings.yaml. Questa sezione descrive i parametri di ogni pipeline di dati.

Origine alle tabelle non elaborate

Questa sezione descrive quali entità vengono recuperate dalle API e in che modo. Ogni voce corrisponde a un'entità Google Ads. In base a questa configurazione, Cortex crea DAG Airflow che eseguono pipeline Dataflow per recuperare i dati utilizzando le API Google Ads.

I seguenti parametri controllano le impostazioni per Source to Raw per ogni voce:

Parametro	Descrizione
`load_frequency`	La frequenza con cui viene eseguito un DAG per questa entità per recuperare i dati da Google Ads. Per saperne di più sui valori possibili, consulta la documentazione di Airflow.
`api_name`	Nome risorsa API (ad esempio, `customer`).
`table_name`	Tabella nel set di dati non elaborati in cui sono archiviati i dati recuperati (ad esempio, `customer`).
`schema_file`	File schema nella directory `src/table_schema` che mappa i campi della risposta API ai nomi delle colonne della tabella di destinazione.
`key`	Colonne (separate da virgole) che formano un record univoco per questa tabella.
`is_metrics_table`	Indica se una determinata voce riguarda un'entità metrica (nell'API Google Ads). Il sistema tratta queste tabelle in modo leggermente diverso a causa della natura aggregata di queste tabelle.
`partition_details`	(Facoltativo) Se vuoi che questa tabella venga partizionata per motivi di rendimento. Per saperne di più, vedi Partizione della tabella.
`cluster_details`	(Facoltativo) Se vuoi che questa tabella venga raggruppata per motivi di rendimento. Per saperne di più, consulta Impostazioni cluster.

Tabelle non elaborate in tabelle CDC

Questa sezione descrive quali voci controllano il modo in cui i dati vengono spostati dalle tabelle non elaborate alle tabelle CDC. Ogni voce corrisponde a una tabella non elaborata (che a sua volta corrisponde all'entità API Google Ads come indicato).

I seguenti parametri controllano le impostazioni per Raw to CDC per ogni voce:

Parametro	Descrizione
`table_name`	Tabella nel set di dati CDC in cui sono archiviati i dati non elaborati dopo la trasformazione CDC (ad esempio, `customer`).
`raw_table`	Tabella in cui sono stati replicati i dati non elaborati.
`key`	Colonne (separate da virgole) che formano un record univoco per questa tabella.
`load_frequency`	La frequenza con cui viene eseguito un DAG per questa entità per popolare la tabella CDC. Per saperne di più sui valori possibili, consulta la documentazione di Airflow.
`schema_file`	File di schema nella directory `src/table_schema` che mappa le colonne non elaborate alle colonne CDC e al tipo di dati della colonna CDC. Si tratta dello stesso file di schema a cui si fa riferimento nella sezione precedente.
`partition_details`	(Facoltativo) Se vuoi che questa tabella venga partizionata per motivi di rendimento. Per saperne di più, vedi Partizione della tabella.
`cluster_details`	(Facoltativo) Se vuoi che questa tabella venga raggruppata per motivi di rendimento. Per saperne di più, consulta Impostazioni cluster.

Impostazioni report

Puoi configurare e controllare il modo in cui Cortex Framework genera i dati per il livello di report finale di Google Ads utilizzando il file delle impostazioni dei report src/GoogleAds/config/reporting_settings.yaml. Questo file controlla la modalità di generazione degli oggetti BigQuery del livello di reporting (tabelle, viste,funzioni o stored procedure).

Per ulteriori informazioni, vedi Personalizzare il file delle impostazioni dei report.

Passaggi successivi

Per saperne di più su altre origini dati e altri carichi di lavoro, vedi Origini dati e carichi di lavoro.
Per ulteriori informazioni sui passaggi per il deployment negli ambienti di produzione, consulta Prerequisiti per il deployment di Cortex Framework Data Foundation.