在Rails當中存取Google AdWords API


目標

利用Google AdWords API讀取AdWords帳戶內的廣告活動成效資料。

1. 選定一個帳號

選定一個你要存取Google AdWords API的帳號,由於申請API需要人工審核,因此需要使用這個帳號提出申請,以下皆稱此帳號為「選定的帳號」。

2. 註冊Google Cloud憑證

英文流程在Github上有記錄

簡單來說:

  1. Developer Console當中建立一個新的專案
  2. 在「憑證」項目底下建立一個用戶端ID
  3. 選擇「已安裝的應用程式」,並選擇「其他」

最後會取得畫面上出現的「用戶端ID」和「用戶端密碼」,記好,晚點會用。

3. 註冊AdWords使用者權杖

  1. 進入AdWords
  2. 點擊右上角的齒輪,選擇「帳戶設定」
  3. 如果你的權限可以管理此帳戶的所有廣告,左邊bar會出現一個「AdWords API中心」選項,點擊該選項
  4. 在選定的帳號底下建立一個開發者權杖
  5. 填寫基本資料以後送出,大概經過1~2個工作天,Google會寄信到你填寫的信箱。
  1. 跟著該信件中的連結進入正式的申請表格頁面,將表格填寫完整,進入人工審核階段。表格請照實際的需求填寫,如果需要A功能就寫A功能,因為Google只會給你你要的,如果沒寫A功能,Google就不會給你A功能的存取權。
  2. 經過1~2個工作天,Google會寄信到你填寫的信箱說已通過,並說明你的存取權有多少。

接下來本次實作方法是要從Rails server端發送request給AdWords讀取資料,因此要利用文件寫得實在不怎樣的google-api-ads-ruby這個library來完成。同時他也提供了很難實作的YouTube影片範例

4. 安裝GEM

要在Rails當中讀取,依然安裝Google提供的API套件。

gem 'omniauth-google-oauth2'
gem 'google-adwords-api'

並執行bundle安裝。

5. 更新yml設定檔

設定檔的內容複製到本機上,由於API預設讀取設定檔的位置是使用者的根目錄,因此我們先在這邊把設定檔建立完成。例如我會把該設定檔放在:

/Users/adler/adwords_api.yml

接著進入該檔案內,將我們在Google取得的資料貼上去:

# 第13行
  :oauth2_client_id: INSERT_OAUTH2_CLIENT_ID_HERE 
    # 貼上在步驟1取得的「用戶端ID」
  :oauth2_client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE 
    # 貼上在步驟1取得的「用戶端密碼」
# 第32行
  :developer_token: INSERT_YOUR_DEVELOPER_TOKEN_HERE 
    # 貼上在AdWords帳戶設定下取得的「使用者權杖」
  :client_customer_id: INSERT_YOUR_CLIENT_CUSTOMER_ID_HERE
    # 貼上AdWords選定的帳號底下的編號,在畫面右上角,格式是「123-123-1234」
  :user_agent: INSERT_YOUR_USER_AGENT_HERE
    # 隨便打一個,例如「good_agent」

6. 利用OAuth2取得Google認證

設定完成之後,確定這個檔案是放在你的使用者根目錄底下,接著要進入該gem安裝的位置,例如我有使用rvm,並使用2.1.2版本,因此目錄會在:

/Users/adler/.rvm/gems/ruby-2.1.2/gems/google-adwords-api-0.15.2/examples

依照你安裝的gem的版本,找到該位置。

接著找到最新的檔案版本,例如我現在最新的版本是v201506,那就key上

cd v201506 

最新的版本編號可以在他的repo中找到。

進入以後,利用內部的檔案建立OAuth2認證,執行:

./misc/setup_oauth2.rb

無誤的話,他會請你連到一個網址並複製認證碼貼到terminal當中,在說明文件當中也有提到這個流程,請照著做。完成以後他會問你:

Would you like to update your adwords_api.yml to save OAuth2 credentials? (y/N):

按下y,你的yml檔案就會更新了。

如果要確認認證有建立起來,請執行:

./basic_operations/get_campaigns.rb

成功的話,他會跟你說:

Total number of campaigns found: 0.

反之,失敗的話,他會跳Hit Auth error訊息請你去認證。

7. 將完成的設定檔複製到Rails目錄底下

由於他預設是抓取本機的設定檔,假如deploy到server上,就不知道要抓哪個檔案了,因此我們要複製到Rails的config目錄底下,並指定路徑給API。

安全起見,最好將adwords_api.yml檔案獨立傳送上去,不要加入Git的source control當中,畢竟裡面是許多設定檔。

以我本機的情況,執行:

mv ~/adwords_api.yml ~/my_rails_project/config/adwords_api.yml

請將我的rails專案名稱換成你的。

8. 在controller當中讀取API

接著我們可以直接在controller當中撰寫讀取的code:

require 'adwords_api'
require 'yaml'

def adwords
  adwords = AdwordsApi::Api.new(YAML.load_file("#{Rails.root}/config/adwords_api.yml"))
  srv = adwords.service(:ManagedCustomerService, :v201506)
  selector = {
    :fields => ["CustomerId", "Name"]
  }
  graph = srv.get(selector)
  render json: graph
end

開瀏覽器並,正確的話就會出現JSON回應了。

雖然我是寫在controller當中,但依照Rails的風格,最好還是寫在model或service當中較佳,請再自行refactor。

所有API的呼叫方法都寫在範例檔當中,可參考檔名決定要使用哪個API。

第一次實作,過程可能有許多繞路的地方,歡迎高手提出改善的建議。