Ingerir dados de Meta Ads

info

Beta

Esse recurso está em Beta.

Aprenda como criar um pipeline de ingestão gerenciado para importar dados do Meta Ads para o Databricks. Para obter uma lista dos objetos suportados, consulte Objetos suportados.

Requisitos

• Para criar um pipeline de ingestão, você deve atender aos seguintes requisitos:

  • Seu workspace deve estar habilitado para o Unity Catalog.

  • compute sem servidor (serverless compute) deve estar habilitado para seu workspace. Consulte os requisitos compute sem servidor.

  • Para criar uma nova conexão, você deve ter os privilégios CREATE CONNECTION no metastore. Consulte Gerenciar privilégios no Unity Catalog.

    Se o conector suportar a criação pipeline baseada em interface de usuário, um administrador poderá criar a conexão e o pipeline simultaneamente, concluindo os passos desta página. No entanto, se os usuários que criam pipelines utilizarem a criação pipeline baseada em API ou não forem administradores, um administrador deverá primeiro criar a conexão no Catalog Explorer. Consulte Conectar para gerenciar fontes de ingestão.

  • Para usar uma conexão existente, você deve ter privilégios USE CONNECTION ou ALL PRIVILEGES no objeto de conexão.

  • Você deve ter privilégios USE CATALOG no catálogo de destino.

  • Você deve ter privilégios USE SCHEMA e CREATE TABLE em um esquema existente ou privilégios CREATE SCHEMA no catálogo de destino.

• Para ingerir dados do Meta Ads, você deve concluir os passos em Configurar o Meta Ads como fonte de dados.

Crie um pipeline de ingestão.

Declarative Automation Bundles

Esta tab descreve como implantar um pipeline de ingestão usando Declarative Automation Bundles. Os pacotes podem conter definições YAML de Job e tarefa, são gerenciados usando a CLI Databricks e podem ser compartilhados e executados em diferentes espaços de trabalho de destino (como desenvolvimento, teste e produção). Para mais informações, consulte O que são pacotes de automação declarativa?.

1. Crie um pacote usando a CLI do Databricks:

   Bash

   databricks bundle init

2. Adicione dois novos arquivos de recursos ao pacote:

   • Um arquivo de definição de pipeline (por exemplo, resources/meta_ads_pipeline.yml). Consulte pipeline.ingestion_definition e exemplos.
   • Um arquivo de definição de trabalho que controla a frequência de ingestão de dados (por exemplo, resources/meta_ads_job.yml). Consulte o arquivo de definição de tarefas dos Pacotes de Automação Declarativa.

3. Implante o pipeline usando a CLI Databricks :

   Bash

   databricks bundle deploy

Databricks notebook

1. Importe o seguinte Notebook para o seu workspace Databricks :

Abrir notebook em uma nova abaOpen in Databricks

2. Deixe a célula um como está.

3. Modifique a célula três com os detalhes da configuração do seu pipeline. Consulte pipeline.ingestion_definition e exemplos.

4. Clique em Executar tudo .

ad_insights configuração

Ao ingerir dados de ad_insights, você deve configurar meta_ads_options em connector_options para a tabela ou esquema:

Valor	Descrição
level	Opcional. Nível de granularidade para percepções: account, campaign, adset ou ad. O valor padrão é ad.
start_date	Opcional. A data de início dos dados de percepções no formato YYYY-MM-DD . Deve ter sido nos últimos 36 meses. Se não estiver definido, o conector assume por padrão 36 meses antes da data atual.
breakdowns	Opcional. Lista de dimensões de decomposição (por exemplo, ["age", "gender", "country"]).
action_breakdowns	Opcional. Lista de dimensões de detalhamento da ação (por exemplo, ["action_type", "action_destination"]).
action_attribution_windows	Opcional. Lista de janelas de atribuição usadas para relatar estatísticas de ação (por exemplo, ["7d_click", "1d_view"]). Se não estiver configurado, o conector usa as configurações de atribuição default da sua account Meta Ads. Consulte a seção Janelas de Atribuição para obter informações sobre os valores suportados.
action_report_time	Opcional. Determina o carimbo de data/hora usado para relatar as estatísticas de ação: impression, conversion, mixed e lifetime. Por exemplo, com impression, o conector reporta uma conversão na data da impressão que a gerou. Com conversion, ele reporta uma conversão na data em que ocorreu.
time_increment	Opcional. Período de agregação para as estatísticas retornadas: all_days, monthly ou um número inteiro de dias (de 1 a 90) como strings (por exemplo, "1" para intervalos diários, "7" para semanais). Se não estiver definido, o default API de suspeita all_days será usado.
custom_insights_lookback_window	Opcional. Número de dias para reingestão em cada sincronização subsequente para capturar conversões que chegam com atraso. Se não estiver definido, o conector reengere os últimos 7 dias. Quando definido explicitamente e action_attribution_windows não está definido, este valor também é usado para derivar a janela de atribuição enviada para Meta como <N>d_click,1d_view.

Valor	Descrição
level	Opcional. Nível de granularidade para percepções: account, campaign, adset ou ad. O valor padrão é ad.
start_date	Opcional. A data de início dos dados de percepções no formato YYYY-MM-DD . Deve ter sido nos últimos 36 meses. Se não estiver definido, o conector assume por padrão 36 meses antes da data atual.
breakdowns	Opcional. Lista de dimensões de decomposição (por exemplo, ["age", "gender", "country"]).
action_breakdowns	Opcional. Lista de dimensões de detalhamento da ação (por exemplo, ["action_type", "action_destination"]).
action_attribution_windows	Opcional. Lista de janelas de atribuição usadas para relatar estatísticas de ação (por exemplo, ["7d_click", "1d_view"]). Se não estiver configurado, o conector usa as configurações de atribuição default da sua account Meta Ads. Consulte a seção Janelas de Atribuição para obter informações sobre os valores suportados.
action_report_time	Opcional. Determina o carimbo de data/hora usado para relatar as estatísticas de ação: impression, conversion, mixed e lifetime. Por exemplo, com impression, o conector reporta uma conversão na data da impressão que a gerou. Com conversion, ele reporta uma conversão na data em que ocorreu.
time_increment	Opcional. Período de agregação para as estatísticas retornadas: all_days, monthly ou um número inteiro de dias (de 1 a 90) como strings (por exemplo, "1" para intervalos diários, "7" para semanais). Se não estiver definido, o default API de suspeita all_days será usado.
custom_insights_lookback_window	Opcional. Número de dias para reingestão em cada sincronização subsequente para capturar conversões que chegam com atraso. Se não estiver definido, o conector reengere os últimos 7 dias. Quando definido explicitamente e action_attribution_windows não está definido, este valor também é usado para derivar a janela de atribuição enviada para Meta como <N>d_click,1d_view.

Exemplos

Utilize esses exemplos para configurar seu pipeline.

Ingerir todas as tabelas atuais e futuras de uma account

Declarative Automation Bundles

Segue abaixo um exemplo de arquivo de definição de pipeline:

YAML

resources:
  pipelines:
    pipeline_meta_ads:
      name: <pipeline-name>
      catalog: <destination-catalog>
      target: <destination-schema>
      ingestion_definition:
        connection_name: <connection-name>
        objects:
          - schema:
              source_schema: <meta-ads-account-id>
              destination_catalog: <destination-catalog>
              destination_schema: <destination-schema>
              table_configuration:
                scd_type: SCD_TYPE_1

Databricks notebook

Segue abaixo um exemplo de especificação de pipeline:

Python

pipeline_spec = {
  "name": "<pipeline-name>",
  "catalog": "<destination-catalog>",
  "schema": "<destination-schema>",
  "ingestion_definition": {
    "connection_name": "<connection-name>",
    "objects": [
      {
        "schema": {
          "source_schema": "<meta-ads-account-id>",
          "destination_catalog": "<destination-catalog>",
          "destination_schema": "<destination-schema>",
          "table_configuration": {
            "scd_type": "SCD_TYPE_1"
          }
        }
      }
    ]
  }
}

json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

Selecione tabelas específicas de uma account para ingestão.

Declarative Automation Bundles

Segue abaixo um exemplo de arquivo de definição de pipeline:

YAML

resources:
  pipelines:
    pipeline_meta_ads:
      name: <pipeline-name>
      catalog: <destination-catalog>
      target: <destination-schema>
      ingestion_definition:
        connection_name: <connection-name>
        objects:
          - table:
              source_schema: <meta-ads-account-id>
              source_table: campaigns
              destination_catalog: <destination-catalog>
              destination_schema: <destination-schema>
              table_configuration:
                scd_type: SCD_TYPE_1
          - table:
              source_schema: <meta-ads-account-id>
              source_table: ads
              destination_catalog: <destination-catalog>
              destination_schema: <destination-schema>
              table_configuration:
                scd_type: SCD_TYPE_1

Databricks notebook

Segue abaixo um exemplo de especificação de pipeline:

Python

pipeline_spec = {
  "name": "<pipeline-name>",
  "catalog": "<destination-catalog>",
  "schema": "<destination-schema>",
  "ingestion_definition": {
    "connection_name": "<connection-name>",
    "objects": [
      {
        "table": {
          "source_schema": "<meta-ads-account-id>",
          "source_table": "campaigns",
          "destination_catalog": "<destination-catalog>",
          "destination_schema": "<destination-schema>",
          "table_configuration": {
            "scd_type": "SCD_TYPE_1"
          }
        }
      },
      {
        "table": {
          "source_schema": "<meta-ads-account-id>",
          "source_table": "ads",
          "destination_catalog": "<destination-catalog>",
          "destination_schema": "<destination-schema>",
          "table_configuration": {
            "scd_type": "SCD_TYPE_1"
          }
        }
      }
    ]
  }
}

json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

Ingerir ad_insights com meta_ads_options

Declarative Automation Bundles

Segue abaixo um exemplo de arquivo resources/meta_ads_pipeline.yml :

YAML

resources:
  pipelines:
    pipeline_meta_ads:
      name: <pipeline-name>
      catalog: <destination-catalog>
      target: <destination-schema>
      ingestion_definition:
        connection_name: <connection-name>
        objects:
          - table:
              source_schema: <meta-ads-account-id>
              source_table: ad_insights
              destination_catalog: <destination-catalog>
              destination_schema: <destination-schema>
              table_configuration:
                scd_type: SCD_TYPE_1
              connector_options:
                meta_ads_options:
                  level: ad
                  start_date: '2024-01-01'
                  breakdowns:
                    - age
                    - gender
                  action_breakdowns:
                    - action_type

Databricks notebook

Python

pipeline_spec = {
  "name": "<pipeline-name>",
  "catalog": "<destination-catalog>",
  "schema": "<destination-schema>",
  "ingestion_definition": {
    "connection_name": "<connection-name>",
    "objects": [
      {
        "table": {
          "source_schema": "<meta-ads-account-id>",
          "source_table": "ad_insights",
          "destination_catalog": "<destination-catalog>",
          "destination_schema": "<destination-schema>",
          "table_configuration": {
            "scd_type": "SCD_TYPE_1"
          },
          "connector_options": {
            "meta_ads_options": {
              "level": "ad",
              "start_date": "2024-01-01",
              "breakdowns": ["age", "gender"],
              "action_breakdowns": ["action_type"]
            }
          }
        }
      }
    ]
  }
}

json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

Arquivo de definição de tarefas do Declarative Automation Bundles

Declarative Automation Bundles

Segue abaixo um exemplo de arquivo de definição de tarefa para uso com pacotes de automação declarativa. A execução do trabalho ocorre todos os dias, exatamente um dia após a última execução.

YAML

resources:
  jobs:
    meta_ads_dab_job:
      name: meta_ads_dab_job

      trigger:
        periodic:
          interval: 1
          unit: DAYS

      email_notifications:
        on_failure:
          - <email-address>

      tasks:
        - task_key: refresh_pipeline
          pipeline_task:
            pipeline_id: ${resources.pipelines.pipeline_meta_ads.id}

Ingerir um relatório pré-construído

Defina source_table como o nome do relatório. connector_options são opcionais para relatórios predefinidos. O exemplo a seguir define start_date para controlar o intervalo de datas. Omita connector_options para usar os default.

Declarative Automation Bundles

Segue abaixo um exemplo de arquivo de definição de pipeline:

YAML

resources:
  pipelines:
    pipeline_meta_ads:
      name: <pipeline-name>
      catalog: <destination-catalog>
      target: <destination-schema>
      ingestion_definition:
        connection_name: <connection-name>
        objects:
          - table:
              source_schema: <meta-ads-account-id>
              source_table: demographics_age_report
              destination_catalog: <destination-catalog>
              destination_schema: <destination-schema>
              connector_options:
                meta_ads_options:
                  start_date: '2024-01-01'

Databricks notebook

Python

pipeline_spec = {
  "name": "<pipeline-name>",
  "catalog": "<destination-catalog>",
  "schema": "<destination-schema>",
  "ingestion_definition": {
    "connection_name": "<connection-name>",
    "objects": [
      {
        "table": {
          "source_schema": "<meta-ads-account-id>",
          "source_table": "demographics_age_report",
          "destination_catalog": "<destination-catalog>",
          "destination_schema": "<destination-schema>",
          "connector_options": {
            "meta_ads_options": { "start_date": "2024-01-01" }
          }
        }
      }
    ]
  }
}

json_payload = json.dumps(pipeline_spec, indent=2)
create_pipeline(json_payload)

Para obter a lista completa de relatórios predefinidos disponíveis, consulte Relatórios predefinidos.

Ingerir um relatório personalizado

Defina source_table como custom_report, forneça um nome destination_table e defina a configuração em connector_options.meta_ads_options.custom_report_options. É preciso definir destination_table para que vários relatórios personalizados possam coexistir em um pipeline.

JSON

{
  "ingestion_definition": {
    "connection_name": "<connection-name>",
    "objects": [
      {
        "table": {
          "source_schema": "<meta-ads-account-id>",
          "source_table": "custom_report",
          "destination_catalog": "<destination-catalog>",
          "destination_schema": "<destination-schema>",
          "destination_table": "country_breakdown_report",
          "connector_options": {
            "meta_ads_options": {
              "start_date": "2024-01-01",
              "custom_insights_lookback_window": 7,
              "custom_report_options": {
                "level": "ad",
                "breakdowns": ["country"],
                "action_breakdowns": ["action_type"],
                "time_increment": "1",
                "action_report_time": "mixed",
                "action_attribution_windows": ["7d_click", "1d_view"]
              }
            }
          }
        }
      }
    ]
  }
}

Para opções de configuração, consulte custom_report opções de configuração.

Padrões comuns

Para configurações avançadas pipeline , consulte Padrões comuns para gerenciar pipeline de ingestão.

Próximos passos

começar, programar e definir alerta em seu pipeline. Consulte Tarefa comum de manutenção pipeline.

Recursos adicionais

• Limitações do conector de ingestão de Meta Ads
• Solução de problemas na ingestão de Meta Ads
• Referência do conector de ingestão de Meta Ads
• Perguntas frequentes sobre o conector de ingestão de Meta Ads