Intégration à Meta

Cette page décrit les configurations requises pour importer des données depuis Meta (annonces Facebook et Instagram) en tant que source de données de la charge de travail marketing de la base de données Cortex Framework.

Meta est une entreprise technologique qui possède plusieurs plates-formes en ligne populaires. Cortex Framework intègre les données publicitaires d'Instagram et de Facebook pour les analyser, les combiner à d'autres sources de données et utiliser l'IA afin d'obtenir des insights plus précis et d'optimiser votre stratégie marketing.

Le schéma suivant décrit comment les données marketing Meta sont disponibles via la charge de travail marketing de Cortex Framework Data Foundation :

Source de métadonnées

Figure 1. Source de données marketing Meta.

Fichier de configuration

Le fichier config.json configure les paramètres requis pour se connecter aux sources de données afin de transférer les données de différentes charges de travail. Ce fichier contient les paramètres suivants pour Meta :

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

Le tableau suivant décrit la valeur de chaque paramètre marketing :

Paramètre	Signification	Valeur par défaut	Description
`marketing.deployMeta`	Déployer Meta	`true`	Exécutez le déploiement pour la source de données de Meta.
`marketing.Meta.deployCDC`	Déployer des scripts CDC pour Meta	`true`	Générez des scripts de traitement CDC Meta à exécuter en tant que DAG dans Cloud Composer.
`marketing.Meta.datasets.cdc`	Ensemble de données CDC pour Meta		Ensemble de données du CDC pour Meta.
`marketing.Meta.datasets.raw`	Ensemble de données brutes pour Meta		Ensemble de données brutes pour Meta.
`marketing.Meta.datasets.reporting`	Ensemble de données de reporting pour Meta	`"REPORTING_Meta"`	Ensemble de données de reporting pour Meta.

Modèle de données

Cette section décrit le modèle de données de Meta à l'aide du diagramme entité-relation (ERD).

Figure 2. Meta : diagramme des relations entre entités.

Vues de base

Il s'agit des objets bleus du diagramme entité-relation. Ce sont des vues sur les tables CDC avec des transformations minimales pour décompresser les structures de données complexes. Consultez les scripts dans src/marketing/src/Meta/src/reporting/ddls.

Vues de rapports

Il s'agit des objets verts du diagramme ERD. Ce sont des vues de reporting qui contiennent des métriques agrégées. Consultez les scripts dans src/marketing/src/Meta/src/reporting/ddls.

Connexion à l'API

Les modèles d'ingestion de Cortex Framework pour Meta utilisent l'API Meta Marketing pour récupérer les attributs et les métriques de reporting. Les modèles actuels utilisent la version 25.0.

Meta impose une limite de débit dynamique lorsque vous interrogez l'API Marketing. Lorsque la limite de fréquence est atteinte, il est possible que les DAG d'ingestion de Source to Raw ne se terminent pas correctement. Dans ce cas, vous pouvez voir les messages d'erreur correspondants dans le journal. La prochaine exécution des DAG chargera rétroactivement les données manquantes.

L'API Marketing Meta propose deux niveaux d'accès : de base et standard. Le niveau Standard offre une limite beaucoup plus élevée et est recommandé si vous prévoyez d'utiliser l'ingestion de la source vers le format brut de manière intensive. Pour en savoir plus sur ces limites et sur la façon d'atteindre un niveau d'accès supérieur, consultez la documentation de Meta.

Si vous avez accès au niveau Standard, vous pouvez réduire la valeur du paramètre next_request_delay_sec dans src/Meta/src/raw/pipelines/config.ini pour accélérer les temps de chargement.

Accès à l'API et jeton d'accès

Les étapes suivantes sont nécessaires dans Meta Business Manager et la console pour les développeurs pour importer correctement les données de Meta dans Cortex Framework.

Identifiez une application à utiliser. Vous pouvez créer une application connectée au compte d'entreprise. Assurez-vous que votre application est de type Business.
Configurez les autorisations des applications. Vous devez être attribué à l'application en tant qu'administrateur avant de pouvoir créer des jetons avec celle-ci. Consultez la documentation sur les rôles d'application. Assurez-vous d'attribuer les composants (comptes) appropriés à votre application.
Créez un jeton d'accès. Les jetons d'accès sont nécessaires pour accéder à l'API Meta Marketing. Ils sont toujours associés à une application et à un utilisateur. Vous pouvez créer le jeton avec un utilisateur système ou avec votre propre identifiant.
1. Créez un utilisateur système administrateur.
2. Générez un jeton. Veillez à noter vos jetons dès qu'ils sont générés, car vous ne pourrez plus les récupérer une fois que vous aurez quitté la page.
3. Accordez les autorisations ads_read et business_management à votre jeton pour accéder aux objets compatibles.
Remarque : Vous pouvez également créer un jeton d'accès utilisateur à l'aide de vos propres identifiants de connexion. Les jetons créés de cette manière ont le même accès à tous les comptes et pages que vous, sans avoir besoin de spécifications supplémentaires.
Suivez la documentation Cloud Composer pour activer Secret Manager dans Cloud Composer. Créez ensuite un secret nommé cortex_meta_access_token et stockez-y le jeton que vous avez généré à l'étape précédente.

Fraîcheur et délai des données

En règle générale, la fraîcheur des données pour les sources de données Cortex Framework est limitée par ce que permet la connexion en amont, ainsi que par la fréquence d'exécution de votre DAG. Ajustez la fréquence d'exécution de votre DAG pour l'adapter à la fréquence en amont, aux contraintes de ressources et à vos besoins commerciaux.

Avec l'API Meta Marketing, la plupart des données (à l'exception des conversions) sont disponibles en temps quasi réel, bien qu'elles puissent être ajustées jusqu'à 28 jours après l'événement.

Autorisations pour les connexions Cloud Composer

Créez les connexions suivantes dans Cloud Composer. Pour en savoir plus, consultez la documentation sur la gestion des connexions Airflow.

Nom de la connexion	Purpose
`meta_raw_dataflow`	Pour l'API Meta Marketing > Ensemble de données brutes BigQuery
`meta_cdc_bq`	Pour le transfert d'ensemble de données brutes > ensemble de données CDC
`meta_reporting_bq`	Pour l'ensemble de données CDC > Transfert d'ensemble de données de reporting

Autorisations du compte de service Cloud Composer

Accordez les autorisations Dataflow au compte de service utilisé dans Cloud Composer (tel que configuré dans la connexion meta_raw_dataflow). Consultez les instructions dans la documentation Dataflow. Le compte de service nécessite également l'autorisation Secret Manager Secret Accessor. Pour en savoir plus, consultez la documentation sur le contrôle des accès.

Paramètres de requête

Le répertoire src/Meta/config/request_parameters contient un fichier de spécification de requête API pour chaque entité extraite de l'API Meta Marketing. Chaque fichier de requête contient une liste de champs à extraire de l'API Marketing Meta, un champ par ligne. Pour en savoir plus, consultez la documentation de référence de l'API Meta Marketing.

Paramètres d'ingestion

Contrôlez les pipelines de données Source to Raw et Raw to CDC à l'aide des paramètres du fichier src/Meta/config/ingestion_settings.yaml. Cette section décrit les paramètres de chaque pipeline de données.

Source vers les tables brutes

Cette section contient des entrées qui contrôlent les entités récupérées par les API et la manière dont elles le sont. Chaque entrée correspond à une entité de l'API Meta Marketing. Sur la base de cette configuration, Cortex Framework crée des DAG Airflow qui exécutent des pipelines Dataflow pour extraire des données à l'aide des API Meta Marketing.

Le fichier src/Meta/src/raw/pipelines/config.ini contrôle certains comportements du DAG Cloud Composer et la façon dont les API Meta Marketing sont utilisées. Vous trouverez la description de chaque paramètre dans le fichier.

Les paramètres suivants contrôlent les paramètres de Source to Raw pour chaque entrée :

Paramètre	Description
`base_table`	Table de l'ensemble de données brutes dans laquelle les données récupérées sont stockées (par exemple, `customer`).
`load_frequency`	Fréquence d'exécution d'un DAG pour récupérer les données de Meta. Pour en savoir plus sur les valeurs possibles, consultez la documentation Airflow.
`object_endpoint`	Chemin d'accès au point de terminaison de l'API (par exemple, `campaigns` pour le point de terminaison `/{account_id}/campaigns`).
`entity_type`	Type de table (doit être l'un des suivants : `fact`, `dimension` ou `addaccount)`).
`object_id_column`	Colonnes (séparées par une virgule) qui forment un enregistrement unique pour cette table. Obligatoire uniquement lorsque `entity_type` est défini sur `fact`.
`breakdowns`	Facultatif : colonnes de répartition (séparées par une virgule) pour les points de terminaison Insights. Ne s'applique que lorsque `entity_type` est défini sur `fact`.
`action_breakdowns`	Facultatif : colonnes de répartition des actions (séparées par une virgule) pour les points de terminaison Insights. Ne s'applique que lorsque `entity_type` est défini sur `fact`.
`partition_details`	Facultatif : si vous souhaitez que cette table soit partitionnée pour des raisons de performances. Pour en savoir plus, consultez Partition de table.
`cluster_details`	Facultatif : si vous souhaitez que cette table soit regroupée pour des raisons de performances. Pour en savoir plus, consultez Paramètres du cluster.

Tables brutes vers tables CDC

Cette section décrit les entrées qui contrôlent la façon dont les données sont transférées des tables brutes vers les tables CDC. Chaque entrée correspond à un tableau brut (qui correspond lui-même à une entité de l'API Meta, comme indiqué).

Les paramètres suivants contrôlent les paramètres de Raw to CDC pour chaque entrée :

Paramètre	Description
`base_table`	Table sur laquelle les données brutes ont été répliquées. Une table portant le même nom dans l'ensemble de données CDC stocke les données brutes après la transformation CDC (par exemple, `campaign_insights`).
`row_identifiers`	Colonnes (séparées par une virgule) qui forment un enregistrement unique pour cette table.
`load_frequency`	Fréquence d'exécution d'un DAG pour cette entité afin de remplir la table CDC. Pour en savoir plus sur les valeurs possibles, consultez la documentation Airflow.
`partition_details`	Facultatif : si vous souhaitez que cette table soit partitionnée pour des raisons de performances. Pour en savoir plus, consultez Partition de table.
`cluster_details`	Facultatif : si vous souhaitez que cette table soit regroupée pour des raisons de performances. Pour en savoir plus, consultez Paramètres du cluster.

Schéma de table CDC

Pour Meta, tous les champs sont stockés au format chaîne dans la couche brute. Dans la couche CDC, les types primitifs sont convertis en types de données métier pertinents, et tous les types complexes sont stockés au format JSON BigQuery.

Pour activer cette conversion, le répertoire src/Meta/config/table_schema contient un fichier de schéma pour chaque entité spécifiée dans la section raw_to_cdc_tables qui explique comment traduire correctement chaque table BigQueryraw en table CDC.

Chaque fichier de schéma contient trois colonnes :

SourceField : nom du champ de la table brute pour cette entité.
TargetField : nom de la colonne de la table CDC pour cette entité.
DataType : type de données de chaque champ de table CDC.

Paramètres de création de rapports

Vous pouvez configurer et contrôler la façon dont Cortex génère des données pour la couche de reporting finale Meta à l'aide du fichier de paramètres de reporting (src/Meta/config/reporting_settings.yaml). Ce fichier contrôle la façon dont les objets BigQuery de la couche de reporting (tables, vues, fonctions ou procédures stockées) sont générés.

Pour en savoir plus, consultez Personnaliser le fichier de paramètres de création de rapports.

Étape suivante

Pour en savoir plus sur les autres sources de données et charges de travail, consultez Sources de données et charges de travail.
Pour en savoir plus sur les étapes de déploiement dans les environnements de production, consultez Conditions préalables au déploiement de la Data Foundation de Cortex Framework.