此页面由 Cloud Translation API 翻译。

与 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 处理脚本，以便在 Cloud Composer 中作为 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 的限制：

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

如需详细了解 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 帮助中心内的以下数据新鲜度简介一文。

Cloud Composer 连接权限

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

连接名称	目的
`googleads_raw_dataflow`	对于 Google Ads API > BigQuery 原始数据集。
`googleads_cdc_bq`	对于“原始数据集”>“CDC 数据集”转移。
`googleads_reporting_bq`	对于 CDC 数据集 > 报告数据集传输。

Cloud Composer 服务账号权限

向 Cloud Composer 中使用的服务账号授予 Dataflow 权限（如在 googleads_raw_dataflow 连接中配置）。请参阅 Dataflow 文档中的说明。

提取设置

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

来源到原始表

本部分介绍了 API 会提取哪些实体以及如何提取。每个条目都对应一个 Google Ads 实体。根据此配置，Cortex 会创建 Airflow 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 部署前提条件。