Référence du connecteur d'ingestion 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.

Cette page contient des documents de référence pour le connecteur d'ingestion Meta Ads dans Databricks Lakeflow Connect.

Transformations de données automatiques

Databricks transforme les types de données Meta Ads en types de données compatibles Delta comme suit :

Type d'annonces Meta	Type Delta
chaîne	Chaîne
int	Entier
long	Long
Présentation libre	Présentation libre
double	Double
booléen	Booléen
Date-heure	Horodatage
Date	Date
Liste	Tableau
Carte	Carte
énumération	Chaîne

Type d'annonces Meta	Type Delta
chaîne	Chaîne
int	Entier
long	Long
Présentation libre	Présentation libre
double	Double
booléen	Booléen
Date-heure	Horodatage
Date	Date
Liste	Tableau
Carte	Carte
énumération	Chaîne

Objets pris en charge

Le connecteur Meta Ads prend en charge l'ingestion des objets suivants :

Objet	Description
publicités	Annonces individuelles dans vos campagnes
ad_sets	Ensembles d’annonces qui regroupent les annonces avec des paramètres de ciblage, de budget et de planification partagés
campagnes	Objets de campagne de niveau supérieur qui contiennent des groupes d'annonces
images publicitaires	Assets d'image utilisés dans les annonces
ad_insights	Mesures de performance et données analytiques pour les publicités, les ensembles de publicités, les campagnes ou les comptes
ad_creatives	Éléments créatifs (images, vidéos, texte) utilisés dans les publicités.
custom_audiences	Définitions d'audience personnalisées pour le ciblage
ad_videos	Ressources vidéo utilisées dans les publicités
custom_conversions	Définitions d'événements de conversion personnalisées
Rapports pré-établis (21 tables)	Variantes ad_insights prêtes à l'emploi avec une configuration fixe par rapport.
rapport personnalisé	Rapport d'insights défini par l'utilisateur. Configurez le rapport avec custom_report_options et nommez la sortie avec destination_table.

Objet	Description
publicités	Annonces individuelles dans vos campagnes
ad_sets	Ensembles d’annonces qui regroupent les annonces avec des paramètres de ciblage, de budget et de planification partagés
campagnes	Objets de campagne de niveau supérieur qui contiennent des groupes d'annonces
images publicitaires	Assets d'image utilisés dans les annonces
ad_insights	Mesures de performance et données analytiques pour les publicités, les ensembles de publicités, les campagnes ou les comptes
ad_creatives	Éléments créatifs (images, vidéos, texte) utilisés dans les publicités.
custom_audiences	Définitions d'audience personnalisées pour le ciblage
ad_videos	Ressources vidéo utilisées dans les publicités
custom_conversions	Définitions d'événements de conversion personnalisées
Rapports pré-établis (21 tables)	Variantes ad_insights prêtes à l'emploi avec une configuration fixe par rapport.
rapport personnalisé	Rapport d'insights défini par l'utilisateur. Configurez le rapport avec custom_report_options et nommez la sortie avec destination_table.

Options de configurationad_insights

L'objet ad_insights prend en charge des options de configuration supplémentaires pour l'analyse des données de performance.

start Date de début

Définissez la date la plus ancienne à partir de laquelle ingérer les données historiques ad_insights. L'API Insights ne conserve les données que pendant environ 36 mois, donc start_date doit se situer dans les 36 derniers mois. S'il n'est pas défini, le connecteur est default 36 mois avant la date actuelle.

Niveaux de granularité

Spécifiez le niveau auquel récupérer les indicateurs de performance :

• account: métriques au niveau du compte
• campaign: Métriques au niveau de la campagne
• adset: Métriques au niveau du groupe d'annonces
• ad: Métriques au niveau de l'annonce (default)

Dimensions de répartition

Configurez les dimensions de répartition pour segmenter les données de performances :

• age: Plages d’âge
• gender: Genre
• country: Pays
• region: Région géographique
• dma: Zone de marché désignée (États-Unis uniquement)
• device_platform: Plateforme de l'appareil (mobile, ordinateur de bureau, etc.)
• placement: Emplacement de placement d'annonces
• publisher_platform: Plateforme de publication (Facebook, Audience Network, etc.)
• impression_device: Type de périphérique pour les impressions

Dimensions de répartition des actions

Configurez les dimensions de répartition des actions pour analyser les actions de conversion :

• action_type: Type d'action de conversion
• action_destination: destination de l'action de conversion
• action_carousel_card_id: Identifiant de carte carrousel
• action_carousel_card_name: Nom de la carte du carrousel
• action_video_sound: Paramètre audio vidéo
• action_video_type: Type de vidéo

Incrément de temps

Configurez la période d'agrégation pour les données ad_insights :

• all_days: Un seul bucket couvrant toute la plage temporelle (par default de l’API Insights).
• monthly: Un compartiment par mois calendaire.
• Un nombre entier de jours sous forme de chaîne (par exemple, "1" pour les compartiments quotidiens, "7" pour les compartiments hebdomadaires).

L'API Insights ne prend pas en charge les incéments de temps horaires.

Heure du rapport d'activité

Configurez le Timestamp utilisé pour rapporter les statistiques d'action :

• impressionLes conversions sont signalées à la date de l'impression qui les a générées.
• conversion: Les conversions sont signalées à la date à laquelle elles se sont produites.
• mixed: les conversions par clic utilisent l'heure d'impression, les conversions après affichage utilisent l'heure de conversion.
• lifetime: conversions Lifetime pour l'entité.

Fenêtres d'attribution

Configurer les fenêtres d'attribution pour les actions.

• 1d_click, 7d_click: fenêtres d'attribution de clics
• 1d_view: Fenêtre d'attribution post-affichage
• 7d_view, 28d_view: Fenêtres d'attribution post-affichage. Obsolète par Meta et n'est plus pris en charge par le connecteur.

Vous pouvez spécifier plusieurs valeurs (par exemple, ["7d_click", "1d_view"]). Si action_attribution_windows n'est pas défini, le connecteur utilise les paramètres d'attribution default de votre compte Meta Ads. Pour une liste de valeurs, consultez la référence de l'API Meta Insights.

Fenêtre de rétrospection

Configurez l'historique de réingestion des données par le connecteur (en jours) à chaque synchronisation. La fenêtre de rétrospection s'applique à ad_insights, custom_report et aux rapports prédéfinis. S'il n'est pas défini, il est de 7 jours default.

• Réingestion sur plage temporelle : à chaque synchronisation après la première, le connecteur extrait les données pour [last_sync_cursor - <N> days, today] afin que les conversions arrivant en retard soient capturées. Si custom_insights_lookback_window n'est pas défini, le connecteur réingère les 7 derniers jours par default.
• Fallback d'attribution : Lorsque vous définissez custom_insights_lookback_window explicitement et que vous n'avez pas défini action_attribution_windows, le connecteur transmet également <N>d_click,1d_view comme fenêtre d'attribution à l'API Insights. Pour contrôler l'attribution indépendamment de la fenêtre rétrospective, définissez action_attribution_windows.

Rapports prédéfinis

Les rapports prédéfinis sont des variantes ad_insights prêtes à l'emploi. Chaque rapport prédéfini émet un appel Meta /insights avec une combinaison fixe de niveau, de répartition et de répartition par action — aucune configuration n'est requise. Contrairement à ad_insights, les rapports prédéfinis ne sont pas configurables.

Pour ingérer un rapport pré-établi, définissez source_table sur le nom du rapport. connector_options sont facultatifs. Un rapport pré-établi s'exécute sans (en utilisant les default), mais vous pouvez définir start_date dans meta_ads_options pour contrôler la plage de dates.

Rapports prédéfinis disponibles

Chaque rapport préconfiguré correspond à une requête Meta /insights fixe.

Rapport (source_table)	Catégorie	Niveau	Répartitions	Répartitions des actions	Ensemble de métriques
basic_ad_report	Basique	ad	—	action_type	Métriques principales.
basic_ad_set_report	Basique	adset	—	action_type	Métriques principales.
basic_campaign_report	Basique	campaign	—	action_type	Métriques principales.
basic_all_levels_report	Basique	ad	—	action_type	Métriques principales (avec les noms d'annonces, d'ensembles d'annonces et de campagnes)
delivery_device_report	Livraison	ad	device_platform	action_type	Métriques principales.
delivery_platform_report	Livraison	ad	publisher_platform	action_type	Métriques principales.
delivery_platform_and_device_report	Livraison	ad	publisher_platform, device_platform	action_type	Métriques principales.
delivery_purchase_roas_report	Livraison	ad	—	action_type	Conversion / ROAS
demographics_age_report	Données démographiques	ad	age	action_type	Métriques principales.
demographics_gender_report	Données démographiques	ad	gender	action_type	Métriques principales.
demographics_age_and_gender_report	Données démographiques	ad	age, gender	action_type	Métriques principales.
demographics_country_report	Données démographiques	ad	country	action_type	Métriques principales.
demographics_region_report	Données démographiques	ad	region	action_type	Métriques principales.
demographics_dma_region_report	Données démographiques	ad	comscore_market	action_type	Métriques principales.
action_canvas_component_report	Action	ad	—	action_type	Conversion / ROAS
action_carousel_card_report	Action	ad	—	action_carousel_card_id, action_carousel_card_name	Conversion / ROAS
action_conversion_device_report	Action	ad	device_platform	action_type	Conversion / ROAS
action_product_id_report	Action	ad	product_id	action_type	Conversion / ROAS
action_reactions_report	Action	ad	—	action_reaction	actions, action_values
action_video_sound_report	Action	ad	—	action_video_sound	Engagement vidéo
action_video_view_type_report	Action	ad	—	action_video_type	Engagement vidéo

Rapport (source_table)	Catégorie	Niveau	Répartitions	Répartitions des actions	Ensemble de métriques
basic_ad_report	Basique	ad	—	action_type	Métriques principales.
basic_ad_set_report	Basique	adset	—	action_type	Métriques principales.
basic_campaign_report	Basique	campaign	—	action_type	Métriques principales.
basic_all_levels_report	Basique	ad	—	action_type	Métriques principales (avec les noms d'annonces, d'ensembles d'annonces et de campagnes)
delivery_device_report	Livraison	ad	device_platform	action_type	Métriques principales.
delivery_platform_report	Livraison	ad	publisher_platform	action_type	Métriques principales.
delivery_platform_and_device_report	Livraison	ad	publisher_platform, device_platform	action_type	Métriques principales.
delivery_purchase_roas_report	Livraison	ad	—	action_type	Conversion / ROAS
demographics_age_report	Données démographiques	ad	age	action_type	Métriques principales.
demographics_gender_report	Données démographiques	ad	gender	action_type	Métriques principales.
demographics_age_and_gender_report	Données démographiques	ad	age, gender	action_type	Métriques principales.
demographics_country_report	Données démographiques	ad	country	action_type	Métriques principales.
demographics_region_report	Données démographiques	ad	region	action_type	Métriques principales.
demographics_dma_region_report	Données démographiques	ad	comscore_market	action_type	Métriques principales.
action_canvas_component_report	Action	ad	—	action_type	Conversion / ROAS
action_carousel_card_report	Action	ad	—	action_carousel_card_id, action_carousel_card_name	Conversion / ROAS
action_conversion_device_report	Action	ad	device_platform	action_type	Conversion / ROAS
action_product_id_report	Action	ad	product_id	action_type	Conversion / ROAS
action_reactions_report	Action	ad	—	action_reaction	actions, action_values
action_video_sound_report	Action	ad	—	action_video_sound	Engagement vidéo
action_video_view_type_report	Action	ad	—	action_video_type	Engagement vidéo

Chaque rapport prédéfini utilise l'un des trois jeux de métriques, qui déterminent les colonnes incluses dans le résultat :

Ensemble de métriques	Colonnes
Métriques principales.	reach, impressions, frequency, spend, cpm, cpc, cost_per_inline_link_click, ctr, inline_link_click_ctr, inline_link_clicks, actions, cost_per_action_type (tableau)
Conversion / ROAS	inline_link_clicks, outbound_clicks, website_purchase_roas, mobile_app_purchase_roas (tableau)
Engagement vidéo	video_thruplay_watched_actions, video_30_sec_watched_actions, video_p25_watched_actions, video_p50_watched_actions, video_p75_watched_actions, video_p100_watched_actions, video_avg_time_watched_actions (tableau)

Ensemble de métriques	Colonnes
Métriques principales.	reach, impressions, frequency, spend, cpm, cpc, cost_per_inline_link_click, ctr, inline_link_click_ctr, inline_link_clicks, actions, cost_per_action_type (tableau)
Conversion / ROAS	inline_link_clicks, outbound_clicks, website_purchase_roas, mobile_app_purchase_roas (tableau)
Engagement vidéo	video_thruplay_watched_actions, video_30_sec_watched_actions, video_p25_watched_actions, video_p50_watched_actions, video_p75_watched_actions, video_p100_watched_actions, video_avg_time_watched_actions (tableau)

Colonnes de sortie

Chaque ligne de rapport prédéfini inclut date_start, date_stop, account_id, les colonnes d'entité et de hiérarchie du rapport (par exemple ad_id, adset_id, campaign_id, et les noms le cas échéant), toute colonne de répartition (par exemple age, device_platform), la breakdown_hash dérivée et la clé primaire insight_id. Les colonnes de métrique dépendent de l'ensemble de métriques du rapport. Les colonnes Action et ROAS sont de type array<string>.

Comportement du rapport préconfiguré

• Chaque ligne est identifiée de manière unique par insight_id. Le connecteur synchronise les données de manière incrémentielle, en utilisant date_stop comme curseur.
• La configuration du rapport — level, breakdowns, action_breakdowns, time_increment (quotidien), fenêtres d'attribution (7d_click, 1d_view) et action_report_time (mixed) — est fixe par rapport et ne peut pas être remplacée à l'aide de meta_ads_options.
• Vous pouvez éventuellement définir start_date (default : 36 mois avant aujourd’hui) et custom_insights_lookback_window (default : 7 jours) dans meta_ads_options.

Options de configurationcustom_report

custom_report vous permet de définir votre propre rapport de style ad_insightsavec une combinaison de niveau, de répartition et de répartition par action personnalisée et de l'ingérer dans une table que vous nommez. Utilisez-le lorsque aucun rapport prédéfini ne correspond à vos besoins et que vous souhaitez avoir un contrôle total sur la configuration /insights.

Pour ingérer un rapport personnalisé, définissez source_table sur custom_report, choisissez un nom de destination_table et configurez le rapport sous connector_options.meta_ads_options.custom_report_options. Vous pouvez ajouter plusieurs objets custom_report à un pipeline, chacun avec un destination_table distinct.

Structure de l'objet :

JSON

{
  "table": {
    "source_schema": "<meta-ads-account-id>",
    "source_table": "custom_report",
    "destination_catalog": "<catalog>",
    "destination_schema": "<schema>",
    "destination_table": "<your-report-name>",
    "connector_options": {
      "meta_ads_options": {
        "start_date": "<YYYY-MM-DD>",
        "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"]
        }
      }
    }
  }
}

custom_report_options

Chaque option reflète l'option ad_insights correspondante :

Option	Description
level	Granularité : account, campaign, adset, ou ad.
breakdowns	Dimensions qui segmentent toutes les métriques (par exemple, ["country", "age"]).
action_breakdowns	Dimensions qui segmentent les métriques d'action/conversion (par exemple, ["action_type"]).
time_increment	Période d'agrégation : all_days, monthly ou un nombre entier de jours sous forme de chaîne (par exemple, "1" pour quotidien).
action_report_time	Lorsque les actions sont comptées : impression, conversion, mixed ou lifetime.
action_attribution_windows	Fenêtres d'attribution pour les actions (par exemple, ["7d_click", "1d_view"]).

Option	Description
level	Granularité : account, campaign, adset, ou ad.
breakdowns	Dimensions qui segmentent toutes les métriques (par exemple, ["country", "age"]).
action_breakdowns	Dimensions qui segmentent les métriques d'action/conversion (par exemple, ["action_type"]).
time_increment	Période d'agrégation : all_days, monthly ou un nombre entier de jours sous forme de chaîne (par exemple, "1" pour quotidien).
action_report_time	Lorsque les actions sont comptées : impression, conversion, mixed ou lifetime.
action_attribution_windows	Fenêtres d'attribution pour les actions (par exemple, ["7d_click", "1d_view"]).

Partagé meta_ads_options

Option	Description	Default lorsqu’il n’est pas défini
start_date	Date d'ingestion la plus ancienne, AAAA-MM-JJ.	36 mois avant la date actuelle
custom_insights_lookback_window	Nombre de jours pour une nouvelle ingestion à chaque synchronisation ultérieure (capture les conversions tardives).	7 jours

Option	Description	Default lorsqu’il n’est pas défini
start_date	Date d'ingestion la plus ancienne, AAAA-MM-JJ.	36 mois avant la date actuelle
custom_insights_lookback_window	Nombre de jours pour une nouvelle ingestion à chaque synchronisation ultérieure (capture les conversions tardives).	7 jours

Vous devez définir destination_table sur l'objet table afin que plusieurs rapports personnalisés puissent coexister dans un même pipeline.

Chaque ligne est identifiée de manière unique par insight_id. Le connecteur synchronise les données de manière incrémentielle, en utilisant date_stop comme curseur.

Versions de l'API

Le connecteur Meta Ads utilise l'API Marketing Meta (Graph API). Databricks maintient le connecteur à jour avec la dernière version stable de l'API.