Integração com a Meta

Esta página descreve as configurações necessárias para importar dados da Meta (anúncios do Facebook e Instagram) como origem de dados da carga de trabalho de marketing da Data Foundation do Cortex Framework.

A Meta é uma empresa tecnológica proprietária de várias plataformas online populares. O Cortex Framework integra dados dos anúncios do Instagram e Facebook para os analisar, combiná-los com outras origens de dados e usar a IA para obter estatísticas mais detalhadas e otimizar a sua estratégia de marketing.

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

Origem dos metadados

Figura 1. Origem de dados de marketing da Meta.

Ficheiro de configuração

O ficheiro config.json configura as definições necessárias para estabelecer ligação a origens de dados para transferir dados de várias cargas de trabalho. Este ficheiro contém os seguintes parâmetros para o Meta:

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

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

Parâmetro Significado Valor predefinido Descrição
marketing.deployMeta Implemente o Meta true Execute a implementação para a origem de dados da Meta.
marketing.Meta.deployCDC Implemente scripts de CDC para a Meta true Gere scripts de processamento de CDC da Meta para executar 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 não processados para a Meta Conjunto de dados não processados 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 secção descreve o modelo de dados da Meta através do diagrama de relação entre entidades (ERD).

Diagrama de relação entre entidades para a Meta

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

Visualizações de base

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

Ligação à API

Os modelos de carregamento no Cortex Framework para Meta usam a API Meta Marketing para obter atributos e métricas de relatórios. Os modelos atuais usam a versão v21.0.

A Meta impõe um limite de velocidade dinâmico quando consulta a API Marketing. Quando o limite de taxa é atingido, os DAGs de carregamento de origem para dados não processados podem não ser concluídos com êxito. Nestes casos, pode ver mensagens de erro relevantes no registo e a execução seguinte dos DAGs carregaria retroativamente os dados em falta.

A API Meta Marketing tem dois níveis de acesso: básico e padrão. O nível Standard oferece um limite muito mais elevado e é recomendado se planear usar a carregamento de dados de origem para dados não processados extensivamente. Para mais detalhes sobre estes limites e como alcançar um nível de acesso superior, consulte a documentação da Meta.

Se tiver acesso ao nível Standard, pode diminuir o valor da next_request_delay_sec definição em src/Meta/src/raw/pipelines/config.ini para tempos de carregamento mais rápidos.

Acesso à API e token de acesso

Os passos seguintes são necessários no Meta Business Manager e na consola do programador para transferir com êxito dados do Meta para o Cortex Framework.

  1. Identifique uma app a usar. Pode criar uma nova app associada à conta empresarial. Certifique-se de que a sua app é do tipo Business.
  2. Configurar autorizações da app. Tem de ter a função de administrador atribuída à app para poder criar tokens com a mesma. Consulte a documentação sobre as funções da app. Certifique-se de que atribui recursos (contas) relevantes à sua app.

  3. Crie um token de acesso. Os tokens de acesso são necessários para aceder à API Meta Marketing e estão sempre associados a uma app e a um utilizador. Pode criar o token com um utilizador do sistema ou com o seu próprio início de sessão.

    1. Crie um utilizador do sistema administrador.
    2. Gere um token. Certifique-se de que anota os tokens assim que são gerados, uma vez que não são recuperáveis depois de sair da página.
    3. Conceda as autorizações ads_read e business_management ao seu token para aceder aos objetos suportados.

  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 gerou no passo anterior como conteúdo.

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.

Com a API Meta Marketing, a maioria dos dados (exceto conversões) está disponível quase em tempo real, embora possam ser ajustados até 28 dias após o evento.

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
meta_raw_dataflow Para a API Meta Marketing > conjunto de dados não processados do BigQuery
meta_cdc_bq Para o conjunto de dados não processados > Transferência do conjunto de dados de CDC
meta_reporting_bq Para o conjunto de dados do CDC > Transferência do conjunto de dados de relatórios

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 associação meta_raw_dataflow). Consulte as instruções na documentação do Dataflow. A conta de serviço também requer a autorização de Secret Manager Secret Accessor. Consulte os detalhes na documentação de controlo de acesso.

Parâmetros do pedido

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

Definições de carregamento

Controle os pipelines de dados Source to Raw e Raw to CDC através das definições no ficheiro src/Meta/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 tem entradas que controlam as entidades obtidas pelas APIs e como. Cada entrada corresponde a uma entidade da API Meta Marketing. Com base nesta configuração, a estrutura Cortex cria DAGs do Airflow que executam pipelines do Dataflow para obter dados através das APIs Meta Marketing.

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

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

Parâmetro Descrição
base_table Tabela no conjunto de dados não processados onde os dados obtidos são armazenados (por exemplo, customer).
load_frequency Com que frequência um DAG para esta é executado para obter dados do Meta. Para mais informações sobre os valores possíveis, consulte a documentação do Airflow.
object_endpoint Caminho do ponto final da API (por exemplo, campaigns para o ponto final /{account_id}/campaigns).
entity_type Tipo de tabela (deve ser um dos seguintes: fact, dimension ou addaccount).
object_id_column Colunas (separadas por vírgulas) que formam um registo único para esta tabela. Só é necessário quando entity_type é fact.
breakdowns Opcional: colunas de discriminação (separadas por vírgula) para os pontos finais de estatísticas. Só aplicável quando entity_type é fact.
action_breakdowns Opcional: colunas de discriminação de ações (separadas por vírgula) para os pontos finais de estatísticas. Só aplicável quando entity_type é fact.
partition_details Opcional: se quiser que esta tabela seja particionada para ter em consideração o desempenho. Para mais informações, consulte o artigo Partição de tabelas.
cluster_details Opcional: se quiser que esta tabela seja agrupada para ter em conta o 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 as entradas que 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 Meta, conforme mencionado).

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

Parâmetro Descrição
base_table Tabela na qual os dados não processados foram replicados. Uma tabela com o mesmo nome no conjunto de dados de CDC armazena os dados não processados após a transformação de CDC (por exemplo, campaign_insights).
row_identifiers 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.
partition_details Opcional: se quiser que esta tabela seja particionada para ter em consideração 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.

Esquema da tabela de CDC

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

Para ativar esta conversão, o diretório src/Meta/config/table_schema contém um ficheiro de esquema para cada entidade especificada na secção raw_to_cdc_tables que explica como traduzir corretamente cada tabela não processada do BigQuery numa tabela de CDC.

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

  • SourceField: nome do campo da tabela não processada para esta entidade.
  • TargetField: nome da coluna na tabela cdc para esta entidade.
  • DataType: tipo de dados de cada campo da tabela de CDC.

Definições de relatórios

Pode configurar e controlar a forma como o Cortex gera dados para a camada de relatórios final da Meta através do ficheiro de definições de relatórios (src/Meta/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?