最全Google Ads API接入和數據拉回指南

一、集成方案介绍

概览

本文将介绍如何将 Google Ads 回传到本地，本方案支持：

流程

与 Google Ads 的数据集成流程如下图：

  1. 使用 Google Ads Manager Account 登录 Google Ads 后台，申请 Developer token
  2. 登录 Google Cloud Platform 后台，创建带有 Google Ads API 权限的项目，并生成 API 凭据，即 Client ID 与 Client Secret
  3. 根据配置的回调地址，配合 TA 工作人员生成 Refresh Token
  4. 獲取 Developer token、Client ID、Client Secret、Refresh Token、需要拉取数据的广告账户的 Customer ID 以及广告账户经理账号的 Customer ID
  5. 选取您需要拉取的 Resource、分析维度以及指标等，并确定数据拉取的频率以及时间范围
  6. 完成数据拉取开发工作
  7. 搭建看板、报表，并完成数据验收

二、集成前准备工作

2.1 申请 Developer token

使用 Google Ads Manager Account 登录 Google Ads 后台，在右上角菜单选中「TOOLS & SETTINGS」- 「SETUP」-「API Center」，填写 Google Ads API Token Application 完成 Developer token 的申请。

您必须提供访问权限为 Basic Level 的 Developer Token，即完成申请后的 Developer Token，不能使用权限为 Test Account 的 Developer Token。

为了方便您更为快速地完成申请，我们整理了申请表单中的一些问题解答，你可以访问本文档进行查看。另外，您还可以参考官方文档获取更多 Developer token 的信息：

填完申请表格之后，需等待 Token Review Team 批准你的 Developer Token。审核大多数会在 1 个工作日内完成，一般不会超过 3 天。

2.2 生成 Client ID 与 Client Secret

在您获取 Developer Token 的同时，您可以创建 API 的访问凭据，即 Client ID 与 Client Secret。在创建 API 凭据之前，还需要在 Google Cloud Platform 中拥有一个项目，并且该项目开启了 Google Ads API。您可以跟随本节的指引，完成 Client ID 与 Client Secret 的创建。

2.2.1 在 Google Cloud Platform 内创建一个项目

如果您在 Google Cloud Platform 中还没有创建过项目，则可以登录 Google Cloud Platform，点击「CREATE PROJECT」创建项目。如果您已经创建过一个项目，可以跳过此步骤。


图1、新建项目示意图

2.2.2 开启 Google Ads API 权限

完成项目的创建后，接下来就需要开启 Google Ads API 权限。在 Google Cloud Platform 后台的顶部搜索栏中搜索「Google Ads API」，进入到介绍页面。如果页面中下图所示区域显示「ENABLE」，则说明项目尚未开启 Google Ads API 权限。点击「ENABLE」开启权限即可。


图2、Google Ads API 介绍页面

2.2.3 创建 API 凭据，获取 Client ID 与 Client Secret

开启 Google Ads API 权限后，接下来需要创建一个具备 Google Ads API 权限的 API 凭据，即拉取数据时所需的 Client ID 与 Client Secret。

进入到创建凭据流程，请按照以下步骤完成配置

  1. 在 Credential Type 页，依次选择 Google Ads API、 User Data，点击「NEXT」
  1. 在 Scopes 页，点击「ADD OR REMOVE SCOPES」，在列表中寻找 Google Ads API 并勾选，将其加入到 Scope 列表。点击「SAVE AND CONTINUE」
  1. OAuth Client ID 页，Application type 处选择 Web application
  1. 仍然在 OAuth Client ID 页，Authorized redirect URIs 处配置回调地址。请记录您设置的回调地址是哪一个，我们需要根据您所选的回调地址生成 Refresh Token。

请填写以下三种回调地址中的任意一种：

使用本方式，请在此处填写：https://developers.google.com/oauthplayground

使用本方式，请在此处填写以下链接，注意替换 {} 中的内容，其中{GOOGLE_LOGIN_CUSTOMER_ID}即为manager account 的 customer id（不加“-”号）：https://{receiver-host}/thirdparty/callback/google/{TA_APP_ID}/{GOOGLE_LOGIN_CUSTOMER_ID}

2.3 生成 Refresh Token（二选一）

根据您在生成凭证时填写的回调地址，会有不同的生成 Refresh Token 的方法。请根据当时配置的回调，选取相应的方法。

2.3.1 使用 Oauthplayground 的回调地址

使用此方法，需要由您自助完成 Refresh Token 的生成，您可以按照以下流程完成 Token 生成

  1. 进入到「APIs & Services」-「OAuth consent screen」（如果您尚未设置则请完成设置）。查看「Publishing status」的值，确定为 Testing（请不要点击「PUBLISH APP」发布应用）。请在「Test users」中添加您需要拉取数据的广告账户关联的 Google 账号的邮箱。
  1. 访问https://developers.google.com/oauthplayground，在左侧栏寻找「Google Ads API」,选中其中的「https://www.googleapis.com/auth/adwords」。
  2. 点击右上角的小齿轮，勾选「Use your own Oauth credentials」，在下图红框标注出填写您的 Client ID 与 Client Secret
  3. 点击左边栏「Authorize APIs」，进入到下一个环节
  1. 接下来页面会自动跳转到 Google 账号的登录页面，请您登录需要拉取数据的广告账户关联的 Google 账号，进行账号授权（在授权流程中，可能会提示该应用未经 Google 验证，请忽视提醒选择继续）

如果在登录时，出现「错误 403：access_denied」的报错，请确认是否在第 1 步中，将您准备登录的用户加入到 Test users 中，如果未操作，请将其加入后重新进行上述流程。

  1. 完成授权后，页面会再次跳转至先前页面，此时点击左侧的「Exchange authorization code for tokens」获取 Refresh Token。
  1. 最后，您可以在左侧栏中查看到获取的 Refresh Token 与 Access Token，请妥善保存这两个 ID，并提供给 TA 工作人员进行后续的数据拉取。

2.3.2 使用服务器的回调地址或 pipedream 生成的地址

使用本方法，產出一個回調地址，请在浏览器中打开地址后，在该页面中登录您的广告账号关联的 Google 账号，如下图所示：

当您完成授权后，可以看到如下图所示的状态，接下来我们将完成 Refresh Token 的生成工作。

2.4 获取 Customer ID 和 Login Customer ID

最后，请您将要拉取数据的广告账户的 Customer ID，以及该用户的广告经理账号的 Customer ID（即后续调用中的 Login Customer ID）。您可以按照以下流程查看这些 ID。

  1. 在 Google Ads 后台 登录将要拉取数据的广告账户
  2. 单击右上角的帮助图标
  3. 在菜单底部找到 Customer ID
  4. 切换到广告经理账号，按照上述流程获得 Customer ID，即为 Login Customer ID（您也可以直接从广告经理账号的管理员获得其 Customer ID）


三、数据拉取

接口基本信息

接口名API 类型产品化数据粒度归因数据成本数据收益数据展示数据点击数据转化数据
Reporting API拉式否聚合数据是是是是

Google Ads 的 Reporting API 需要通过 GAQL 查询语言来拉取广告数据，且所有广告数据均以 Resource 的形式组织，不同的 Resource 能够提供不同的分析维度以及指标数据，因此我们需要提前获知我们需要获取的数据是什么，这些数据又是存在于那个 Resource 中，从而才能编写适合的 GAQL 语句来拉取数据。

目前我已完成两种数据拉取模式，一种被称为固定拉取，类似于其他第三方平台的拉取方式，我们对常用的 Resource 进行了封装，您只需要指定需要拉取的 Resource，TA 工作人员将拉取预先设计好的维度与指标字段。另一种方式称为自定义拉取，需要指定拉取数据的 GAQL，好处在于可以拉取的维度、指标以及 Resource 都可以完全自定义，并且可以使用 GAQL where 条件筛选，但是必须提供完整的拉取维度以及指标字段清单（或者 GAQL 语句），配置相对复杂。

另外，Google Ads 的不同广告层级结构如下：

3.1 固定 Resource 拉取

固定 Resource 拉取方式获取的字段是固定的，且不能使用 GAQL 筛选等特性。该方式也是 TA 3.7 版本之前唯一的拉取方式。目前支持固定拉取的 Resource 如下所示：

3.1.1 Ad Group Ad 拉取字段

customer.id
segments.date
segments.ad_network_type
campaign.id
campaign.name
ad_group.id
ad_group.name
ad_group_ad. ad.id
ad_group_ad.ad.name
campaign.bidding_strategy
campaign.bidding_strategy_type
campaign.advertising_channel_type
campaign.advertising_channel_sub_type
campaign.app_campaign_setting.bidding_strategy_goal_type
ad_group_ad.action_items
metrics.impressions
metrics.clicks
metrics.conversions
metrics.ctr
metrics.average_cpm
metrics.average_cpe
metrics.average_cpc
metrics.average_cpv
metrics.average_cost
metrics.all_conversions
metrics.conversions_value
metrics.cost_micros
metrics.cost_per_all_conversions
metrics.cost_per_conversion
metrics.value_per_all_conversions
metrics.value_per_conversion
metrics.view_through_conversions
metrics.active_view_cpm
metrics.active_view_ctr
metrics.current_model_attributed_conversions
metrics.current_model_attributed_conversions_value
metrics.engagement_rate
metrics.engagements
metrics.cost_per_current_model_attributed_conversion
metrics.cross_device_conversions
metrics.conversions_value_by_conversion_date
metrics.absolute_top_impression_percentage
metrics.active_view_impressions
metrics.active_view_measurability
metrics.active_view_measurable_impressions
metrics.active_view_measurable_cost_micros
metrics.active_view_viewability
metrics.all_conversions_by_conversion_date
metrics.all_conversions_from_interactions_rate
metrics.all_conversions_value
metrics.all_conversions_value_by_conversion_date
metrics.average_page_views
metrics.average_time_on_site
metrics.bounce_rate
metrics.conversions_by_conversion_date
metrics.conversions_from_interactions_rate
metrics.gmail_forwards
metrics.gmail_saves
metrics.gmail_secondary_clicks
metrics.interactions
metrics.interaction_event_types
metrics.interaction_rate
metrics.percent_new_visitors
metrics.top_impression_percentage
metrics.value_per_all_conversions_by_conversion_date
metrics.value_per_conversions_by_conversion_date
metrics.value_per_current_model_attributed_conversion
metrics.video_views
metrics.video_view_rate
metrics.video_quartile_p25_rate
metrics.video_quartile_p50_rate
metrics.video_quartile_p75_rate
metrics.video_quartile_p100_rate

3.1.2 Ad Group Ad Asset 拉取字段

customer.id
segments.date
segments.ad_network_type
campaign.id
campaign.name
ad_group.id
ad_group.name
ad_group_ad.ad.id
ad_group_ad.ad.name
asset.id
asset.name
campaign.bidding_strategy
campaign.bidding_strategy_type
campaign.advertising_channel_type
campaign.advertising_channel_sub_type
campaign.app_campaign_setting.bidding_strategy_goal_type
campaign.manual_cpm
campaign.manual_cpv
campaign.maximize_conversions.target_cpa
campaign.target_cpm
campaign.target_cpa.cpc_bid_ceiling_micros
campaign.target_cpa.cpc_bid_floor_micros
campaign.target_cpa.target_cpa_micros
campaign.maximize_conversion_value.target_roas
ad_group.cpm_bid_micros
ad_group.target_cpm_micros
ad_group.effective_target_cpa_micros
ad_group.effective_target_cpa_source
ad_group.target_cpa_micros
ad_group_ad.action_items
asset.youtube_video_asset.youtube_video_title
asset.youtube_video_asset.youtube_video_id
metrics.all_conversions
metrics.all_conversions_value
metrics.all_conversions_value_per_cost
metrics.average_cpc
metrics.clicks
metrics.conversions
metrics.conversions_value
metrics.conversions_value_per_cost
metrics.cost_micros
metrics.cost_per_all_conversions
metrics.cost_per_conversion
metrics.ctr
metrics.impressions
metrics.value_per_all_conversions
metrics.value_per_conversion
metrics.view_through_conversions

3.1.3 Geographic View 拉取字段

customer.id
campaign.id
campaign.name
ad_group.id
ad_group.name
geographic_view.country_criterion_id
geographic_view.location_type
geographic_view.resource_name
segments.ad_network_type
segments.date
segments.device
metrics.all_conversions
metrics.average_cpc
metrics.average_cpm
metrics.clicks
metrics.conversions
metrics.conversions_value
metrics.cost_micros
metrics.cost_per_all_conversions
metrics.cost_per_conversion
metrics.ctr
metrics.impressions
metrics.interaction_event_types
metrics.interaction_rate
metrics.interactions
metrics.value_per_conversion
metrics.video_views

3.1.4 Conversion Actions 拉取字段

conversion_action.app_id
conversion_action.attribution_model_settings.attribution_model
conversion_action.attribution_model_settings.data_driven_model_status
conversion_action.category
conversion_action.click_through_lookback_window_days
conversion_action.counting_type
conversion_action.firebase_settings.event_name
conversion_action.firebase_settings.project_id
conversion_action.id
conversion_action.include_in_conversions_metric
conversion_action.mobile_app_vendor
conversion_action.name
conversion_action.owner_customer
conversion_action.phone_call_duration_seconds
conversion_action.resource_name
conversion_action.status
conversion_action.tag_snippets
conversion_action.third_party_app_analytics_settings.event_name
conversion_action.third_party_app_analytics_settings.provider_name
conversion_action.value_settings.always_use_default_value
conversion_action.value_settings.default_currency_code
conversion_action.value_settings.default_value
conversion_action.view_through_lookback_window_days
customer.auto_tagging_enabled
customer.call_reporting_setting.call_conversion_action
customer.call_reporting_setting.call_conversion_reporting_enabled
customer.call_reporting_setting.call_reporting_enabled
customer.conversion_tracking_setting.conversion_tracking_id
customer.conversion_tracking_setting.cross_account_conversion_tracking_id
customer.currency_code
customer.descriptive_name
customer.final_url_suffix
customer.has_partners_badge
customer.id
customer.manager
customer.optimization_score
customer.optimization_score_weight
customer.pay_per_conversion_eligibility_failure_reasons
customer.remarketing_setting.google_global_site_tag
customer.resource_name
customer.test_account
customer.time_zone
customer.tracking_url_template
metrics.conversion_last_conversion_date
metrics.conversion_last_received_request_date_time

3.1.5 Campaign 拉取字段

customer.id
segments.date
segments.ad_network_type
campaign.id
campaign.name
campaign.bidding_strategy
campaign.bidding_strategy_type
campaign.advertising_channel_type
campaign.advertising_channel_sub_type
campaign.app_campaign_setting.bidding_strategy_goal_type

metrics.impressions
metrics.clicks
metrics.conversions
metrics.ctr
metrics.average_cpm
metrics.average_cpe
metrics.average_cpc
metrics.average_cpv
metrics.average_cost
metrics.all_conversions
metrics.conversions_value
metrics.cost_micros
metrics.cost_per_all_conversions
metrics.cost_per_conversion
metrics.value_per_all_conversions
metrics.value_per_conversion
metrics.view_through_conversions
metrics.active_view_cpm
metrics.active_view_ctr
metrics.current_model_attributed_conversions
metrics.current_model_attributed_conversions_value
metrics.engagement_rate
metrics.engagements
metrics.cost_per_current_model_attributed_conversion
metrics.cross_device_conversions
metrics.conversions_value_by_conversion_date
metrics.absolute_top_impression_percentage
metrics.active_view_impressions
metrics.active_view_measurability
metrics.active_view_measurable_impressions
metrics.active_view_measurable_cost_micros
metrics.active_view_viewability
metrics.all_conversions_by_conversion_date
metrics.all_conversions_from_interactions_rate
metrics.all_conversions_value
metrics.all_conversions_value_by_conversion_date
metrics.average_page_views
metrics.average_time_on_site
metrics.bounce_rate
metrics.conversions_by_conversion_date
metrics.conversions_from_interactions_rate
metrics.interactions
metrics.interaction_event_types
metrics.interaction_rate
metrics.percent_new_visitors
metrics.top_impression_percentage
metrics.value_per_all_conversions_by_conversion_date
metrics.value_per_conversions_by_conversion_date
metrics.value_per_current_model_attributed_conversion

3.1.6 接口参数

3.1.7 数据入库规则

默认情况下，我们会将拉取的数据以事件形式写入 TA 项目中：

3.2 自定义拉取

自定义拉取需要指定拉取数据的 GAQL

3.2.1 接口参数

3.2.2 数据入库规则

默认情况下，我们会将拉取的数据以事件形式写入 TA 项目中：

请注意，如果您配置多个自定义拉取 GAQL，需要为每个自定义拉取数据进行重命名，否则重名数据将互相覆盖

四、数据集成配置信息模板

在阅读完以上文档之后，建议您完成以下信息模板，并发送给您在数数科技的客户成功经理，我们将根据该信息模板完成 Google Ads 的数据拉取：

请注意，customer_id 与 login_customer_id 不要加“-”号

数据接收地址 push_url: XXX
--------------------
developer_token: XXX
client_id: XXX
client_secret: XXX
refresh_token: XXX 
customer_id 列表: [XXX, XXX]
login_customer_id: XXX
--------------------
拉取方式：固定拉取/自定义拉取

<-----以下是固定拉取的信息----->
拉取资源: XXX, XXX
拉取字段筛选（可选）：XXX（从拉取字段筛选章节筛选字段）
字段映射配置文件（可选）：XXX（CSV文件对入库事件属性名称进行自定义）
<--------------------------->

<-----以下是自定义拉取的信息----->
拉取GAQL：XXXXXXX
自定义事件名：XXX（默认为 google_ads_customize）
<---------------------------->

--------------------
历史数据拉取：
时间范围：yyyy/mm/dd - yyyy/mm/dd

定时任务拉取：
定时拉取：每天 X 点拉取过去 Y 天的数据

五、数据校驗

在事件管理中查看是否有以下事件：

六、数据使用和 FAQ

6.1 为什么 google_ads_ad_group_ad_asset_view 的成本和曝光等数据和 google_ads_ad_group_ad 的成本和曝光等数据对不上？

谷歌官方解释 asset view 不包括自动生成的 asset（自动生成的 asset 包含其他指标)。因此, asset view 成本的总和与您的整体 campaign (ad group, ad group ad) 成本的总和会不一致；在分析数据时，应当考虑到「自动生成 asset」因素带来的差异性进行分析；更多信息可以参考该文档。

七、聯繫我做問題解答

在對接任何廣告平台API時，若遇到無論是棘手的技術或者產品問題，歡迎聯繫我幫你解答，查看我的履歷

Tagged

Leave a Reply

Your email address will not be published. Required fields are marked *