google-adwords-api 0.4.5 → 0.5.0

data/examples/v201109/{get_all_active_ad_group_criteria.rb → basic_operations/get_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 retrieve all the active criteria for an ad
-# group. To add criteria to an existing ad group, run add_ad_group_criteria.rb.
+# This example illustrates how to retrieve all keywords for an ad group. To add
+# keywords to an existing ad group, run add_keywords.rb.
 #
 # Tags: AdGroupCriterionService.get
 
@@ -26,8 +27,9 @@ require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109
+PAGE_SIZE = 500
 
-def get_all_active_ad_group_criteria()
+def get_keywords()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -41,44 +43,49 @@ def get_all_active_ad_group_criteria()
 
   ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
 
-  # Get all the active criteria for this ad group
+  # Get all keywords for this ad group.
   selector = {
-    :fields => ['Id'],
-    :ordering => [{
-      :field => 'AdGroupId',
-      :sort_order => 'ASCENDING'
-    }],
+    :fields => ['Id', 'CriteriaType', 'KeywordText'],
+    :ordering => [
+      {:field => 'Id', :sort_order => 'ASCENDING'}
+    ],
     :predicates => [
-      {
-        :field => 'AdGroupId',
-        :operator => 'IN',
-        :values => [ad_group_id]
-      },
-      {
-        :field => 'Status',
-        :operator => 'IN',
-        :values => ['ACTIVE']
-      }
-    ]
+      {:field => 'AdGroupId', :operator => 'EQUALS', :values => [ad_group_id]},
+      {:field => 'CriteriaType', :operator => 'EQUALS', :values => ['KEYWORD']}
+    ],
+    :paging => {
+      :start_index => 0,
+      :number_results => PAGE_SIZE
+    }
   }
-  response = ad_group_criterion_srv.get(selector)
-  if response and response[:entries]
-    ad_group_criteria = response[:entries]
-    puts "Ad group ID %d has %d active criteria." % [ad_group_id,
-        ad_group_criteria.length]
-    ad_group_criteria.each do |ad_group_criterion|
-      puts "\tCriterion ID is %d  and type is '%s'" %
-          [ad_group_criterion[:criterion][:id],
-           ad_group_criterion[:criterion][:type]]
+
+  # Set initial values.
+  offset, page = 0, {}
+
+  begin
+    page = ad_group_criterion_srv.get(selector)
+    if page[:entries]
+      page[:entries].each do |keyword|
+        puts "Keyword ID %d, type '%s' and text '%s'" %
+            [keyword[:criterion][:id],
+             keyword[:criterion][:type],
+             keyword[:criterion][:text]]
+      end
+      # Increment values to request the next page.
+      offset += PAGE_SIZE
+      selector[:paging][:start_index] = offset
     end
-  else
-    puts "No active criteria found for ad group %d" % ad_group_id
+  end while page[:total_num_entries] > offset
+
+  if page.include?(:total_num_entries)
+    puts "\tAd group ID %d has %d keyword(s)." %
+        [ad_group_id, page[:total_num_entries]]
   end
 end
 
 if __FILE__ == $0
   begin
-    get_all_active_ad_group_criteria()
+    get_keywords()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{get_all_ads.rb → basic_operations/get_text_ads.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 retrieve all the ads for an ad group. To add
-# ads to an existing ad group, run add_ads.rb.
+# This example illustrates how to retrieve all text ads for an ad group. To add
+# ads to an existing ad group, run add_text_ads.rb.
 #
 # Tags: AdGroupAdService.get
 
@@ -26,8 +27,9 @@ require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109
+PAGE_SIZE = 500
 
-def get_all_ads()
+def get_text_ads()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -42,35 +44,50 @@ def get_all_ads()
 
   # Get all the ads for this ad group.
   selector = {
-    :fields => ['Id', 'Status'],
+    :fields => ['Id', 'Status', 'AdType'],
     :ordering => [{:field => 'Id', :sort_order => 'ASCENDING'}],
     # By default, disabled ads aren't returned by the selector. To return them,
     # include the DISABLED status in a predicate.
     :predicates => [
       {:field => 'AdGroupId', :operator => 'IN', :values => [ad_group_id]},
-      {
-        :field => 'Status',
-        :operator => 'IN',
-        :values => ['ENABLED', 'PAUSED', 'DISABLED']
-      }
-    ]
+      {:field => 'Status',
+       :operator => 'IN',
+       :values => ['ENABLED', 'PAUSED', 'DISABLED']},
+      {:field => 'AdType',
+       :operator => 'EQUALS',
+       :values => ['TEXT_AD']}
+    ],
+    :paging => {
+      :start_index => 0,
+      :number_results => PAGE_SIZE
+    }
   }
-  response = ad_group_ad_srv.get(selector)
-  if response and response[:entries]
-    ads = response[:entries]
-    puts "Ad group ##{ad_group_id} has #{ads.length} ad(s)."
-    ads.each do |ad|
-      puts "  Ad id is #{ad[:ad][:id]}, type is #{ad[:ad][:xsi_type]} and " +
-          "status is \"#{ad[:status]}\"."
+
+  # Set initial values.
+  offset, page = 0, {}
+
+  begin
+    page = ad_group_ad_srv.get(selector)
+    if page[:entries]
+      page[:entries].each do |ad|
+        puts "Ad ID is %d, type is '%s' and status is '%s'" %
+            [ad[:ad][:id], ad[:ad][:ad_type], ad[:status]]
+      end
+      # Increment values to request the next page.
+      offset += PAGE_SIZE
+      selector[:paging][:start_index] = offset
     end
-  else
-    puts "No ads found for ad group ##{ad_group_id}."
+  end while page[:total_num_entries] > offset
+
+  if page.include?(:total_num_entries)
+    puts "\tAd group ID %d has %d ad(s)." %
+        [ad_group_id, page[:total_num_entries]]
   end
 end
 
 if __FILE__ == $0
   begin
-    get_all_ads()
+    get_text_ads()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{update_ad.rb → basic_operations/pause_ad.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.
 #
@@ -18,7 +19,7 @@
 #           limitations under the License.
 #
 # This example illustrates how to update an ad, setting its status to 'PAUSED'.
-# To create ads, run add_ads.rb.
+# To create ads, run add_text_ads.rb.
 #
 # Tags: AdGroupAdService.mutate
 
@@ -27,7 +28,7 @@ require 'adwords_api'
 
 API_VERSION = :v201109
 
-def update_ad()
+def pause_ad()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -41,15 +42,13 @@ def update_ad()
   ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
   ad_id = 'INSERT_AD_ID_HERE'.to_i
 
-  # Prepare for updating ad.
+  # Prepare operation for updating ad.
   operation = {
     :operator => 'SET',
     :operand => {
       :ad_group_id => ad_group_id,
       :status => 'PAUSED',
-      :ad => {
-        :id => ad_id
-      }
+      :ad => {:id => ad_id}
     }
   }
 
@@ -57,7 +56,7 @@ def update_ad()
   response = ad_group_ad_srv.mutate([operation])
   if response and response[:value]
     ad = response[:value].first
-    puts 'Ad id %d was successfully updated, status set to %s.' %
+    puts "Ad ID %d was successfully updated, status set to '%s'." %
         [ad[:ad][:id], ad[:status]]
   else
     puts 'No ads were updated.'
@@ -66,7 +65,7 @@ end
 
 if __FILE__ == $0
   begin
-    update_ad()
+    pause_ad()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{update_ad_group.rb → basic_operations/update_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/{update_campaign.rb → basic_operations/update_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/{update_ad_group_criterion.rb → basic_operations/update_keyword.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 update an ad group criterion, setting its
-# bid. To create an ad group criterion, run add_ad_group_criterion.rb.
+# This example updates the bid of a keyword. To create a keyword, run
+# add_keywords.rb.
 #
 # Tags: AdGroupCriterionService.mutate
 
@@ -27,7 +28,7 @@ require 'adwords_api'
 
 API_VERSION = :v201109
 
-def update_ad_group_criterion()
+def update_keyword()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -42,7 +43,7 @@ def update_ad_group_criterion()
   ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
   criterion_id = 'INSERT_CRITERION_ID_HERE'.to_i
 
-  # Prepare for updating ad group criterion.
+  # Prepare for updating a keyword.
   operation = {
     :operator => 'SET',
     :operand => {
@@ -69,17 +70,17 @@ def update_ad_group_criterion()
   response = ad_group_criterion_srv.mutate([operation])
   if response and response[:value]
     ad_group_criterion = response[:value].first
-    puts 'Criterion id %d was successfully updated, bid set to %d.' %
+    puts "Keyword ID %d was successfully updated, bid set to %d." %
         [ad_group_criterion[:criterion][:id],
          ad_group_criterion[:bids][:max_cpc][:amount][:micro_amount]]
   else
-    puts 'No criteria were updated.'
+    puts 'No keywords were updated.'
   end
 end
 
 if __FILE__ == $0
   begin
-    update_ad_group_criterion()
+    update_keyword()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{add_experiment.rb → campaign_management/add_experiment.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.sgomes@gmail.com (Sérgio Gomes)
 #
@@ -20,8 +21,8 @@
 # This example creates an experiment using a query percentage of 10, which
 # defines what fraction of auctions should go to the control split (90%) vs.
 # the experiment split (10%), then adds experimental bid changes for criteria
-# and ad groups. To get campaigns, run get_all_campaigns.rb. To get ad groups,
-# run get_all_ad_groups.rb. To get criteria, run get_all_ad_group_criteria.rb.
+# and ad groups. To get campaigns, run get_campaigns.rb. To get ad groups,
+# run get_ad_groups.rb. To get keywords, run get_keywords.rb.
 #
 # Tags: ExperimentService.mutate
 

data/examples/v201109/{perform_mutate_job.rb → campaign_management/add_keywords_in_bulk.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 code sample illustrates how to perform asynchronous requests using the
-# MutateJobService.
+# This code sample illustrates how to add many keywords using asynchronous
+# requests and MutateJobService.
 #
 # Tags: MutateJobService.mutate, MutateJobService.get,
 #       MutateJobService.getResult
@@ -31,7 +32,7 @@ RETRY_INTERVAL = 30
 RETRIES_COUNT = 30
 KEYWORD_NUMBER = 100
 
-def perform_mutate_job()
+def add_keywords_in_bulk()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -44,44 +45,17 @@ def perform_mutate_job()
 
   ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
 
-  # Create list of all operations for the job.
-  operations = []
-
-  # Create an AdGroupAdOperation to add a text ad.
-  operations << {
-    # 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 => 'AdGroupAdOperation',
-    :operator => 'ADD',
-    :operand => {
-      :ad_group_id => ad_group_id,
-      :ad => {
-        :xsi_type => 'TextAd',
-        :headline => 'Luxury Cruise to Mars',
-        :description1 => 'Visit the Red Planet in style.',
-        :description2 => 'Low-gravity fun for everyone!',
-        :url => 'http://www.example.com',
-        :display_url => 'www.example.com',
-      }
-    }
-  }
-
   # Create AdGroupCriterionOperations to add keywords.
-  KEYWORD_NUMBER.times do |index|
-    operations << {
-        :xsi_type => 'AdGroupCriterionOperation',
-        :operator => 'ADD',
-        :operand => {
-            :xsi_type => 'BiddableAdGroupCriterion',
-            :ad_group_id => ad_group_id,
-            :criterion => {
-                :xsi_type => 'Keyword',
-                :match_type => 'BROAD',
-                :text => "mars%d" % index
-            }
-        }
-    }
+  operations = (1..KEYWORD_NUMBER).map do |index|
+    {:xsi_type => 'AdGroupCriterionOperation',
+     :operator => 'ADD',
+     :operand => {
+       :xsi_type => 'BiddableAdGroupCriterion',
+       :ad_group_id => ad_group_id,
+       :criterion => {
+         :xsi_type => 'Keyword',
+         :match_type => 'BROAD',
+         :text => "mars%d" % index}}}
   end
 
   # You can specify up to 3 job IDs that must successfully complete before
@@ -151,13 +125,13 @@ def perform_mutate_job()
       raise StandardError, 'Error retrieving job results; aborting.'
     end
   else
-    puts "Job failed to complete after %d retries" % RETRY_COUNT
+    puts "Job failed to complete after %d retries." % RETRY_COUNT
   end
 end
 
 if __FILE__ == $0
   begin
-    perform_mutate_job()
+    add_keywords_in_bulk()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e