Integração com a Meta

Nesta página, descrevemos as configurações necessárias para trazer dados da Meta (anúncios do Facebook e do Instagram) como uma fonte de dados da carga de trabalho de marketing da Data Foundation do Cortex Framework.

A Meta é uma empresa de tecnologia proprietária de várias plataformas on-line conhecidas. O Cortex Framework integra dados de anúncios do Instagram e do Facebook para analisar e combinar com outras fontes de dados, além de usar a IA para gerar insights mais detalhados e otimizar sua estratégia de marketing.

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

Fonte de metadados

Figura 1. Fonte de dados de marketing da Meta.

Arquivo de configuração

O arquivo config.json configura as definições necessárias para se conectar a fontes de dados e transferir dados de várias cargas de trabalho. Esse arquivo contém os seguintes parâmetros para o Meta:

   "marketing": {
        "deployMeta": true,
        "Meta": {
            "deployCDC": true,
            "datasets": {
                "cdc": "",
                "raw": "",
                "reporting": "REPORTING_Meta"
            }
        }
    }

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

Parâmetro	Significado	Valor padrão	Descrição
`marketing.deployMeta`	Implantar meta	`true`	Execute a implantação da fonte de dados da Meta.
`marketing.Meta.deployCDC`	Implante scripts de CDC para a Meta	`true`	Gere scripts de processamento de CDC do Meta para serem executados como DAGs no Cloud Composer.
`marketing.Meta.datasets.cdc`	Conjunto de dados de CDC para a Meta		Conjunto de dados de CDC para a Meta.
`marketing.Meta.datasets.raw`	Conjunto de dados brutos para a Meta		Conjunto de dados brutos para a Meta.
`marketing.Meta.datasets.reporting`	Conjunto de dados de relatórios para a Meta	`"REPORTING_Meta"`	Conjunto de dados de relatórios para a Meta.

Modelo de dados

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

Figura 2. Meta: diagrama de relacionamento de entidades.

Visualizações básicas

São os objetos azuis no DER e são visualizações em tabelas de CDC com transformações mínimas para descompactar estruturas de dados complexas. Consulte scripts em src/marketing/src/Meta/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/Meta/src/reporting/ddls.

Conexão de API

Os modelos de ingestão no Cortex Framework para Meta usam a API de marketing da Meta para recuperar atributos e métricas de relatórios. Os modelos atuais usam a versão v25.0.

A Meta impõe um limite de taxa dinâmico ao consultar a API Marketing. Quando o limite de taxa é atingido, os DAGs de ingestão de origem para bruto podem não ser concluídos. Nesses casos, você pode ver mensagens de erro relevantes no registro, e a próxima execução dos DAGs vai carregar de forma retroativa os dados ausentes.

A API Marketing da Meta tem dois níveis de acesso: básico e padrão. O nível padrão oferece um limite muito maior e é recomendado se você planeja usar a ingestão de origem para dados brutos de forma extensiva. Para mais detalhes sobre esses limites e como alcançar um nível de acesso mais alto, consulte a documentação da Meta.

Se você tiver acesso ao nível Standard, poderá diminuir o valor da configuração next_request_delay_sec em src/Meta/src/raw/pipelines/config.ini para reduzir os tempos de carregamento.

Acesso à API e token de acesso

As etapas a seguir são necessárias no Gerenciador de empresa da Meta e no Developer Console para trazer dados da Meta para o Cortex Framework.

Identifique um app para usar. Você pode criar um novo app conectado à conta empresarial. Confira se o app é do tipo Business.
Configurar permissões do app. Você precisa ser atribuído ao app como um administrador antes de criar tokens com ele. Consulte a documentação sobre papéis de app. Atribua recursos relevantes (contas) ao seu app.
Crie um token de acesso. Os tokens de acesso são necessários para acessar a API Marketing do Meta e estão sempre associados a um app e um usuário. Você pode criar o token com um usuário do sistema ou com seu próprio login.
1. Crie um usuário administrador do sistema.
2. Gere um token. Anote o token assim que ele for gerado, porque não será possível recuperá-lo depois que você sair da página.
3. Conceda as permissões ads_read e business_management ao seu token para acessar os objetos compatíveis.
Observação: como alternativa, você pode criar um token de acesso do usuário usando seu próprio login. Os tokens criados dessa forma têm o mesmo acesso a todas as contas e páginas que você, sem necessidade de mais especificações.
Siga a documentação do Cloud Composer para ativar o Secret Manager no Cloud Composer. Em seguida, crie um secret chamado cortex_meta_access_token e armazene o token gerado na etapa anterior como conteúdo.

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.

Com a API de marketing da Meta, a maioria dos dados (exceto conversões) fica disponível quase em tempo real, embora possa ser ajustada até 28 dias após o evento.

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
`meta_raw_dataflow`	Para a API Meta Marketing > conjunto de dados bruto do BigQuery
`meta_cdc_bq`	Para "Conjunto de dados brutos > Transferência de conjunto de dados de CDC"
`meta_reporting_bq`	Para conjunto de dados de 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 meta_raw_dataflow). Consulte as instruções na documentação do Dataflow. A conta de serviço também precisa da permissão Secret Manager Secret Accessor. Confira detalhes na documentação de controle de acesso.

Parâmetros de solicitação

O diretório src/Meta/config/request_parameters contém um arquivo de especificação de solicitação de API para cada entidade extraída da API Marketing do Meta. Cada arquivo de solicitação contém uma lista de campos a serem buscados na API Meta Marketing, um campo por linha. Para mais informações, consulte a referência da API Marketing da Meta.

Configurações de ingestão

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

Origem para tabelas brutas

Esta seção tem entradas que controlam quais entidades são buscadas pelas APIs e como. Cada entrada corresponde a uma entidade da API Meta Marketing. Com base nessa configuração, o Cortex Framework cria DAGs do Airflow que executam pipelines do Dataflow para buscar dados usando as APIs de marketing da Meta.

O arquivo src/Meta/src/raw/pipelines/config.ini controla alguns comportamentos do DAG do Cloud Composer e como as APIs de marketing da Meta são consumidas. Encontre as descrições de cada parâmetro no arquivo.

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

Parâmetro	Descrição
`base_table`	Tabela no conjunto de dados brutos em que os dados buscados são armazenados (por exemplo, `customer`).
`load_frequency`	Com que frequência um DAG para isso é executado para buscar dados da Meta. Para mais informações sobre os valores possíveis, consulte a documentação do Airflow.
`object_endpoint`	Caminho do endpoint de API (por exemplo, `campaigns` para o endpoint `/{account_id}/campaigns`).
`entity_type`	Tipo de tabela (deve ser um de `fact`, `dimension` ou `addaccount)`.
`object_id_column`	Colunas (separadas por vírgula) que formam um registro exclusivo para essa tabela. Obrigatório apenas quando `entity_type` é `fact`.
`breakdowns`	Opcional:colunas de detalhamento (separadas por vírgula) para endpoints de insights. Aplicável somente quando `entity_type` é `fact`.
`action_breakdowns`	Opcional:colunas de detalhamento da ação (separadas por vírgula) para endpoints de insights. Aplicável somente quando `entity_type` é `fact`.
`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 as entradas que 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 do Meta, conforme mencionado).

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

Parâmetro	Descrição
`base_table`	Tabela em que os dados brutos foram replicados. Uma tabela com o mesmo nome no conjunto de dados de CDC armazena os dados brutos após a transformação de CDC (por exemplo, `campaign_insights`).
`row_identifiers`	Colunas (separadas por vírgula) que formam um registro exclusivo para essa 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.
`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.

Esquema da tabela de CDC

Para a Meta, todos os campos são armazenados no formato de string na camada bruta. Na camada de CDC, os tipos primitivos são convertidos em tipos de dados comerciais relevantes, e todos os tipos complexos são armazenados no formato JSON do BigQuery.

Para ativar essa conversão, o diretório src/Meta/config/table_schema contém um arquivo de esquema para cada entidade especificada na seção raw_to_cdc_tables que explica como traduzir corretamente cada tabela bruta do BigQuery em uma tabela de CDC.

Cada arquivo de esquema contém três colunas:

SourceField: nome do campo da tabela bruta para essa entidade.
TargetField: nome da coluna na tabela de CDC para essa entidade.
DataType: tipo de dados de cada campo da tabela de CDC.

Configurações de relatórios

É possível configurar e controlar como o Cortex gera dados para a camada final de relatórios da Meta usando o arquivo de configurações de relatórios (src/Meta/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.