Questa pagina è stata tradotta dall'API Cloud Translation.

Integrazione con Google Ads

Questa pagina descrive le configurazioni necessarie 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 promuovere i propri prodotti o servizi su varie proprietà di Google. Cortex Framework riunisce i tuoi dati di Google Ads con altri canali di marketing, li analizza in modo completo e utilizza l'AI per migliorare i risultati delle tue campagne.

Il seguente diagramma descrive come i dati di Google Ads sono disponibili tramite il carico di lavoro di marketing di Cortex Data Foundation:

Origine dati Google Ads

Figura 1. Origine dati di Google Ads.

File di configurazione

Il file config.json configura le impostazioni necessarie per trasferire i dati da qualsiasi origine dati, incluso 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`	Esegui il deployment di 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 Cloud Composer.
`marketing.GoogleAds.lookbackDays`	Giorni di lookback per Google Ads	`180`	Numero di giorni prima di 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 di relazione tra entità (ERD).

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

Visualizzazioni di base

Questi sono gli oggetti blu nell'ERD e sono viste sulle tabelle CDC senza trasformazioni diverse da alcuni alias dei nomi delle colonne. Visualizza gli script in src/marketing/src/GoogleAds/src/reporting/ddls.

Viste report

Si tratta degli oggetti verdi nell'ERD e sono visualizzazioni dei report che contengono metriche aggregate. Visualizza 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 gli attributi e le 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: 15000 (le richieste paginate contenenti next_page_token validi non vengono conteggiate).
Dimensioni massime della pagina: 10.000 righe per pagina.
Parametri predefiniti consigliati: dimensioni pagina pari a 10000 righe per pagina.

Per ulteriori informazioni sulla connessione dell'API, consulta la documentazione dell'API Google Ads.

Autenticazione account

Per configurare l'autenticazione dell'account:

Nella console Google Cloud, fai clic su Menu di navigazione > API e servizi > Credenziali > Crea credenziali.
Crea una credenziale ID client OAuth con le seguenti caratteristiche. Per ulteriori informazioni, consulta l'articolo 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 le credenziali. 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 importa automaticamente i dati di tutti i clienti (account) accessibili alle credenziali utilizzate per generare il token.
Crea un secret utilizzando Secret Manager:
- Nella console Google Cloud, 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 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 di 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 a monte, nonché dalla frequenza di esecuzione del DAG. Modifica la frequenza di esecuzione del DAG in modo che sia in linea con la frequenza a monte, le limitazioni delle risorse e le esigenze della tua attività.

I dati recuperati utilizzando l'API Google Ads sono disponibili a livello generale con una latenza di oltre 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 l'articolo Informazioni sull'aggiornamento dei dati nel Centro assistenza Google Ads.

Autorizzazioni per le connessioni di Cloud Composer

Crea le seguenti connessioni in Cloud Composer. Per ulteriori dettagli, consulta la documentazione sulla gestione delle connessioni Airflow.

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

Autorizzazioni del service account di Cloud Composer

Concedi le autorizzazioni Dataflow all'account di servizio utilizzato in Cloud Composer (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 come. Ogni voce corrisponde a una persona giuridica Google Ads. In base a questa configurazione, Cortex crea DAG di Airflow che eseguono pipeline di Dataflow per recuperare i dati utilizzando le API Google Ads.

I seguenti parametri controllano le impostazioni di 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 ulteriori informazioni sui possibili valori, consulta la documentazione di Airflow.
`api_name`	Nome della risorsa API (ad es. `customer`).
`table_name`	Tabella nel set di dati non elaborato in cui sono memorizzati i dati recuperati (ad es. `customer`).
`schema_file`	File dello schema nella directory `src/table_schema` che mappa i campi di risposta dell'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 le tratta in modo leggermente diverso a causa della loro natura aggregata.
`partition_details`	Facoltativo:se vuoi che questa tabella sia suddivisa per motivi di rendimento. Per ulteriori informazioni, consulta Partizione della tabella.
`cluster_details`	(Facoltativo) Se vuoi che questa tabella sia raggruppata per motivi di rendimento. Per ulteriori informazioni, consulta Impostazioni cluster.

Tabelle non elaborate a CDC

Questa sezione descrive le voci che controllano il trasferimento dei dati dalle tabelle non elaborate alle tabelle CDC. Ogni voce corrisponde a una tabella non elaborata (che a sua volta corrisponde all'entità dell'API Google Ads, come indicato).

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

Parametro	Descrizione
`table_name`	Tabella nel set di dati CDC in cui vengono archiviati i dati non elaborati dopo la trasformazione CDC (ad es. `customer`).
`raw_table`	Tabella su 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 compilare la tabella CDC. Per ulteriori informazioni sui possibili valori, consulta la documentazione di Airflow.
`schema_file`	File dello 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 dello schema a cui si fa riferimento nella sezione precedente.
`partition_details`	Facoltativo:se vuoi che questa tabella sia suddivisa per motivi di rendimento. Per ulteriori informazioni, consulta Partizione della tabella.
`cluster_details`	(Facoltativo) Se vuoi che questa tabella sia raggruppata per motivi di rendimento. Per ulteriori informazioni, consulta Impostazioni cluster.

Impostazioni report

Puoi configurare e controllare la modalità di generazione dei dati da parte di Cortex Framework per il livello di generazione dei report finali di Google Ads utilizzando il file di impostazioni dei report src/GoogleAds/config/reporting_settings.yaml. Questo file controlla come vengono generati gli oggetti BigQuery del livello di generazione di report (tabelle, visualizzazioni,funzioni o stored procedure).

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

Passaggi successivi

Per ulteriori informazioni su altre origini dati e carichi di lavoro, consulta Origini dati e carichi di lavoro.
Per ulteriori informazioni sulla procedura di implementazione negli ambienti di produzione, consulta Prerequisiti per l'implementazione di Data Foundation di Cortex Framework.