使用 Azure 数据工厂或 Synapse Analytics 从 Google Ads 复制数据

项目
07/12/2024

适用于： Azure 数据工厂 Azure Synapse Analytics

提示

试用 Microsoft Fabric 中的数据工厂，这是一种适用于企业的一站式分析解决方案。 Microsoft Fabric 涵盖从数据移动到数据科学、实时分析、商业智能和报告的所有内容。了解如何免费开始新的试用！

本文概述如何使用 Azure 数据工厂或 Synapse Analytics 管道中的复制活动从 Google Ads 复制数据。它是基于概述复制活动总体的复制活动概述一文。

重要

请在 2024 年 2 月 18 日之前升级 Google Ads 驱动程序版本。否则，由于旧驱动程序的弃用，连接将开始失败并出现错误。

支持的功能

以下功能支持此 Google Ads 连接器：

支持的功能	IR
复制活动（源/-）	① ②
Lookup 活动	① ②

① Azure 集成运行时 ② 自承载集成运行时

如需可以用作源/接收器的数据存储的列表，请参阅支持的数据存储表。

该服务提供内置的驱动程序用于启用连接，因此使用此连接器无需手动安装任何驱动程序。

入门

若要使用管道执行复制活动，可以使用以下工具或 SDK 之一：

使用 UI 创建到 Google Ads 的链接服务

使用以下步骤在 Azure 门户 UI 中创建一个到 Google Ads 的链接服务。

浏览到 Azure 数据工厂或 Synapse 工作区中的“管理”选项卡，并选择“链接服务”，然后单击“新建”：
- Azure 数据工厂
- Azure Synapse
搜索 Google Ads 并选择 Google Ads 连接器。
配置服务详细信息、测试连接并创建新的链接服务。

连接器配置详细信息

对于特定于 Google Ads 连接器的数据工厂实体，以下部分提供了有关用于定义这些实体的属性的详细信息。

链接服务属性

Google Ads 链接服务支持以下属性：

properties	描述	必需
type	type 属性必须设置为：GoogleAdWords	是
googleAdsApiVersion	选择推荐的驱动程序版本时使用的 Google Ads API 版本。有关 API 版本信息，可参阅此文章。	是
clientCustomerID	需提取其报表数据的 Ads 帐户的客户端客户 ID。	是
loginCustomerID	要通过其提取特定客户的报表数据的 Google Ads 经理帐户的客户 ID。	否
developerToken	与管理员帐户相关联的开发人员令牌，该帐户用来授予对 Ads API 的访问权限。可选择将此字段标记为 SecureString，将其安全地存储，或在 Azure Key Vault 中存储密码，并允许复制活动在执行数据复制时从此处拉取（请参阅在 Key Vault 中存储凭据了解详细信息）。	是
authenticationType	用于身份验证的 OAuth 2.0 身份验证机制。允许的值为：ServiceAuthentication、UserAuthentication。 ServiceAuthentication 只能在自托管 IR 上使用。	是
对于 UserAuthentication：
refreshToken	从 Google 获得的刷新令牌，用于授权访问 Ads 以进行用户身份验证。可选择将此字段标记为 SecureString，将其安全地存储，或在 Azure Key Vault 中存储密码，并允许复制活动在执行数据复制时从此处拉取（请参阅在 Key Vault 中存储凭据了解详细信息）。	否
clientId	Google 应用程序的客户端 ID，用于获取刷新令牌。可选择将此字段标记为 SecureString，将其安全地存储，或在 Azure Key Vault 中存储密码，并允许复制活动在执行数据复制时从此处拉取（请参阅在 Key Vault 中存储凭据了解详细信息）。	否
clientSecret	Google 应用程序的客户端机密，用户获取刷新令牌。可选择将此字段标记为 SecureString，将其安全地存储，或在 Azure Key Vault 中存储密码，并允许复制活动在执行数据复制时从此处拉取（请参阅在 Key Vault 中存储凭据了解详细信息）。	否
对于 ServiceAuthentication：
电子邮件	用于 ServiceAuthentication 的服务帐户电子邮件 ID，只能在自托管 IR 上使用。	否
privateKey	用于推荐驱动程序版本的 ServiceAuthentication 的服务私钥，只能在自承载 IR 上使用。可选择将此字段标记为 SecureString，将其安全地存储，或在 Azure Key Vault 中存储密码，并允许复制活动在执行数据复制时从此处拉取（请参阅在 Key Vault 中存储凭据了解详细信息）。	否
对于使用旧版驱动程序的 ServiceAuthentication：
电子邮件	用于 ServiceAuthentication 的服务帐户电子邮件 ID，只能在自托管 IR 上使用。	否
keyFilePath	`.p12` 或 `.json` 密钥文件的完整路径，用于验证服务帐户电子邮件地址，只能在自承载 IR 上使用。	否
trustedCertPath	包含受信任 CA 证书（通过 TLS 进行连接时用来验证服务器）的 .pem 文件的完整路径。只有在自承载 IR 上使用 TLS 时才能设置此属性。默认值是随 IR 一起安装的 cacerts.pem 文件。	否
useSystemTrustStore	指定是使用系统信任存储中的 CA 证书还是使用指定 PEM 文件中的 CA 证书。默认值是 false。	否

示例：

{
    "name": "GoogleAdsLinkedService",
    "properties": {
        "type": "GoogleAdWords",
        "typeProperties": {
            "clientCustomerID": "<clientCustomerID>",
            "loginCustomerID": "<loginCustomerID>",
            "developerToken": {
                "type": "SecureString",
                "value": "<developerToken>"
            },
            "authenticationType": "UserAuthentication",
            "refreshToken": {
                "type": "SecureString",
                "value": "<refreshToken>"
            },
            "clientId": {
                "type": "SecureString",
                "value": "<clientId>"
            },
            "clientSecret": {
                "type": "SecureString",
                "value": "<clientSecret>"
            },
            "googleAdsApiVersion": "v14"
        }
    }
}

数据集属性

有关可用于定义数据集的各部分和属性的完整列表，请参阅数据集一文。本部分提供 Google Ads 数据集支持的属性列表。

要从 Google Ads 复制数据，请将数据集的 type 属性设置为GoogleAdWordsObject。支持以下属性：

属性	描述	必需
type	数据集的 type 属性必须设置为：GoogleAdWordsObject	是
tableName	表的名称。使用旧版驱动程序时，请指定此属性。	否（如果指定了活动源中的“query”）

示例

{
    "name": "GoogleAdsDataset",
    "properties": {
        "type": "GoogleAdWordsObject",
        "typeProperties": {},
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<GoogleAds linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

复制活动属性

有关可用于定义活动的各部分和属性的完整列表，请参阅管道一文。本部分提供 Google Ads 数据源支持的属性列表。

充当源的 Google Ads

要从 Google Ads 复制数据，请将复制活动中的源类型设置为GoogleAdWordsSource。复制活动source部分支持以下属性：

属性	描述	必需
type	复制活动 source 的 type 属性必须设置为：GoogleAdWordsSource	是
查询	使用 GAQL 查询读取数据。例如：`SELECT campaign.id FROM campaign`。	否（如果指定了数据集中的“tableName”）

示例：

"activities":[
    {
        "name": "CopyFromGoogleAds",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<GoogleAds input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "GoogleAdWordsSource",
                "query": "SELECT campaign.id FROM campaign"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

查找活动属性

若要了解有关属性的详细信息，请查看 Lookup 活动。

升级 Google Ads 驱动程序版本

要升级 Google Ads 驱动程序版本，需要更新链接服务，并了解如何从 SQL 迁移到 Google Ads 查询语言 (GAQL)。

更新链接服务配置

在“编辑链接服务”页中，选择“驱动程序版本”下的“推荐”，并参考链接服务属性来配置链接服务。

从 SQL 迁移到 GAQL

从 SQL 迁移到 GAQL 时，转换查询语句和字段名。

查询语句

如果在复制活动源或引用旧版 Google Ads 链接服务的查找活动中使用 SQL 查询，则需要将其更新为 GAQL 查询。

与 SQL 相比，GAQL 中的查询由六种类型的子句组成：

SELECT
FROM
WHERE
ORDER BY
LIMIT
PARAMETERS

要获取 GAQL 的简介，请转到Google Ads 查询语言语法。

以以下 SQL 语句为例：

SELECT *|FieldName FROM ResourceName WHERE FieldName Operator Value

可以按照以下指南将 SQL 语句转换为相应的 GAQL 语句：

如果在SELECT子句后使用*（星号），需要指定所有必填字段以代替星号，因为 GAQL 不支持SELECT *。转到此文章以查看特定资源中的所有可选字段。
如果在SELECT子句之后使用字段名称，需要将名称转换为 GAQL 中的相应字段名称，因为它们具有不同的命名约定。例如，SQL 查询语句中的字段名称campaign_id应转换为 GAQL 中的campaign.id。有关字段名称转换的更多详细信息，请参阅字段名称。
资源名称可以保留为原样，除非其大小写与此处指定的名称不一致。
WHERE子句应根据GAQL 语法更新，因为 GAQL 支持的运算符与 SQL 不一致，字段名称也应按照第二点中所述进行转换。

下面是 Google 提供的两种非常有用的工具，在生成相应的 GAQL 查询语句时，强烈建议使用这些工具：

字段名称

SQL 中使用的字段名称与 GAQL 不一致。还需要了解从 SQL 中的字段名称到 GAQL 中的字段名称的转换规则。转换规则可以如下汇总：

如果字段名称属于资源，SQL 中的下划线 (_) 将更改为 GAQL 中的点 (.)。对于点之间的单词，SQL 中使用的 camelCase 类型语句将更改为独立单词，并在两者之间添加下划线。 SQL 中 PascalCase 类型的第一个字符串将更改为 GAQL 中的相应资源名称。
如果字段名称属于段或指标，应在 GAQL 中添加前缀segments.或metrics.，然后按照第一个点中所述的相同规则转换名称。

下面是字段名称转换的具体示例：

类别	SQL 中的字段名称	GAQL 中的字段名称
资源字段	`Campaign_startDate`	`campaign.start_date`
资源字段	`Customer_conversionTrackingSetting_conversionTrackingStatus`	`customer.conversion_tracking_setting.conversion_tracking_status`
Segments	`DayOfWeek`	`segments.day_of_week`
指标	`VideoViews`	`metrics.video_views`

使用推荐驱动程序版本和旧版驱动程序版本的 Google Ads 之间的差异

下表显示了使用推荐驱动程序版本和旧版驱动程序版本的 Google Ads 之间的功能差异。

建议的驱动程序版本	旧版驱动程序版本
支持指定 Google Ads API 版本。	不支持指定 Google Ads API 版本。
ServiceAuthentication 支持两个属性： � email � privateKey	ServiceAuthentication 支持四个属性： � email � keyFilePath � trustedCertPath � useSystemTrustStore
不支持在数据集中选择表。	支持在数据集中选择表并在复制活动中查询表。
支持 GAQL 语法作为查询语言。	支持 SQL 语法作为查询语言。
输出列名称与 Google Ads 中定义的字段名称相同。	输出列名称与 Google Ads 中定义的字段名称不匹配。
以下映射用于从 Google Ads 数据类型到服务内部使用的临时数据类型。 float -> float int32 -> int int64 -> long	以下映射用于从 Google Ads 数据类型到服务内部使用的临时数据类型。 float -> string int32 -> string int64 -> string

将 Google AdWords 连接器升级到 Google Ads 连接器

按照以下步骤将 Google AdWords 链接服务升级到最新的 Google Ads 链接服务：

选择“推荐”作为驱动程序版本新建 Google Ads 链接服务，并引用链接服务属性以对其进行配置。

更新引用旧版 Google AdWords 链接服务的管道。考虑到 Google Ads 链接服务仅支持使用查询复制数据，因此：

如果管道直接从 Google AdWords 报表中检索数据，请在下表中找到 Google Ads 的相应资源名称，并使用此工具生成查询。

Google AdWords 报表	Google Ads 资源
ACCOUNT_PERFORMANCE_REPORT	客户
AD_PERFORMANCE_REPORT	ad_group_ad
ADGROUP_PERFORMANCE_REPORT	ad_group
AGE_RANGE_PERFORMANCE_REPORT	age_range_view
AUDIENCE_PERFORMANCE_REPORT	campaign_audience_view,ad_group_audience_view
AUTOMATIC_PLACEMENTS_PERFORMANCE_REPORT	group_placement_view
BID_GOAL_PERFORMANCE_REPORT	bidding_strategy
BUDGET_PERFORMANCE_REPORT	campaign_budget
CALL_METRICS_CALL_DETAILS_REPORT	call_view
CAMPAIGN_AD_SCHEDULE_TARGET_REPORT	ad_schedule_view
CAMPAIGN_CRITERIA_REPORT	campaign_criterion
CAMPAIGN_PERFORMANCE_REPORT	市场活动
CAMPAIGN_SHARED_SET_REPORT	campaign_shared_set
CAMPAIGN_LOCATION_TARGET_REPORT	location_view
CLICK_PERFORMANCE_REPORT	click_view
DISPLAY_KEYWORD_PERFORMANCE_REPORT	display_keyword_view
DISPLAY_TOPICS_PERFORMANCE_REPORT	topic_view
GENDER_PERFORMANCE_REPORT	gender_view
GEO_PERFORMANCE_REPORT	geographic_view,user_location_view
KEYWORDLESS_QUERY_REPORT	dynamic_search_ads_search_term_view
KEYWORDS_PERFORMANCE_REPORT	keyword_view
LABEL_REPORT	label
LANDING_PAGE_REPORT	landing_page_view,expanded_landing_page_view
PAID_ORGANIC_QUERY_REPORT	paid_organic_search_term_view
PARENTAL_STATUS_PERFORMANCE_REPORT	parental_status_view
PLACEHOLDER_FEED_ITEM_REPORT	feed_item,feed_item_target
PLACEHOLDER_REPORT	feed_placeholder_view
PLACEMENT_PERFORMANCE_REPORT	managed_placement_view
PRODUCT_PARTITION_REPORT	product_group_view
SEARCH_QUERY_PERFORMANCE_REPORT	search_term_view
SHARED_SET_CRITERIA_REPORT	shared_criterion
SHARED_SET_REPORT	shared_set
SHOPPING_PERFORMANCE_REPORT	shopping_performance_view
TOP_CONTENT_PERFORMANCE_REPORT	Google Ads API 中不再可用。
URL_PERFORMANCE_REPORT	detail_placement_view
USER_AD_DISTANCE_REPORT	distance_view
VIDEO_PERFORMANCE_REPORT	视频

如果管道使用查询从 Google AdWords 检索数据，请使用查询迁移工具将 AWQL（AdWords 查询语言）转换为 GAQL（Google Ads 查询语言）。

请注意，此升级存在一些限制：
1. GAQL 并不支持 AWQL 中的所有报表类型。
2. 并非所有 AWQL 查询都已完全转换为 GAQL 查询。

有关复制活动支持作为源和接收器的数据存储的列表，请参阅支持的数据存储。

通过