google-adwords-api 0.4.5 → 0.5.0

data/ChangeLog

@@ -1,3 +1,7 @@
+0.5.0:
+  - Removed deprecated API versions (pre-v201109).
+  - Example updates and revamp.
+
 0.4.5:
   - Support for GZip compression.
   - Support for returnMoneyInMicros header.

data/README

@@ -6,9 +6,9 @@ AdWords and DoubleClick Ad Exchange Buyer API!
 Please note that this is an early PREVIEW of the client library, still under
 development.
 
-It contains full support for v13, v200909, v201003, v201008, v201101 and
-v201109, with full stubs, and a simplified programming interface that lets you
-handle everything in native Ruby collections.
+It contains full support for v201109, with full stubs, and a simplified
+programming interface that lets you handle everything in native Ruby
+collections.
 
 
 = Docs for Users

data/Rakefile

@@ -1,8 +1,8 @@
-#!/usr/bin/ruby
+# Encoding: utf-8
 #
 # Authors:: api.dklimkin@gmail.com (Danial Klimkin)
 #
-# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
+# Copyright:: Copyright 2012, Google Inc. All Rights Reserved.
 #
 # License:: Licensed under the Apache License, Version 2.0 (the "License");
 #           you may not use this file except in compliance with the License.
@@ -26,7 +26,7 @@ require './lib/adwords_api/api_config'
 require './lib/adwords_api/extensions'
 
 # Workaround for the current mess of different yamlers in Ruby world.
-if RUBY_VERSION>='1.9.2'
+if RUBY_VERSION >= '1.9.2' and RUBY_ENGINE == 'ruby'
   gem 'psych'
   YAML::ENGINE.yamler = 'psych'
 end

data/examples/v201109/{create_account.rb → account_management/create_account.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.dklimkin@gmail.com (Danial Klimkin)
 #

data/examples/v201109/{get_campaign_alerts.rb → account_management/get_account_alerts.rb}

@@ -1,6 +1,7 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
-# Author:: api.sgomes@gmail.com (Sérgio Gomes)
+# Author:: api.dklimkin@gmail.com (Danial Klimkin)
 #
 # Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
 #
@@ -17,8 +18,8 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This code example illustrates how to retrieve campaign alerts for a user.
-# The alerts are restricted to a maximum of 10 entries.
+# This example gets all alerts for all clients of an MCC account. The effective
+# user (clientCustomerId, or authToken) must be an MCC user to get results.
 #
 # Tags: AlertService.get
 
@@ -27,8 +28,9 @@ require 'adwords_api'
 require 'adwords_api/utils'
 
 API_VERSION = :v201109
+PAGE_SIZE = 500
 
-def get_campaign_alerts()
+def get_account_alerts()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -46,36 +48,51 @@ def get_campaign_alerts()
       :client_spec => 'ALL',
       :trigger_time_spec => 'ALL_TIME',
       :severities => ['GREEN', 'YELLOW', 'RED'],
-      :types => ['CAMPAIGN_ENDING', 'CAMPAIGN_ENDED']
+      :types => [
+        'ACCOUNT_BUDGET_BURN_RATE', 'ACCOUNT_BUDGET_ENDING',
+        'ACCOUNT_ON_TARGET', 'CAMPAIGN_ENDED', 'CAMPAIGN_ENDING',
+        'CREDIT_CARD_EXPIRING', 'DECLINED_PAYMENT', 'MANAGER_LINK_PENDING',
+        'MISSING_BANK_REFERENCE_NUMBER', 'PAYMENT_NOT_ENTERED',
+        'TV_ACCOUNT_BUDGET_ENDING', 'TV_ACCOUNT_ON_TARGET',
+        'TV_ZERO_DAILY_SPENDING_LIMIT', 'USER_INVITE_ACCEPTED',
+        'USER_INVITE_PENDING', 'ZERO_DAILY_SPENDING_LIMIT'
+      ]
     },
     :paging => {
       :start_index => 0,
-      :number_results => 10
+      :number_results => PAGE_SIZE
     }
   }
 
-  # Get alerts.
-  response = alert_srv.get(selector)
+  # Set initial values.
+  offset, page = 0, {}
 
-  if response and response[:entries]
-    alerts = response[:entries]
-    alerts.each_with_index do |alert, index|
-      puts "{index}) Customer Id is " +
-          "#{AdwordsApi::Utils.format_id(alert[:client_customer_id])}, " +
-          "alert type is '#{alert[:alert_type]}', severity is " +
-          "#{alert[:alert_severity]}."
-      alert[:details].each do |detail|
-        puts "  - triggered at #{detail[:trigger_time]}"
+  # Get alerts.
+  begin
+    page = alert_srv.get(selector)
+    if page[:entries]
+      page[:entries].each_with_index do |alert, index|
+        puts "%d) Customer ID is '%s', alert type is '%s', severity is '%s'."
+            [AdwordsApi::Utils.format_id(alert[:client_customer_id]),
+             alert[:alert_type], alert[:alert_severity]]
+        alert[:details].each do |detail|
+          puts "\t- triggered at %s" % detail[:trigger_time]
+        end
       end
+      # Increment values to request the next page.
+      offset += PAGE_SIZE
+      selector[:paging][:start_index] = offset
     end
-  else
-    puts "No alerts were found."
+  end while page[:total_num_entries] > offset
+
+  if page.include?(:total_num_entries)
+    puts "\tTotal number of alerts: %d." % page[:total_num_entries]
   end
 end
 
 if __FILE__ == $0
   begin
-    get_campaign_alerts()
+    get_account_alerts()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{get_all_account_changes.rb → account_management/get_account_changes.rb}

@@ -1,6 +1,7 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
-# Author:: api.sgomes@gmail.com (Sérgio Gomes)
+# Author:: api.dklimkin@gmail.com (Danial Klimkin)
 #
 # Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
 #
@@ -17,18 +18,19 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example gets all account changes between the two dates specified, for
-# all campaigns.
+# This example gets all account changes that happened within the last 24 hours,
+# for all your campaigns.
 #
 # Tags: CustomerSyncService.get
 
 require 'rubygems'
 require 'adwords_api'
+require 'date'
 require 'pp'
 
 API_VERSION = :v201109
 
-def get_all_account_changes()
+def get_account_changes()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -54,14 +56,12 @@ def get_all_account_changes()
   campaign_ids = []
 
   if response and response[:entries]
-    campaigns = response[:entries]
-    campaign_ids = campaigns.map { |campaign| campaign[:id] }
+    campaign_ids = response[:entries].map { |campaign| campaign[:id] }
   else
-    puts "No campaigns were found."
-    return
+    raise StandardError, 'No campaigns were found.'
   end
 
-  # Create selector for CustomerSyncService.
+  # Create a selector for CustomerSyncService.
   selector = {
     :campaign_ids => campaign_ids,
     :date_time_range => {
@@ -70,54 +70,55 @@ def get_all_account_changes()
     }
   }
 
-  # Get all account changes for campaigns.
+  # Get all account changes for the campaigns.
   campaign_changes = customer_sync_srv.get(selector)
 
   # Display changes.
   if campaign_changes
-    puts "Most recent change: #{campaign_changes[:last_change_timestamp]}"
+    puts "Most recent change: %s" % campaign_changes[:last_change_timestamp]
     campaign_changes[:changed_campaigns].each do |campaign|
-      puts "Campaign with id #{campaign[:campaign_id]} was changed:"
-      puts "  Campaign changed status: #{campaign[:campaign_change_status]}"
-      if campaign[:campaign_change_status] != 'NEW'
-        puts "  Added ad extensions: %s" %
-            campaign[:added_ad_extensions].pretty_inspect
-        puts "  Added campaign criteria: %s" %
-            campaign[:added_campaign_criteria].pretty_inspect
-        puts "  Added campaign targeting: %s" %
-            campaign[:campaign_targeting_changed].pretty_inspect
-        puts "  Deleted ad extensions: %s" %
-            campaign[:deleted_ad_extensions].pretty_inspect
-        puts "  Deleted campaign criteria: %s" %
-            campaign[:deleted_campaign_criteria].pretty_inspect
+      puts "Campaign with ID %d was changed:" % campaign[:campaign_id]
+      puts "\tCampaign change status: '%s'" % campaign[:campaign_change_status]
+      unless ['NEW', 'FIELDS_UNCHANGED'].include?(
+          campaign[:campaign_change_status])
+        puts "\tAdded ad extensions: '%s'" %
+            campaign[:added_ad_extensions].pretty_inspect.chomp
+        puts "\tAdded campaign criteria: '%s'" %
+            campaign[:added_campaign_criteria].pretty_inspect.chomp
+        puts "\tAdded campaign targeting: '%s'" %
+            campaign[:campaign_targeting_changed].pretty_inspect.chomp
+        puts "\tDeleted ad extensions: '%s'" %
+            campaign[:deleted_ad_extensions].pretty_inspect.chomp
+        puts "\tDeleted campaign criteria: '%s'" %
+            campaign[:deleted_campaign_criteria].pretty_inspect.chomp
 
         if campaign[:changed_ad_groups]
           campaign[:changed_ad_groups].each do |ad_group|
-            puts "  Ad group with id #{ad_group[:ad_group_id]} was changed:"
-            puts "    Ad group changed status: " +
-                "#{ad_group[:ad_group_change_status]}"
-            if ad_group[:ad_group_change_status] != 'NEW'
-              puts "    Ads changed: %s" % ad_group[:changed_ads].pretty_inspect
-              puts "    Criteria changed: %s" %
-                  ad_group[:changed_criteria].pretty_inspect
-              puts "    Criteria deleted: %s" %
-                  ad_group[:deleted_criteria].pretty_inspect
+            puts "\tAd group with ID %d was changed:" % ad_group[:ad_group_id]
+            puts "\t\tAd group changed status: '%s'" %
+                ad_group[:ad_group_change_status]
+            unless ['NEW', 'FIELDS_UNCHANGED'].include?(
+                ad_group[:ad_group_change_status])
+              puts "\t\tAds changed: '%s'" %
+                  ad_group[:changed_ads].pretty_inspect.chomp
+              puts "\t\tCriteria changed: '%s'" %
+                  ad_group[:changed_criteria].pretty_inspect.chomp
+              puts "\t\tCriteria deleted: '%s'" %
+                  ad_group[:deleted_criteria].pretty_inspect.chomp
             end
           end
         end
       end
-      puts ''
+      puts
     end
   else
-    puts "No account changes were found."
+    puts 'No account changes were found.'
   end
-
-
 end
 
 if __FILE__ == $0
   begin
-    get_all_account_changes()
+    get_account_changes()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{get_account_hierarchy.rb → account_management/get_account_hierarchy.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.dklimkin@gmail.com (Danial Klimkin)
 #

data/examples/v201109/{get_client_customer_id.rb → account_management/get_client_customer_id.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.dklimkin@gmail.com (Danial Klimkin)
 #

data/examples/v201109/{get_unit_count.rb → account_management/get_client_unit_usage.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.dklimkin@gmail.com (Danial Klimkin)
 #
@@ -17,8 +18,8 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example illustrates how to retrieve the number of API units recorded for
-# the developer token over the given date range as well as for the current call.
+# This example illustrates how to retrieve the number of API units usage for a
+# client account for the current month.
 #
 # Tags: InfoService.get
 
@@ -27,7 +28,7 @@ require 'adwords_api'
 
 API_VERSION = :v201109
 
-def get_unit_count()
+def get_client_unit_usage()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -38,19 +39,26 @@ def get_unit_count()
 
   info_srv = adwords.service(:InfoService, API_VERSION)
 
+  # Specify client customer ID for the account to get usage for.
+  client_customer_id = 'INSERT_CLIENT_CUSTOMER_ID_HERE'.to_i
+
   start_date = Time.now.strftime('%Y%m01')
   end_date = Time.now.strftime('%Y%m%d')
 
   selector = {
-    :api_usage_type => 'UNIT_COUNT',
+    :api_usage_type => 'UNIT_COUNT_FOR_CLIENTS',
+    :client_customer_ids => [client_customer_id],
+    # Set to true to navigate your entire accounts tree.
+    :include_sub_accounts => 1,
     :date_range => {
       :min => start_date,
       :max => end_date
     }
   }
 
-  # Get the unit info.
+  # Force to use the MCC credentials.
   adwords.use_mcc do
+    # Get the unit info.
     info_srv.get(selector) do |header, response|
       puts "Total number of units consumed from %s to %s is %d." %
           [start_date, end_date, response[:cost]]
@@ -61,7 +69,7 @@ end
 
 if __FILE__ == $0
   begin
-    get_unit_count()
+    get_client_unit_usage()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{add_ad_group.rb → basic_operations/add_ad_group.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.sgomes@gmail.com (Sérgio Gomes)
 #

data/examples/v201109/{add_campaign.rb → basic_operations/add_campaign.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.sgomes@gmail.com (Sérgio Gomes)
 #

data/examples/v201109/{add_ad_group_criteria.rb → basic_operations/add_keywords.rb}

@@ -1,6 +1,7 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
-# Author:: api.sgomes@gmail.com (Sérgio Gomes)
+# Author:: api.dklimkin@gmail.com (Danial Klimkin)
 #
 # Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
 #
@@ -17,8 +18,8 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example illustrates how to add a criterion to a given ad group. To create
-# an ad group, run add_ad_group.rb.
+# This example illustrates how to add multiple keywords to a given ad group. To
+# create an ad group, run add_ad_group.rb.
 #
 # Tags: AdGroupCriterionService.mutate
 
@@ -27,7 +28,7 @@ require 'adwords_api'
 
 API_VERSION = :v201109
 
-def add_ad_group_criteria()
+def add_keywords()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -41,42 +42,36 @@ def add_ad_group_criteria()
 
   ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
 
-  # Create keyword.
-  kwd_operation = {
-    :operator => 'ADD',
-    :operand => {
-      # The 'xsi_type' field allows you to specify the xsi:type of the object
-      # being created. It's only necessary when you must provide an explicit
-      # type that the client library can't infer.
-      :xsi_type => 'BiddableAdGroupCriterion',
-      :ad_group_id => ad_group_id,
-      :criterion => {
-        :xsi_type => 'Keyword',
-        :text => 'mars cruise',
-        :match_type => 'BROAD'
-      }
-    }
-  }
+  # Create keywords.
+  # The 'xsi_type' field allows you to specify the xsi:type of the object
+  # being created. It's only necessary when you must provide an explicit
+  # type that the client library can't infer.
+  keywords = [
+    {:xsi_type => 'BiddableAdGroupCriterion',
+     :ad_group_id => ad_group_id,
+     :criterion => {
+       :xsi_type => 'Keyword',
+       :text => 'mars cruise',
+       :match_type => 'BROAD'}},
+    {:xsi_type => 'BiddableAdGroupCriterion',
+     :ad_group_id => ad_group_id,
+     :criterion => {
+       :xsi_type => 'Keyword',
+       :text => 'space hotel',
+       :match_type => 'BROAD'}}
+  ]
 
-  # Create placement.
-  plc_operation = {
-    :operator => 'ADD',
-    :operand => {
-      :xsi_type => 'BiddableAdGroupCriterion',
-      :ad_group_id => ad_group_id,
-      :criterion => {
-        :xsi_type => 'Placement',
-        :url => 'http://mars.google.com'
-      }
-    }
-  }
+  # Create 'ADD' operations.
+  operations = keywords.map do |keyword|
+    {:operator => 'ADD', :operand => keyword}
+  end
 
   # Add criteria.
-  response = ad_group_criterion_srv.mutate([kwd_operation, plc_operation])
+  response = ad_group_criterion_srv.mutate(operations)
   if response and response[:value]
     ad_group_criteria = response[:value]
-    puts "Added %d criteria to ad group %d" % [ad_group_criteria.length,
-        ad_group_id]
+    puts "Added %d criteria to ad group ID %d:" %
+        [ad_group_criteria.length, ad_group_id]
     ad_group_criteria.each do |ad_group_criterion|
       puts "\tCriterion ID is %d and type is '%s'" %
           [ad_group_criterion[:criterion][:id],
@@ -89,7 +84,7 @@ end
 
 if __FILE__ == $0
   begin
-    add_ad_group_criteria()
+    add_keywords()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e