Ingérer les données de Meta Ads

info

Bêta

Cette fonctionnalité est en Bêta. Les administrateurs du Workspace peuvent contrôler l'accès à cette fonctionnalité à partir de la page Previews . Consultez Gérer les aperçus Databricks.

Découvrez comment créer un pipeline d'ingestion géré pour ingérer des données de Meta Ads dans Databricks. Pour une liste des objets pris en charge, consultez Objets pris en charge.

Exigences

• Pour créer un pipeline d'ingestion, vous devez remplir les conditions suivantes :

  • Votre workspace doit être activé pour Unity Catalog.

  • Le compute Serverless doit être activé pour votre Workspace. Consultez les exigences du compute Serverless.

  • Pour créer une nouvelle connexion, vous devez disposer des privilèges CREATE CONNECTION sur le métastore. Voir Gérer les privilèges dans Unity Catalog.

    Si le connecteur prend en charge la création de pipelines basée sur l'interface utilisateur, un administrateur peut créer la connexion et le pipeline en même temps en suivant les étapes décrites sur cette page. Cependant, si les utilisateurs qui créent des pipelines utilisent la création de pipelines basée sur l'API ou ne sont pas des utilisateurs administrateurs, un administrateur doit d'abord créer la connexion dans l'Explorateur de catalogues. Voir Connexion aux sources d'ingestion gérées.

  • Pour utiliser une connexion existante, vous devez avoir les privilèges USE CONNECTION ou ALL PRIVILEGES sur l'objet de connexion.

  • Vous devez disposer de privilèges USE CATALOG sur le catalogue cible.

  • Vous devez disposer des privilèges USE SCHEMA et CREATE TABLE sur un schéma existant ou des privilèges CREATE SCHEMA sur le catalogue cible.

• Pour ingérer des données depuis Meta Ads, vous devez suivre les étapes de Configurer Meta Ads comme source de données.

Créez un pipeline d'ingestion

Declarative Automation Bundles

Cet tab décrit comment déployer un pipeline d'ingestion à l'aide des Declarative Automation Bundles. Les bundles peuvent contenir des définitions YAML de jobs et de tâches, sont gérés à l’aide de la Databricks CLI, et peuvent être partagés et exécutés dans différents Workspace cibles (comme le développement, la pré-production et la production). Pour plus d'informations, consultez What are Declarative Automation Bundles?.

1. Créez un bundle à l'aide de la CLI Databricks :

   Bash

   databricks bundle init

2. Ajoutez deux nouveaux fichiers de ressources au bundle :

   • Un fichier de définition de pipeline (par exemple, resources/meta_ads_pipeline.yml). Voir pipeline.ingestion_definition et Exemples.
   • Un fichier de définition de Job qui contrôle la fréquence d'ingestion des données (par exemple, resources/meta_ads_job.yml). Consultez le fichier de définition de Job des Declarative Automation Bundles.

3. Déployez le pipeline à l'aide de la CLI Databricks :

   Bash

   databricks bundle deploy

Databricks notebook

1. Importez le notebook suivant dans votre Databricks Workspace :

Ouvrir le notebook dans un nouvel ongletOuvrir dans Databricks

2. Laisser la cellule un telle quelle.

3. Modifiez la troisième cellule avec les détails de configuration de votre pipeline. Voir pipeline.ingestion_definition et Exemples.

4. Cliquez sur Tout exécuter .

ad_insights configuration

Lorsque vous ingérez depuis ad_insights, vous devez configurer meta_ads_options dans le connector_options pour la table ou le schéma :

Valeur	Description
level	Facultatif. Niveau de granularité pour les insights : account, campaign, adset, ou ad. default est ad.
start_date	Facultatif. La date de start pour les données insight au format YYYY-MM-DD. Doit être au cours des 36 derniers mois. S'il n'est pas défini, le connecteur utilise par default les 36 mois précédant la date actuelle.
breakdowns	Facultatif. Liste des dimensions de répartition (par ex., ["age", "gender", "country"]).
action_breakdowns	Facultatif. Liste des dimensions de répartition des actions (par exemple, ["action_type", "action_destination"]).
action_attribution_windows	Facultatif. Liste des fenêtres d'attribution utilisées pour signaler les statistiques d'action (par exemple, ["7d_click", "1d_view"]). S'il n'est pas défini, le connecteur utilise les paramètres d'attribution par default de votre compte Meta Ads. Consultez les fenêtres d'attribution pour connaître les valeurs prises en charge.
action_report_time	Facultatif. Détermine le timestamp utilisé pour signaler les statistiques d'action : impression, conversion, mixed et lifetime. Par exemple, avec impression, le connecteur signale une conversion à la date de l'impression qui l'a générée. Avec conversion, il signale une conversion à la date à laquelle elle s'est produite.
time_increment	Facultatif. Période d'agrégation pour les statistiques renvoyées : all_days, monthly, ou un nombre entier de jours (de 1 à 90) sous forme de chaîne de caractères (par exemple, "1" pour les compartiments quotidiens, "7" pour les compartiments hebdomadaires). Si non défini, la valeur default de all_days de l'API Insights est utilisée.
custom_insights_lookback_window	Facultatif. Nombre de jours à réingérer lors de chaque synchronisation ultérieure pour capturer les conversions à arrivée tardive. S'il n'est pas défini, le connecteur réingère les 7 derniers jours. Lorsqu'il est défini explicitement et que action_attribution_windows n'est pas défini, cette valeur est également utilisée pour dériver la fenêtre d'attribution envoyée à Meta en tant que <N>d_click,1d_view.

Valeur	Description
level	Facultatif. Niveau de granularité pour les insights : account, campaign, adset, ou ad. default est ad.
start_date	Facultatif. La date de start pour les données insight au format YYYY-MM-DD. Doit être au cours des 36 derniers mois. S'il n'est pas défini, le connecteur utilise par default les 36 mois précédant la date actuelle.
breakdowns	Facultatif. Liste des dimensions de répartition (par ex., ["age", "gender", "country"]).
action_breakdowns	Facultatif. Liste des dimensions de répartition des actions (par exemple, ["action_type", "action_destination"]).
action_attribution_windows	Facultatif. Liste des fenêtres d'attribution utilisées pour signaler les statistiques d'action (par exemple, ["7d_click", "1d_view"]). S'il n'est pas défini, le connecteur utilise les paramètres d'attribution par default de votre compte Meta Ads. Consultez les fenêtres d'attribution pour connaître les valeurs prises en charge.
action_report_time	Facultatif. Détermine le timestamp utilisé pour signaler les statistiques d'action : impression, conversion, mixed et lifetime. Par exemple, avec impression, le connecteur signale une conversion à la date de l'impression qui l'a générée. Avec conversion, il signale une conversion à la date à laquelle elle s'est produite.
time_increment	Facultatif. Période d'agrégation pour les statistiques renvoyées : all_days, monthly, ou un nombre entier de jours (de 1 à 90) sous forme de chaîne de caractères (par exemple, "1" pour les compartiments quotidiens, "7" pour les compartiments hebdomadaires). Si non défini, la valeur default de all_days de l'API Insights est utilisée.
custom_insights_lookback_window	Facultatif. Nombre de jours à réingérer lors de chaque synchronisation ultérieure pour capturer les conversions à arrivée tardive. S'il n'est pas défini, le connecteur réingère les 7 derniers jours. Lorsqu'il est défini explicitement et que action_attribution_windows n'est pas défini, cette valeur est également utilisée pour dériver la fenêtre d'attribution envoyée à Meta en tant que <N>d_click,1d_view.

Exemples

Utilisez ces exemples pour configurer votre pipeline.

Ingérer toutes les tables actuelles et futures d'un compte

Declarative Automation Bundles

Voici un exemple de fichier de définition de pipeline :

YAML

resources:
  pipelines:
    pipeline_meta_ads:
      name: <pipeline-name>
      catalog: <destination-catalog>
      target: <destination-schema>
      channel: PREVIEW
      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

Voici un exemple de spécification de pipeline :

Python

pipeline_spec = {
  "name": "<pipeline-name>",
  "catalog": "<destination-catalog>",
  "schema": "<destination-schema>",
  "channel": "PREVIEW",
  "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)

Sélectionnez des tables spécifiques d'un compte à ingérer.

Declarative Automation Bundles

Voici un exemple de fichier de définition de pipeline :

YAML

resources:
  pipelines:
    pipeline_meta_ads:
      name: <pipeline-name>
      catalog: <destination-catalog>
      target: <destination-schema>
      channel: PREVIEW
      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

Voici un exemple de spécification de pipeline :

Python

pipeline_spec = {
  "name": "<pipeline-name>",
  "catalog": "<destination-catalog>",
  "schema": "<destination-schema>",
  "channel": "PREVIEW",
  "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)

Ingérer ad_insights avec meta_ads_options

Declarative Automation Bundles

Voici un exemple de fichier resources/meta_ads_pipeline.yml :

YAML

resources:
  pipelines:
    pipeline_meta_ads:
      name: <pipeline-name>
      catalog: <destination-catalog>
      target: <destination-schema>
      channel: PREVIEW
      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>",
  "channel": "PREVIEW",
  "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)

Fichier de définition de job Declarative Automation Bundles

Declarative Automation Bundles

Voici un exemple de fichier de définition de job à utiliser avec les Declarative Automation Bundles. Le job s'exécute tous les jours, exactement un jour après la dernière exécution.

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}

Ingérer un rapport préconfiguré

Définir source_table sur le nom du rapport. Les connector_options sont facultatifs pour les rapports préconfigurés. L'exemple suivant définit start_date pour contrôler la plage de dates. Omettez connector_options pour utiliser les valeurs par default.

Declarative Automation Bundles

Voici un exemple de fichier de définition de pipeline :

YAML

resources:
  pipelines:
    pipeline_meta_ads:
      name: <pipeline-name>
      catalog: <destination-catalog>
      target: <destination-schema>
      channel: PREVIEW
      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>",
  "channel": "PREVIEW",
  "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)

Pour la liste complète des rapports prédéfinis disponibles, consultez Rapports prédéfinis.

Ingérer un rapport personnalisé

Définissez source_table sur custom_report, indiquez un nom destination_table et définissez la configuration sous connector_options.meta_ads_options.custom_report_options. Vous devez définir destination_table pour que plusieurs rapports personnalisés puissent coexister dans un seul 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"]
              }
            }
          }
        }
      }
    ]
  }
}

Pour les options de configuration, consultez les options de configuration decustom_report.

Modèles courants

Pour les configurations de pipeline avancées, consultez Modèles courants pour les pipelines d'ingestion gérés.

Étapes suivantes

start, planifiez et configurez des alertes sur votre pipeline. Consultez les Tâches de maintenance courantes du pipeline.

Ressources supplémentaires

• Limitations du connecteur d'ingestion Meta Ads
• Résoudre les problèmes d'ingestion de Meta Ads
• Référence du connecteur d'ingestion Meta Ads
• FAQ du connecteur d'ingestion Meta Ads