与 Google Ads 集成

本页面介绍了将数据从 Google Ads 作为 Cortex Framework Data Foundation 的营销工作负载的数据源引入所需的配置。

Google Ads 是一个线上广告平台，商家可以在各种 Google 产品和服务上投放广告来宣传自己的产品或服务。Cortex Framework 可将您的 Google Ads 广告数据与其他营销渠道的数据整合在一起，对其进行全面分析，并使用 AI 来提升广告系列效果。

下图介绍了如何通过 Cortex Framework Data Foundation 的营销工作负载获取 Google Ads 广告数据：

Google Ads 广告数据源

图 1. Google Ads 数据源。

配置文件

config.json 文件用于配置从任何数据源（包括 Google Ads）转移数据所需的设置。此文件包含以下 Google Ads 参数：

  "marketing": {
          "deployGoogleAds": true,
          "GoogleAds": {
              "deployCDC": true,
              "lookbackDays": 180,
              "datasets": {
                  "cdc": "",
                  "raw": "",
                  "reporting": "REPORTING_GoogleAds"
                    }
                  }
                 }

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

参数	含义	默认值	说明
`marketing.deployGoogleAds`	部署 Google Ads	`true`	执行 Google Ads 数据源的部署。
`marketing.GoogleAds.deployCDC`	为 Google Ads 部署 CDC	`true`	生成 Google Ads CDC 处理脚本，以便在 Managed Airflow 中作为 DAG 运行。
`marketing.GoogleAds.lookbackDays`	Google Ads 的回溯天数	`180`	开始从 Google Ads API 获取数据的天数。
`marketing.GoogleAds.datasets.cdc`	Google Ads 的 CDC 数据集		Google Ads 的 CDC 数据集。
`marketing.GoogleAds.datasets.raw`	Google Ads 的原始数据集		Google Ads 的原始数据集。
`marketing.GoogleAds.datasets.reporting`	Google Ads 的报告数据集	`"REPORTING_GoogleAds"`	Google Ads 的报告数据集。

数据模型

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

图 2. Google Ads：实体关系图。

基本视图

这些是 ERD 中的蓝色对象，是 CDC 表的视图，除了某些列名称别名之外，没有其他转换。请参阅 src/marketing/src/GoogleAds/src/reporting/ddls 中的脚本。

报告视图

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

API 连接

Cortex Framework 提取模板使用 Google Ads API 从 Google Ads 检索报告属性和指标。当前的 Cortex Framework 模板使用 Google Ads API 版本 17.1。请注意 Google Ads API 的限制：

每天的基本访问操作数：15000（不计包含有效 next_page_token 的分页请求）。
页面大小上限 ：每页 10000 行。
建议的默认参数 ：页面大小等于每页 10000 行。

如需详细了解 API 连接，请参阅 Google Ads API 文档。

账号身份验证

请按照以下步骤设置账号身份验证：

在 Google Cloud 控制台中，依次点击 导航菜单 > API 和服务 > 凭证 > 创建凭证。
创建具有以下特征的 OAuth 客户端 ID 凭证。如需了解详情，请参阅使用 OAuth 2.0 访问 Google API。
```
Application type: "Web Application"
Name: CHOSEN_NAME #(For example,"Cortex Authentication Client").
Authorized redirect URIs: http://127.0.0.1
```
将 CHOSEN_NAME 替换为为 OAuth 客户端 ID 凭证账号选择的名称。
配置凭证后，保存 Client ID 和 Client secret。您后面需要用到它。
使用 OAuth 2.0 访问 Google API 生成新令牌。Cortex Data Foundation 会自动检测并注入可使用用于生成令牌的凭证访问的所有客户（账号）的数据。
使用 Secret Manager 创建 Secret ：
- 在 Google Cloud 控制台中，点击 Secret Manager。
- 使用以下格式创建一个名为 cortex-framework-google-ads-yaml 的 Secret，并根据您的设置更改相应的值：
```
{"developer_token": "DEVELOPER_TOKEN_VALUE", "refresh_token": "REFRESH_TOKEN_VALUE", "client_id": "CLIENT_ID_VALUE", "client_secret": "CLIENT_SECRET_VALUE", "use_proto_plus": False}
```

替换以下内容：

将 DEVELOPER_TOKEN_VALUE 替换为 Google Ads 账号中提供的开发者令牌值。
将 REFRESH_TOKEN_VALUE 替换为在第 4 步中获取的刷新令牌值。
将 CLIENT_ID_VALUE 替换为在第 2 步的 OAuth 设置中获取的客户端 ID 值。
将 CLIENT_SECRET_VALUE 替换为在第 2 步的 OAuth 设置中获取的客户端密钥值。

数据新鲜度和延迟时间

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

使用 Google Ads API 检索的数据通常具有 3 小时以上的延迟时间。由于转化和无效流量检测，这些数据可能会在之后进行调整。如需了解详情，请参阅 Google Ads 帮助中心内的以下 “数据新鲜度简介” 文章。

Managed Service for Apache Airflow 连接权限

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

连接名称	目的
`googleads_raw_dataflow`	适用于 Google Ads API > BigQuery 原始数据集。
`googleads_cdc_bq`	适用于原始数据集 > CDC 数据集转移。
`googleads_reporting_bq`	适用于 CDC 数据集 > 报告数据集转移。

Managed Airflow 服务帐号权限

向 Managed Airflow 中使用的服务帐号（如 googleads_raw_dataflow 连接中所配置）授予 Dataflow 权限。请参阅 Dataflow 文档中的说明。

提取设置

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

源表到原始表

本部分介绍了 API 提取哪些实体以及如何提取。每个条目对应一个 Google Ads 实体。根据此配置，Cortex 会创建 Airflow DAG，这些 DAG 会运行 Dataflow 流水线以使用 Google Ads API 提取数据。

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

参数	说明
`load_frequency`	此实体的 DAG 运行以从 Google Ads 提取数据的频率。如需详细了解可能的值，请参阅 Airflow 文档。
`api_name`	API 资源名称（例如 `customer`)。
`table_name`	原始数据集中存储提取的数据的表（例如 `customer`）。
`schema_file`	`src/table_schema` 目录中的架构文件，用于将 API 响应字段映射到目标表的列名称。
`key`	构成此表的唯一记录的列（以英文逗号分隔）。
`is_metrics_table`	指示给定条目是否适用于指标实体（在 Google Ads API 中）。由于此类表的汇总性质，系统会以略有不同的方式处理此类表。
`partition_details`	可选：如果您希望对此表进行分区以提高性能。如需了解详情，请参阅表分区。
`cluster_details`	可选：如果您希望对此表进行聚簇以提高性能。如需了解详情，请参阅聚簇设置。

原始表到 CDC 表

本部分介绍了哪些条目控制着如何将数据从原始表移到 CDC 表。每个条目对应一个原始表（该原始表又对应一个 Google Ads API 实体，如上所述）。

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

参数	说明
`table_name`	CDC 数据集中存储经过 CDC 转换后的原始数据的表（例如 `customer`）。
`raw_table`	已复制原始数据的表。
`key`	构成此表的唯一记录的列（以英文逗号分隔）。
`load_frequency`	此实体的 DAG 运行以填充 CDC 表的频率。如需详细了解可能的值，请参阅 Airflow 文档。
`schema_file`	`src/table_schema` 目录中的架构文件，用于将原始列映射到 CDC 列和 CDC 列的数据类型。这与上一部分中引用的架构文件相同。
`partition_details`	可选：如果您希望对此表进行分区以提高性能。如需了解详情，请参阅表分区。
`cluster_details`	可选：如果您希望对此表进行聚簇以提高性能。如需了解详情，请参阅聚簇设置。

报告设置

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

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

接下来怎么做？

如需详细了解其他数据源和工作负载，请参阅数据源和工作负载。
如需详细了解在生产环境中进行部署的步骤，请参阅 Cortex Framework Data Foundation 部署前提条件。