Esta página foi traduzida pela API Cloud Translation.

Integração com o Google Ads

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

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

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

Origem de dados do Google Ads

Figura 1. Origem de dados do Google Ads.

Arquivo de configuração

O arquivo config.json configura as configurações necessárias para transferir dados de qualquer origem, 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`	Execute a implantação da fonte de dados do Google Ads.
`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 Cloud Composer.
`marketing.GoogleAds.lookbackDays`	Dias de lookback 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 do CDC para o Google Ads		Conjunto de dados do 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 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 de API

Os modelos de transferência 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 API Google Ads versão 17.1. 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 saber mais 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 console do Google Cloud, 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 Client ID e 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 Cortex Data Foundation detecta e processa automaticamente os 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 console do Google Cloud, 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 com o valor do token do 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 da configuração do OAuth na etapa 2.

Atualização e atraso de dados

Como regra geral, a atualidade dos dados para fontes de dados do Cortex Framework é limitada pelo que a conexão upstream permite, bem como pela frequência da execução da DAG. Ajuste a frequência de execução do DAG para alinhá-la à frequência upstream, às restrições de recursos e às necessidades da sua empresa.

Os dados recuperados usando a API Google Ads geralmente estão disponíveis com uma latência de mais de três 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 Cloud Composer

Crie as seguintes conexões no Cloud Composer. 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 o conjunto de dados brutos > Transferência de conjunto de dados do CDC.
`googleads_reporting_bq`	Para o conjunto de dados do CDC > Transferência de conjunto de dados de relatórios.

Permissões da conta de serviço do Cloud Composer

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

Configurações de transferência

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 por 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 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 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 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írgulas) 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 Particionamento de tabelas.
`cluster_details`	Opcional:se você quiser agrupar essa tabela para considerar a performance. Para mais informações, consulte Configurações do cluster.

De bruto para tabelas de 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 são armazenados após a transformação da CDC (por exemplo, `customer`).
`raw_table`	Tabela em que os dados brutos foram replicados.
`key`	Colunas (separadas por vírgulas) que formam um registro exclusivo para essa tabela.
`load_frequency`	Com que frequência um DAG dessa entidade é executado para preencher a tabela 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 do CDC e o tipo de dados da coluna do CDC. Esse é 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 Particionamento de tabelas.
`cluster_details`	Opcional:se você quiser agrupar essa tabela para considerar a performance. Para mais informações, consulte Configurações do cluster.

Configurações de relatórios

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