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

茄子妹妹

發佈時間: 2023-02-27 05:18:25

更新時間: 2023-02-27 08:05:30

一、集成方案介紹

概覽

本文將介紹如何將 Google Ads 的數據通過Google Ads API拉回到自己本地和系統裡，本方案支持 ：

  • 通過 Google Ads API 回傳聚合指標數據，數據中包含成本、點擊、展示、轉換等指標。
  • Google Ads API 的數據以 Resource 的形式，目前支持固定拉取的 Resource 有：
  • 除上述列舉的 Resource 外，還支持通過直接編寫 GAQL 的方式實現自定義數據拉取，GAQL 的介紹可參考官方文檔

流程

與 Google Ads 的數據集成流程如下圖：

  1. 使用 Google Ads Manager Account  登錄 Google Ads 後臺，申請 Developer token
  2. 登錄 Google Cloud Platform 後臺，創建帶有 Google Ads API 權限的項目，並生成 API 憑據，即 Client ID 與 Client Secret
  3. 根據配置的回調地址，生成 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。

爲了方便您更爲快速地完成申請，我整理了申請表單中的一些問題解答，你可以直接降次文檔內提供的答案輸入之Google後台，申請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 的創建。

1. 在 Google Cloud Platform 內創建一個項目

如果您在 Google Cloud Platform 中還沒有創建過項目，則可以登錄 Google Cloud Platform，點擊「CREATE PROJECT」創建項目。如果您已經創建過一個項目，可以跳過此步驟。

2. 開啓 Google Ads API 權限

完成項目的創建後，接下來就需要開啓 Google Ads API 權限。在 Google Cloud Platform 後臺的頂部搜索欄中搜索「Google Ads API」，進入到介紹頁面。如果頁面中下圖所示區域顯示「ENABLE」，則說明項目尚未開啓 Google Ads API 權限。點擊「ENABLE」開啓權限即可。

3. 創建 API 憑據，獲取 Client ID 與 Client Secret

開啓 Google Ads API 權限後，接下來需要創建一個具備 Google Ads API 權限的 API 憑據，即拉取數據時所需的 Client ID 與 Client Secret。

  • 開啓 Google Ads API 權限時，您應該會跳轉到以下頁面。此時點擊下圖紅框處「CREATE CREDENTIALS」即可進入到創建憑據的流程中。

  • 如果您沒有找到上述頁面，也可以在頁面左上角的菜單欄中，找到「APIs & Services」- 「Enabled APIs & services」並進入。在列表中尋找 Google Ads API，點擊進入到下圖頁面。此時選中「CREDENTIALS」標籤頁，點擊「+ CREATE CREDENTIALS」，選擇「Help me choose」，亦可進入到創建憑據的流程中。

進入到創建憑據流程，請按照以下步驟完成配置

  1. 在 Credential Type 頁，依次選擇 Google Ads API、 User Data，點擊「NEXT」

2. 在 Scopes 頁，點擊「ADD OR REMOVE SCOPES」，在列表中尋找 Google Ads API 並勾選，將其加入到 Scope 列表。點擊「SAVE AND CONTINUE」

3. OAuth客戶端 ID 頁，應用程序類型處選擇Web應用程序

4. 仍然在 OAuth Client ID 頁，Authorized redirect URIs 處配置回調地址。請記錄您設置的回調地址是哪一個，我們需要根據您所選的回調地址生成 Refresh Token。

請填寫以下三種回調地址中的任意一種：

  • 使用 Oauthplayground 的回調地址

使用本方式，請在此處填寫：https://developers.google.com/oauthplayground

  • 使用自己服務器的回調地址

使用本方式，請在此處填寫以下鏈接，注意替換 {} 中的內容，其中{GOOGLE_LOGIN_CUSTOMER_ID}即爲manager account 的 customer id（不加“-”號）：https://{receiver-host}/thirdparty/callback/google/{GOOGLE_LOGIN_CUSTOMER_ID}

  • 使用 pipedream 生成的地址

如果您選擇使用這種方式，需要在pipedream 完成創建後，將該回調地址填寫在此處。


5. 完成所有配置後，點擊「CREATE」創建憑證。創建完畢後，頁面中將展示 Client ID，建議您點擊「DOWNLOAD」下載該憑證。

2.3 生成 Refresh Token（二選一）

根據您在生成憑證時填寫的回調地址，會有不同的生成 Refresh Token 的方法。請根據當時配置的回調，選取相應的方法。

1. 使用 Oauthplayground 的回調地址

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

1. 進入到「APIs & Services」-「OAuth consent screen」（如果您尚未設置則請完成設置）。查看「Publishing status」的值，確定爲 Testing（請不要點擊「PUBLISH APP」發佈應用）。請在「Test users」中添加您需要拉取數據的廣告賬戶關聯的 Google 賬號的郵箱。

2. 訪問https://developers.google.com/oauthplayground，在左側欄尋找「Google Ads API」,選中其中的「https://www.googleapis.com/auth/adwords」。

3. 點擊右上角的小齒輪，勾選「Use your own Oauth credentials」，在下圖紅框標註出填寫您的 Client ID 與 Client Secret

4. 點擊左邊欄「Authorize APIs」，進入到下一個環節

5. 接下來頁面會自動跳轉到 Google 賬號的登錄頁面，請您登錄需要拉取數據的廣告賬戶關聯的 Google 賬號，進行賬號授權（在授權流程中，可能會提示該應用未經 Google 驗證，請忽視提醒選擇繼續）

如果在登錄時，出現「錯誤 403：access_denied」的報錯，請確認是否在第 1 步中，將您準備登錄的用戶加入到 Test users 中，如果未操作，請將其加入後重新進行上述流程。

6. 完成授權後，頁面會再次跳轉至先前頁面，此時點擊左側的「Exchange authorization code for tokens」獲取 Refresh Token。

7. 最後，您可以在左側欄中查看到獲取的 Refresh Token 與 Access Token，請妥善保存這兩個 ID，因為後續的數據拉取都需要用到這兩個ID。

2. 使用自己的服務器的回調地址或 pipedream 生成的地址

使用自己生成的服務器的回調地址時，請在瀏覽器中打開地址後，在該頁面中登錄您的廣告賬號關聯的 Google 賬號，如下圖所示：

當您完成授權後，可以看到如下圖所示的狀態，接下來我們將完成 Refresh Token 的生成工作。

2.4獲取 客戶 ID 和登錄客戶 ID

最後，請您將要拉取數據的廣告賬戶的 Customer ID。您可以按照以下流程查看這些 ID。

  1. 在 Google Ads 後臺 登錄將要拉取數據的廣告賬戶
  2. 單擊右上角的幫助圖標
  3. 在菜單底部找到 Customer ID
  4. 切換到廣告經理賬號，按照上述流程獲得 Customer ID，即爲 Login Customer ID（您也可以直接從廣告經理賬號的管理員獲得其 Customer ID）

Google Ads的customerID

三、數據拉取

接口名 API 類型產品化數據粒度歸因數據成本數據收益數據展示數據點擊數據轉化數據
彙報API拉式否聚合數據是是是是是是

Google Ads 的 Reporting API 需要通過 GAQL 查詢語言來拉取廣告數據，且所有廣告數據均以 Resource 的形式組織，不同的 Resource 能夠提供不同的分析維度以及指標數據，因此我們需要提前獲知我們需要獲取的數據是什麼，這些數據又是存在於那個 Resource 中，從而才能編寫適合的 GAQL 語句來拉取數據。

另外，Google Ads 的不同廣告層級結構如下：

Google Ads裡account，campaign，adgroup和keywords的層級結構

3.1 固定 Resource 拉取

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

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

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. 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

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

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

6. 接口參數

  • 時間：拉取基於廣告賬號設置時區、以日爲時間單位的數據

7 數據入庫規則

默認情況下，我會將拉取的數據以事件形式寫入數據庫中：

1. 由於 Reporting API 是聚合數據，因此我將使用一個固定值作爲其用戶標識，您可以認爲所有數據掛載在一個虛擬用戶上

2. 使用數據中的 segments_date 字段，即數據的日期，設置爲聚合數據的 #event_time

3. 數據事件名爲：

    4. 其餘字段都將會入庫

    3.2 自定義拉取

    自定義拉取需要指定拉取數據的 GAQL

    1. 接口參數

    • 時間：拉取基於廣告賬號設置時區、以日爲時間單位的數據

    2. 數據入庫規則

    默認情況下，我會將拉取的數據以事件形式寫入數據庫中：

    • 由於 Reporting API 是聚合數據，因此我將使用一個固定值作爲其用戶標識，您可以認爲所有數據掛載在一個虛擬用戶上
    • 使用數據中的 segments_date 字段，即數據的日期，設置爲聚合數據的 #event_time
    • 數據的事件名可以自定義，如果不自定義，則默認事件名爲：google_ads_customize
    • 指標字段（以 metric 開頭字段）將以數值類型入庫，其餘字段以字符串類型入庫
    請注意，如果您配置多個自定義拉取 GAQL，需要爲每個自定義拉取數據進行重命名，否則重名數據將互相覆蓋

    四、數據集成配置信息模板

    在閱讀完以上文檔之後，會收集到以下的信息，我們就可以完成Google Ads數據的拉取了

    請注意，customer_id 與 login_customer_id 不要加“-”號
    数据接口：Google Ads Reporting API
--------------------
数据接收地址 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 天的数据

    五、數據效驗

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

    • google_ads_ad_group_ad
    • google_ads_ad_group_ad_asset_view
    • google_ads_conversion_action
    • google_ads_geographic_view
    • google_ads_campaign
    • 或自定義事件名（默認爲 google_ads_customize）

    六、數據使用和 FAQ

    爲什麼 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」因素帶來的差異性進行分析；更多信息可以參考該文檔。





    HTML Sitemap
    聯絡我們: chachingtech123@gmail.com