Integração com o Google Ads

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

O Google Ads é uma plataforma de publicidade on-line que permite às empresas anunciar 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, faz uma análise 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 ficam disponíveis na carga de trabalho de marketing da base de dados 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 origem, incluindo o Google Ads. Esse arquivo contém os seguintes parâmetros do 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`	Execute a implantação para a fonte de dados de anúncios do Google.
`marketing.GoogleAds.deployCDC`	Implantar o CDC para o Google Ads	`true`	Gere scripts de processamento de CDC do Google Ads para serem executados como DAGs no Airflow Gerenciado.
`marketing.GoogleAds.lookbackDays`	Período de retorno para o Google Ads	`180`	Número de dias para começar a buscar dados da API Google Ads.
`marketing.GoogleAds.datasets.cdc`	Conjunto de dados de CDC para o Google Ads		Conjunto de dados de 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 do Google Ads	`"REPORTING_GoogleAds"`	Conjunto de dados de relatórios do Google Ads.

Modelo de dados

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

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

Visualizações básicas

São os objetos azuis no DER e são visualizações em tabelas de CDC sem transformações além de alguns aliases de nomes de colunas. Consulte scripts em src/marketing/src/GoogleAds/src/reporting/ddls.

Vistas de relatórios

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

Conexão de 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 next_page_token válidos 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 > API 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 Client ID e Client secret depois que a credencial for configurada. Você precisará disso mais tarde.
Gere um novo token usando Acessar as APIs do Google com o OAuth 2.0. O Cortex Data Foundation detecta e ingere automaticamente dados de todos os clientes (contas) acessíveis às 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 mudando 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 com o valor do token de desenvolvedor disponível na conta do Google Ads.
REFRESH_TOKEN_VALUE com o valor do token de atualização obtido na etapa 4.
CLIENT_ID_VALUE com o valor do ID do cliente obtido na configuração do OAuth na etapa 2.
CLIENT_SECRET_VALUE com o 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 dos 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 com a frequência upstream, as restrições de recursos e as necessidades da sua empresa.

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 depois devido a conversões e detecção de tráfego inválido. Para mais informações, consulte o artigo Sobre a atualização de dados na Central de Ajuda do Google Ads.

Permissões de conexões do Serviço gerenciado para Apache Airflow

Crie as seguintes conexões no Airflow Gerenciado. Confira mais detalhes na documentação sobre como 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 "Conjunto de dados bruto > Transferência de conjunto de dados de CDC".
`googleads_reporting_bq`	Para transferência de conjunto de dados de CDC > conjunto de dados de relatórios.

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 com as configurações no arquivo src/GoogleAds/config/ingestion_settings.yaml. Nesta seção, descrevemos 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 do Google Ads.

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

Parâmetro	Descrição
`load_frequency`	A frequência com que um DAG para essa 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 bruto 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 esta 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 por motivos de performance. Para mais informações, consulte Partição de tabela.
`cluster_details`	Opcional:se você quiser que essa tabela seja agrupada para considerações de performance. Para mais informações, consulte Configurações do cluster.

Tabelas brutas para CDC

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

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

Parâmetro	Descrição
`table_name`	Tabela no conjunto de dados de CDC em que os dados brutos após a transformação de 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 esta tabela.
`load_frequency`	A frequência com que um DAG para essa entidade é executado para preencher a tabela do 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 de CDC e o tipo de dados da coluna de CDC. É o mesmo arquivo de esquema mencionado na seção anterior.
`partition_details`	Opcional:se você quiser que essa tabela seja particionada por motivos de performance. Para mais informações, consulte Partição de tabela.
`cluster_details`	Opcional:se você quiser que essa tabela seja agrupada para considerações de performance. Para mais informações, consulte Configurações do cluster.

Configurações de relatórios

É possível configurar e controlar como o Cortex Framework gera dados para a camada final de relatórios 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 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.