Integração com o Meta

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

A Meta é uma empresa de tecnologia que tem várias plataformas on-line conhecidas. O Cortex Framework integra dados de anúncios do Instagram e do Facebook para analisá-los, combiná-los com outras fontes de dados e usar a IA para ter insights mais detalhados e otimizar sua estratégia de marketing.

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

Origem de metadados

Figura 1. Fonte de dados de metamarketing.

Arquivo de configuração

O arquivo config.json configura as configurações necessárias para se conectar a fontes de dados para 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 para a fonte de dados do Meta.
marketing.Meta.deployCDC Implantar scripts de CDC para a Meta true Gere scripts de processamento de CDC Meta para serem executados como DAGs no Cloud Composer.
marketing.Meta.datasets.cdc Conjunto de dados do CDC para Meta Conjunto de dados do CDC para Meta.
marketing.Meta.datasets.raw Conjunto de dados brutos para Meta Conjunto de dados brutos para Meta.
marketing.Meta.datasets.reporting Conjunto de dados de relatórios para Meta "REPORTING_Meta" Conjunto de dados de relatórios para a Meta.

Modelo de dados

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

Diagrama de relacionamento de entidades para Meta

Figura 2. Meta: diagrama de relacionamento de entidade.

Visualizações básicas

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

Conexão de API

Os modelos de transferência no Cortex Framework para Meta usam a API Meta Marketing para recuperar atributos e métricas de relatórios. Os modelos atuais usam a versão v21.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 transferência de origem para dados brutos podem não ser concluídos. Nesses casos, é possível ver mensagens de erro relevantes no registro, e a próxima execução dos DAGs carregaria retroativamente os dados ausentes.

A API Meta Marketing 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 transferência de origem para bruto extensivamente. 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 padrão, poderá diminuir o valor da configuração next_request_delay_sec em src/Meta/src/raw/pipelines/config.ini para acelerar o tempo de carregamento.

Acesso à API e token de acesso

As etapas a seguir são necessárias no Meta Business Manager e no Console do desenvolvedor para trazer dados do Meta para o Cortex Framework.

  1. Identifique um app para usar. Você pode criar um novo app conectado à conta da empresa. Confira se o app é do tipo Business.
  2. Configurar as permissões do app. Você precisa ser atribuído ao app como administrador para criar tokens com ele. Consulte a documentação sobre papéis de app. Atribua recursos (contas) relevantes ao seu app.

  3. Crie um token de acesso. Os tokens de acesso são necessários para acessar a API Meta Marketing e sempre são associados a um app e um usuário. É possível criar o token com um usuário do sistema ou com seu próprio login.

    1. Crie um usuário do sistema de administrador.
    2. Gerar um token. Anote seu token assim que ele for gerado, porque ele não poderá ser recuperado depois que você sair da página.
    3. Conceda as permissões ads_read e business_management ao seu token para acessar os objetos com suporte.

  4. Siga a documentação do Cloud Composer para ativar o Secret Manager no Cloud Composer. Em seguida, crie um segredo com o nome cortex_meta_access_token e armazene o token que você gerou na etapa anterior como conteúdo.

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.

Com a API Meta Marketing, a maioria dos dados (exceto conversões) fica disponível quase em tempo real, embora eles possam ser ajustados 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 brutos do BigQuery
meta_cdc_bq Para o conjunto de dados brutos > Transferência de conjunto de dados da CDC
meta_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 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. Consulte os 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 Meta Marketing. Cada arquivo de solicitação contém uma lista de campos a serem buscados na API Meta Marketing, um campo por linha. Confira mais informações na referência da API Meta Marketing.

Configurações de transferência

Controle os pipelines de dados Source to Raw e Raw to CDC pelas 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 do Meta Marketing.

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

Os parâmetros a seguir 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 A frequência com que um DAG é executado para buscar dados do Meta. Para mais informações sobre os valores possíveis, consulte a documentação do Airflow.
object_endpoint Caminho do endpoint da API (por exemplo, campaigns para o endpoint /{account_id}/campaigns).
entity_type Tipo de tabela (precisa ser fact, dimension ou addaccount)).
object_id_column Colunas (separadas por vírgulas) que formam um registro exclusivo para esta tabela. Obrigatório apenas quando entity_type é fact.
breakdowns Opcional:colunas de detalhamento (separadas por vírgulas) para endpoints de insights. Aplicável apenas quando entity_type é fact.
action_breakdowns Opcional:colunas de detalhamento de ações (separadas por vírgula) para endpoints de insights. Aplicável apenas quando entity_type é fact.
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 que essa tabela seja agrupada para fins de performance. Para mais informações, consulte Configurações do cluster.

De bruto para tabelas de CDC

Esta seção descreve as entradas que 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 Meta, conforme mencionado.

Os parâmetros a seguir 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 da CDC armazena os dados brutos após a transformação da CDC (por exemplo, campaign_insights).
row_identifiers Colunas (separadas por vírgulas) que formam um registro exclusivo para esta tabela.
load_frequency Com que frequência um DAG para essa entidade é executado para preencher a tabela do CDC. Para mais informações sobre os possíveis valores, 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 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.

Esquema da tabela CDC

No caso de Meta, todos os campos são armazenados no formato de string na camada bruta. Na camada 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 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 cdc.

Configurações de relatórios

É possível configurar e controlar como o Cortex gera dados para a camada de relatórios final do 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 Como personalizar o arquivo de configurações de relatórios.

A seguir