与 Meta 集成

本页介绍了将 Meta（Facebook 和 Instagram 广告）数据作为 Cortex Framework Data Foundation 营销工作负载的数据源所需的配置。

Meta 是一家科技公司，拥有多个热门在线平台。 Cortex Framework 可集成来自 Instagram 和 Facebook 的广告数据，以便进行分析、与其他数据源相结合，并利用 AI 获得更深入的数据洞见，从而优化您的营销策略。

下图描述了如何通过 Cortex Framework Data Foundation 的营销工作负载获取 Meta 营销数据：

元数据源

图 1。Meta 营销数据源。

配置文件

config.json 文件用于配置连接到数据源所需的设置，以便从各种工作负载转移数据。此文件包含以下 Meta 参数：

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

下表介绍了每个营销参数的值：

参数 含义 默认值 说明
marketing.deployMeta 部署 Meta true 执行 Meta 数据源的部署。
marketing.Meta.deployCDC 为 Meta 部署 CDC 脚本 true 生成 Meta CDC 处理脚本，以便在 Cloud Composer 中作为 DAG 运行。
marketing.Meta.datasets.cdc Meta 的 CDC 数据集 Meta 的 CDC 数据集。
marketing.Meta.datasets.raw Meta 的原始数据集 Meta 的原始数据集。
marketing.Meta.datasets.reporting Meta 的报告数据集 "REPORTING_Meta" Meta 的报告数据集。

数据模型

本部分使用实体关系图 (ERD) 介绍了 Meta 的数据模型。

Meta 的实体关系图

图 2。Meta：实体关系图。

基本视图

这些是 ERD 中的蓝色对象，是 CDC 表的视图，通过最少的转换来解封复杂的数据结构。请参阅 src/marketing/src/Meta/src/reporting/ddls 中的脚本。

报告数据视图

这些是 ERD 中的绿色对象，属于包含汇总指标的报告视图。请参阅 src/marketing/src/Meta/src/reporting/ddls 中的脚本。

API 连接

Cortex Framework 中适用于 Meta 的提取模板使用 Meta Marketing API 来检索报告属性和指标。当前模板使用版本 v25.0。

在查询 Marketing API 时，Meta 会施加动态速率限制。达到速率限制后，从来源到原始数据的提取 DAG 可能无法成功完成。 在这种情况下，您可以在日志中看到相关错误消息，并且 DAG 的下一次执行会追溯加载所有缺失的数据。

Meta Marketing API 有两个访问权限层级：基本和标准。标准层级提供的限制要高得多，如果您计划广泛使用“从源到原始数据”的提取，建议使用标准层级。如需详细了解这些限制以及如何获得更高级别的访问权限，请参阅 Meta 的文档。

如果您拥有标准层级访问权限，可以降低 src/Meta/src/raw/pipelines/config.ini 中 next_request_delay_sec 设置的值，以缩短加载时间。

API 访问权限和访问令牌

若要成功将数据从 Meta 导入 Cortex Framework，您需要在 Meta Business Manager 和开发者控制台中执行以下步骤。

  1. 确定要使用的应用。您可以创建与商家账号相关联的新应用。确保您的应用是 Business 类型。
  2. 设置应用权限。您必须先被分配为应用的管理员，然后才能使用该应用创建令牌。请参阅应用角色文档。 确保您已为应用分配相关资产（账号）。

  3. 创建访问令牌。访问令牌是访问 Meta Marketing API 所必需的，并且始终与应用和用户相关联。您可以使用系统用户或自己的登录信息创建令牌。

    1. 创建管理员系统用户。
    2. 生成令牌。 请务必在令牌生成后立即记下，因为离开此页面后将无法再次检索。
    3. 向您的令牌授予 ads_read 和 business_management 权限，以访问受支持的对象。

  4. 按照 Cloud Composer 文档中的说明在 Cloud Composer 中启用 Secret Manager。然后，创建一个名为 cortex_meta_access_token 的 Secret，并将您在上一步中生成的令牌存储为内容。

数据新鲜度和延迟

一般来说，Cortex Framework 数据源的数据新鲜度受上游连接允许的范围以及 DAG 执行频率的限制。调整 DAG 执行频率，使其与上游频率、资源限制和业务需求保持一致。

借助 Meta Marketing API，您几乎可以实时获取大多数数据（转化数据除外），不过这些数据可能会在事件发生后 28 天内进行调整。

Cloud Composer 连接权限

在 Cloud Composer 中创建以下连接。如需了解详情，请参阅管理 Airflow 连接文档。

连接名称 目的
meta_raw_dataflow 对于 Meta Marketing API > BigQuery 原始数据集
meta_cdc_bq 对于原始数据集 > CDC 数据集转移
meta_reporting_bq 对于 CDC 数据集 > 报告数据集转移

Cloud Composer 服务帐号权限

向 Cloud Composer 中使用的服务帐号（如 meta_raw_dataflow 连接中所配置）授予 Dataflow 权限。请参阅 Dataflow 文档中的说明。服务帐号还需要具有 Secret Manager Secret Accessor 权限。如需了解详情，请参阅访问权限控制文档。

请求参数

目录 src/Meta/config/request_parameters 包含从 Meta Marketing API 中提取的每个实体的 API 请求规范文件。每个请求文件都包含一个要从 Meta Marketing API 中提取的字段列表，每个字段占一行。如需了解详情，请参阅 Meta Marketing API 参考文档。

提取设置

通过文件 src/Meta/config/ingestion_settings.yaml 中的设置控制 Source to Raw 和 Raw to CDC 数据流水线。 本部分介绍了每个数据流水线的参数。

从来源到原始表的转换

此部分包含用于控制 API 提取哪些实体以及如何提取实体的条目。每个条目都对应一个 Meta Marketing API 实体。根据此配置，Cortex Framework 会创建 Airflow DAG，这些 DAG 会运行 Dataflow 流水线，以使用 Meta Marketing API 获取数据。

文件 src/Meta/src/raw/pipelines/config.ini 控制着 Cloud Composer DAG 的某些行为，以及 Meta Marketing API 的使用方式。您可以在该文件中找到每个参数的说明。

以下参数可控制每个条目的 Source to Raw 设置：

参数 说明
base_table 用于存储所提取数据的“原始”数据集中的表（例如 customer）。
load_frequency 相应 DAG 运行以从 Meta 获取数据的频率。如需详细了解可能的值，请参阅 Airflow 文档。
object_endpoint API 端点路径（例如，/{account_id}/campaigns 端点的 campaigns）。
entity_type 表类型（应为 fact、dimension 或 addaccount) 之一）。
object_id_column 构成相应表的唯一记录的列（以英文逗号分隔）。仅在 entity_type 为 fact 时为必需。
breakdowns 可选：用于洞见端点的细分列（以英文逗号分隔）。仅在 entity_type 为 fact 时适用。
action_breakdowns 可选：用于分析洞见端点的操作细分列（以英文逗号分隔）。仅在 entity_type 为 fact 时适用。
partition_details 可选：如果您希望对该表进行分区以提高性能。如需了解详情，请参阅表分区。
cluster_details 可选：如果您希望出于性能考虑而对该表进行聚类。如需了解详情，请参阅集群设置。

从原始表到 CDC 表

本部分介绍了用于控制如何将数据从原始表移至 CDC 表的条目。每个条目都对应一个原始表（该表又对应于上述 Meta API 实体）。

以下参数可控制每个条目的 Raw to CDC 设置：

参数 说明
base_table 已复制原始数据的表。CDC 数据集中具有相同名称的表存储 CDC 转换后的原始数据（例如 campaign_insights）。
row_identifiers 构成相应表的唯一记录的列（以英文逗号分隔）。
load_frequency 相应实体的 DAG 运行以填充 CDC 表的频率。如需详细了解可能的值，请参阅 Airflow 文档。
partition_details 可选：如果您希望对该表进行分区以提高性能，请指定此参数。如需了解详情，请参阅表分区。
cluster_details 可选：如果您希望出于性能考虑而对该表进行聚类。如需了解详情，请参阅集群设置。

CDC 表架构

对于 Meta，所有字段都以字符串格式存储在原始层中。在 CDC 层中，原始类型会转换为相关的商家数据类型，所有复杂类型都会以 BigQuery JSON 格式存储。

为了实现此转换，目录 src/Meta/config/table_schema 包含 raw_to_cdc_tables 部分中指定的每个实体的一个架构文件，用于说明如何将每个 BigQuery 原始表正确转换为 CDC 表。

每个架构文件包含三列：

  • SourceField：相应实体的原始表的字段名称。
  • TargetField：相应实体的 CDC 表中的列名称。
  • DataType：每个 CDC 表字段的数据类型。

报告设置

您可以使用报告设置文件 (src/Meta/config/reporting_settings.yaml) 配置和控制 Cortex 如何为 Meta 最终报告层生成数据。此文件控制报告层 BigQuery 对象（表、视图、函数或存储过程）的生成方式。

如需了解详情，请参阅自定义报告设置文件。

后续步骤