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 transferir dados do Google Ads como uma origem de dados da carga de trabalho de marketing da base de dados do Cortex Framework.

O Google Ads é uma plataforma de publicidade online que permite às empresas anunciar os respetivos produtos ou serviços em várias propriedades da Google. A framework Cortex junta os seus dados do Google Ads com outros canais de marketing, analisa-os de forma abrangente e usa a IA para melhorar os resultados das suas campanhas.

O diagrama seguinte descreve como os dados do Google Ads estão disponíveis através da carga de trabalho de marketing da base de dados do Cortex Framework:

Origem de dados do Google Ads

Figura 1. Origem de dados do Google Ads.

Ficheiro de configuração

O ficheiro config.json configura as definições necessárias para transferir dados de qualquer origem de dados, incluindo o Google Ads. Este ficheiro 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 seguinte descreve o valor de cada parâmetro de marketing do Google Ads:

Parâmetro	Significado	Valor predefinido	Descrição
`marketing.deployGoogleAds`	Implemente o Google Ads	`true`	Execute a implementação para a origem de dados do Google Ads.
`marketing.GoogleAds.deployCDC`	Implemente a CDC para o Google Ads	`true`	Gere scripts de processamento de CDC do Google Ads para execução como DAGs no Cloud Composer.
`marketing.GoogleAds.lookbackDays`	Dias de retrospetiva para o Google Ads	`180`	Número de dias para começar a obter 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 não processados para o Google Ads		Conjunto de dados não processados 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 secção descreve o modelo de dados do Google Ads através do diagrama de relação entre entidades (ERD).

Figura 2. Google Ads: diagrama de relação entre entidades.

Visualizações de base

Estes são os objetos azuis no DRE e são vistas em tabelas de CDC sem transformações, exceto alguns alias de nomes de colunas. Veja guiões em src/marketing/src/GoogleAds/src/reporting/ddls.

Visualizações de propriedade de relatórios

Estes são os objetos verdes no DER e são vistas de relatórios que contêm métricas agregadas. Veja guiões em src/marketing/src/GoogleAds/src/reporting/ddls.

Ligação à API

Os modelos de carregamento da estrutura do Cortex usam a API Google Ads para obter atributos e métricas de relatórios do Google Ads. Os modelos atuais da Cortex Framework usam a versão 17.1 da API Google Ads. Tenha em atenção as limitações da API Google Ads:

Operações de acesso básicas por dia: 15 000 (os pedidos paginados que contêm next_page_token válidos não são contabilizados).
Tamanho máximo da página: 10 000 linhas por página.
Parâmetros predefinidos recomendados: o tamanho da página é igual a 10 000 linhas por página.

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

Autenticação da conta

Siga estes passos para configurar a autenticação da conta:

Na Google Cloud consola, clique em Menu de navegação > API e serviços > Credenciais > Criar credenciais.
Crie uma credencial de ID de cliente OAuth com as seguintes caraterísticas. Para mais informações, consulte o artigo Utilizar o OAuth 2.0 para aceder às APIs 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 credenciais do ID de cliente OAuth.
Guarde o Client ID e o Client secret depois de configurar a credencial. Precisar dele mais tarde.
Gere um novo token através do OAuth 2.0 para aceder às APIs Google. A Cortex Data Foundation deteta e carrega automaticamente dados de todos os clientes (contas) acessíveis às credenciais usadas para gerar o token.
Crie um secret com o Secret Manager:
- Na Google Cloud consola, clique em Secret Manager.
- Crie um segredo denominado cortex-framework-google-ads-yaml usando o seguinte formato e alterando os valores de acordo com as suas definiçõ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 o seguinte:

DEVELOPER_TOKEN_VALUE com o valor do token de programador disponível na conta do Google Ads.
REFRESH_TOKEN_VALUE com o valor do token de atualização obtido no passo 4.
CLIENT_ID_VALUE com o valor do ID de cliente obtido na configuração do OAuth no passo 2.
CLIENT_SECRET_VALUE com o valor do segredo do cliente obtido na configuração do OAuth no passo 2.

Atualidade e atraso dos dados

Regra geral, a atualização dos dados das origens de dados do Cortex Framework é limitada pelo que a ligação a montante 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 a montante, as restrições de recursos e as necessidades da sua empresa.

Os dados obtidos através da API Google Ads estão geralmente disponíveis com uma latência de mais de 3 horas. Podem ser ajustados posteriormente devido a conversões e deteção de tráfego inválido. Para mais informações, consulte o artigo Acerca da atualização dos dados no Centro de Ajuda do Google Ads.

Autorizações de ligações do Cloud Composer

Crie as seguintes associações no Cloud Composer. Veja mais detalhes na documentação sobre a gestão de associações do Airflow.

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

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

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

Definições de carregamento

Controle os pipelines de dados Source to Raw e Raw to CDC através das definições no ficheiro src/GoogleAds/config/ingestion_settings.yaml. Esta secção descreve os parâmetros de cada pipeline de dados.

Origem para tabelas não processadas

Esta secção descreve que entidades são obtidas pelas APIs e como. Cada entrada corresponde a uma entidade do Google Ads. Com base nesta configuração, o Cortex cria DAGs do Airflow que executam pipelines do Dataflow para obter dados através das APIs Google Ads.

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

Parâmetro	Descrição
`load_frequency`	Com que frequência um DAG para esta entidade é executado para obter dados do Google Ads. Para mais informações acerca dos 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 não processados onde os dados obtidos são armazenados (por exemplo, `customer`).
`schema_file`	Ficheiro 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 registo único para esta tabela.
`is_metrics_table`	Indica se uma determinada entrada se refere a uma entidade de métrica (na API Google Ads). O sistema trata essas tabelas de forma ligeiramente diferente devido à natureza agregada das mesmas.
`partition_details`	Opcional: se quiser que esta tabela seja particionada para ter em conta o desempenho. Para mais informações, consulte o artigo Partição de tabelas.
`cluster_details`	Opcional: se quiser que esta tabela seja agrupada para considerações de desempenho. Para mais informações, consulte o artigo Definições de cluster.

Tabelas de dados não processados para tabelas do CDC

Esta secção descreve que entradas controlam a forma como os dados são movidos das tabelas não processadas para as tabelas de CDC. Cada entrada corresponde a uma tabela não processada (que, por sua vez, corresponde à entidade da API Google Ads, conforme mencionado).

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

Parâmetro	Descrição
`table_name`	Tabela no conjunto de dados de CDC onde os dados não processados após a transformação de CDC são armazenados (por exemplo, `customer`).
`raw_table`	Tabela na qual os dados não processados foram replicados.
`key`	Colunas (separadas por vírgulas) que formam um registo único para esta tabela.
`load_frequency`	A frequência com que um DAG para esta entidade é executado para preencher a tabela de CDC. Para mais informações sobre os valores possíveis, consulte a documentação do Airflow.
`schema_file`	Ficheiro de esquema no diretório `src/table_schema` que mapeia colunas não processadas para colunas de CDC e o tipo de dados da coluna de CDC. Este é o mesmo ficheiro de esquema referido na secção anterior.
`partition_details`	Opcional: se quiser que esta tabela seja particionada por motivos de desempenho. Para mais informações, consulte o artigo Partição de tabelas.
`cluster_details`	Opcional: se quiser que esta tabela seja agrupada para considerações de desempenho. Para mais informações, consulte o artigo Definições de cluster.

Definições de relatórios

Pode configurar e controlar como a Cortex Framework gera dados para a camada de relatórios final do Google Ads através do ficheiro de definições de relatórios src/GoogleAds/config/reporting_settings.yaml. Este ficheiro controla a forma como os objetos do BigQuery da camada de relatórios (tabelas, vistas,funções ou procedimentos armazenados) são gerados.

Para mais informações, consulte o artigo Personalizar o ficheiro de definições de relatórios.

O que se segue?

Para mais informações sobre outras origens de dados e cargas de trabalho, consulte o artigo Origens de dados e cargas de trabalho.
Para mais informações sobre os passos de implementação em ambientes de produção, consulte os Pré-requisitos de implementação da base de dados do Cortex Framework.