Integração com o Google Ads

Esta página descreve as configurações necessárias para trazer dados do Google Ads como uma fonte de dados da carga de trabalho de marketing da Data Foundation do Cortex Framework.

O Google Ads é uma plataforma de publicidade on-line que permite que as empresas anunciem seus produtos ou serviços em vários Serviços do Google. O Cortex Framework reúne seus dados de anúncios do Google Ads com outros canais de marketing, analisa de forma abrangente e usa a IA para melhorar os resultados da campanha.

O diagrama a seguir descreve como os dados de anúncios do Google Ads estão disponíveis na carga de trabalho de marketing da Data Foundation do Cortex Framework:

Fonte de dados de anúncios do Google

Figura 1. Fonte de dados do Google Ads.

Arquivo de configuração

O arquivo config.json configura as definições necessárias para transferir dados de qualquer fonte, incluindo o Google Ads. Esse arquivo contém os seguintes parâmetros para o Google Ads:

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

A tabela a seguir descreve o valor de cada parâmetro de marketing do Google Ads:

Parâmetro	Significado	Valor padrão	Descrição
`marketing.deployGoogleAds`	Implantar o Google Ads	`true`	Executar a implantação da fonte de dados de anúncios do Google.
`marketing.GoogleAds.deployCDC`	Implantar a CDC para o Google Ads	`true`	Gerar scripts de processamento da CDC do Google Ads para serem executados como DAGs no Airflow gerenciado.
`marketing.GoogleAds.lookbackDays`	Dias de retrospectiva do Google Ads	`180`	Número de dias para começar a buscar dados da API Google Ads.
`marketing.GoogleAds.datasets.cdc`	Conjunto de dados da CDC para o Google Ads		Conjunto de dados da CDC para o Google Ads.
`marketing.GoogleAds.datasets.raw`	Conjunto de dados brutos para o Google Ads		Conjunto de dados brutos para o Google Ads.
`marketing.GoogleAds.datasets.reporting`	Conjunto de dados de relatórios para o Google Ads	`"REPORTING_GoogleAds"`	Conjunto de dados de relatórios para o Google Ads.

Modelo de dados

Esta seção descreve o modelo de dados do Google Ads usando o diagrama de relacionamento de entidades (ERD, na sigla em inglês).

Figura 2. Google Ads: diagrama de relacionamento de entidades.

Visualizações básicas

Esses são os objetos azuis no ERD e são visualizações em tabelas de CDC sem transformações, exceto alguns aliases de nome de coluna. Consulte os scripts em src/marketing/src/GoogleAds/src/reporting/ddls.

Visualizações de relatórios

Esses são os objetos verdes no ERD e são visualizações de relatórios que contêm métricas agregadas. Consulte os scripts em src/marketing/src/GoogleAds/src/reporting/ddls.

Conexão da API

Os modelos de ingestão do Cortex Framework usam a API Google Ads para recuperar atributos e métricas de relatórios do Google Ads. Os modelos atuais do Cortex Framework usam a versão 17.1 da API Google Ads . Considere as limitações da API Google Ads:

Operações básicas de acesso por dia: 15.000 (solicitações paginadas que contêm válidos next_page_token não são contabilizadas).
Tamanho máximo da página:10.000 linhas por página.
Parâmetros padrão recomendados:o tamanho da página é igual a 10.000 linhas por página.

Para mais informações sobre a conexão da API, consulte a documentação da API Google Ads..

Autenticação da conta

Siga estas etapas para configurar a autenticação da conta:

No Google Cloud console, clique em Menu de navegação > APIs e serviços > Credenciais > Criar credenciais.
Crie uma credencial de ID do cliente OAuth com as seguintes características. Para mais informações, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.
```
Application type: "Web Application"
Name: CHOSEN_NAME #(For example,"Cortex Authentication Client").
Authorized redirect URIs: http://127.0.0.1
```
Substitua CHOSEN_NAME pelo nome escolhido para a conta de credencial do ID do cliente OAuth.
Salve o Client ID e o Client secret depois que a credencial for configurada. Você precisará disso mais tarde.
Gere um novo token usando o OAuth 2.0 para acessar as APIs do Google. A Data Foundation do Cortex detecta e ingere automaticamente dados de todos os clientes (contas) que podem ser acessados pelas credenciais usadas para gerar o token.
Crie um secret usando o Secret Manager:
- No Google Cloud console, clique em Secret Manager.
- Crie um secret chamado cortex-framework-google-ads-yaml usando o formato a seguir e alterando os valores de acordo com suas configurações:
```
{"developer_token": "DEVELOPER_TOKEN_VALUE", "refresh_token": "REFRESH_TOKEN_VALUE", "client_id": "CLIENT_ID_VALUE", "client_secret": "CLIENT_SECRET_VALUE", "use_proto_plus": False}
```

Substitua:

DEVELOPER_TOKEN_VALUE pelo valor do token de desenvolvedor disponível na conta do Google Ads.
REFRESH_TOKEN_VALUE pelo valor do token de atualização obtido na etapa 4.
CLIENT_ID_VALUE pelo valor do ID do cliente obtido na configuração do OAuth na etapa 2.
CLIENT_SECRET_VALUE pelo valor da chave secreta do cliente obtido na configuração do OAuth na etapa 2.

Atualização e atraso de dados

Como regra geral, a atualização de dados para fontes de dados do Cortex Framework é limitada pelo que a conexão upstream permite, bem como pela frequência de execução do DAG. Ajuste a frequência de execução do DAG para se alinhar à frequência upstream, às restrições de recursos e às necessidades de negócios.

Os dados recuperados usando a API Google Ads geralmente estão disponíveis com uma latência de mais de 3 horas. Eles podem ser ajustados posteriormente devido a conversões e detecção de tráfego inválido. Para mais informações, consulte o seguinte artigo Sobre a atualização de dados na Central de Ajuda do Google Ads.

Permissões do Serviço Gerenciado para Apache Airflow para conexões

Crie as seguintes conexões no Airflow gerenciado. Confira mais detalhes na documentação Gerenciar conexões do Airflow.

Nome da conexão	Purpose
`googleads_raw_dataflow`	Para a API Google Ads > conjunto de dados brutos do BigQuery.
`googleads_cdc_bq`	Para a transferência de conjunto de dados brutos > conjunto de dados da CDC.
`googleads_reporting_bq`	Para a transferência de conjunto de dados da CDC > conjunto de dados de relatórios transferência.

Permissões da conta de serviço do Airflow gerenciado

Conceda permissões do Dataflow à conta de serviço usada no Airflow Gerenciado (conforme configurado na conexão googleads_raw_dataflow). Consulte as instruções na documentação do Dataflow.

Configurações de ingestão

Controle os pipelines de dados Source to Raw e Raw to CDC pelas configurações no arquivo src/GoogleAds/config/ingestion_settings.yaml. Esta seção descreve os parâmetros de cada pipeline de dados.

Origem para tabelas brutas

Esta seção descreve quais entidades são buscadas pelas APIs e como. Cada entrada corresponde a uma entidade do Google Ads. Com base nessa configuração, o Cortex cria DAGs do Airflow que executam pipelines do Dataflow para buscar dados usando as APIs Google Ads.

Os parâmetros a seguir controlam as configurações de Source to Raw para cada entrada:

Parâmetro	Descrição
`load_frequency`	Com que frequência um DAG dessa entidade é executado para buscar dados do Google Ads. Para mais informações sobre os valores possíveis, consulte a documentação do Airflow.
`api_name`	Nome do recurso da API (por exemplo, `customer`).
`table_name`	Tabela no conjunto de dados brutos em que os dados buscados são armazenados (por exemplo, `customer`).
`schema_file`	Arquivo de esquema no diretório `src/table_schema` que mapeia os campos de resposta da API para os nomes das colunas da tabela de destino.
`key`	Colunas (separadas por vírgula) que formam um registro exclusivo para essa tabela.
`is_metrics_table`	Indica se uma determinada entrada é para uma entidade de métrica (na API Google Ads). O sistema trata essas tabelas de maneira um pouco diferente devido à natureza agregada delas.
`partition_details`	Opcional: Se você quiser que essa tabela seja particionada para considerações de performance. Para mais informações, consulte Partição de tabelas.
`cluster_details`	Opcional: Se você quiser que essa tabela seja agrupada para considerações de performance. Para mais informações, consulte Configurações de cluster.

Tabelas brutas para CDC

Esta seção descreve quais entradas controlam como os dados são movidos de tabelas brutas para tabelas de CDC. Cada entrada corresponde a uma tabela bruta (que, por sua vez, corresponde à entidade da API Google Ads, conforme mencionado).

Os parâmetros a seguir controlam as configurações de Raw to CDC para cada entrada:

Parâmetro	Descrição
`table_name`	Tabela no conjunto de dados da CDC em que os dados brutos após a transformação da CDC são armazenados (por exemplo, `customer`).
`raw_table`	Tabela em que os dados brutos foram replicados.
`key`	Colunas (separadas por vírgula) que formam um registro exclusivo para essa tabela.
`load_frequency`	Com que frequência um DAG dessa entidade é executado para preencher a tabela da CDC. Para mais informações sobre os valores possíveis, consulte a documentação do Airflow.
`schema_file`	Arquivo de esquema no diretório `src/table_schema` que mapeia colunas brutas para colunas da CDC e o tipo de dados da coluna da CDC. Esse é o mesmo arquivo de esquema a que se refere a seção anterior.
`partition_details`	Opcional: Se você quiser que essa tabela seja particionada para considerações de performance. Para mais informações, consulte Partição de tabelas.
`cluster_details`	Opcional: Se você quiser que essa tabela seja agrupada para considerações de performance. Para mais informações, consulte Configurações de cluster.

Configurações de relatório

É possível configurar e controlar como o Cortex Framework gera dados para a camada de relatórios finais do Google Ads usando o arquivo de configurações de relatórios src/GoogleAds/config/reporting_settings.yaml. Esse arquivo controla como os objetos do BigQuery da camada de relatórios (tabelas, visualizações,funções ou procedimentos armazenados) são gerados.

Para mais informações, consulte Como personalizar o arquivo de configurações de relatórios.

A seguir

Para mais informações sobre outras fontes de dados e cargas de trabalho, consulte Fontes de dados e cargas de trabalho.
Para mais informações sobre as etapas de implantação em ambientes de produção, consulte Pré-requisitos de implantação da Data Foundation do Cortex Framework.