google-adwords-api 0.4.5 → 0.5.0

data/examples/{v200909/update_ad.rb → v201109/basic_operations/add_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,17 +18,17 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example illustrates how to update an ad, setting its status to 'PAUSED'.
-# To create ads, run add_ads.rb.
+# This example illustrates how to add text ads to a given ad group. To create an
+# ad group, run add_ad_group.rb.
 #
 # Tags: AdGroupAdService.mutate
 
 require 'rubygems'
 require 'adwords_api'
 
-API_VERSION = :v200909
+API_VERSION = :v201109
 
-def update_ad()
+def add_text_ads()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -39,34 +40,49 @@ def update_ad()
   ad_group_ad_srv = adwords.service(:AdGroupAdService, API_VERSION)
 
   ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
-  ad_id = 'INSERT_AD_ID_HERE'.to_i
 
-  # Prepare for updating ad.
-  operation = {
-    :operator => 'SET',
-    :operand => {
-      :ad_group_id => ad_group_id,
-      :status => 'PAUSED',
-      :ad => {
-        :id => ad_id
-      }
-    }
-  }
+  # Create text ads.
+  # 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.
+  text_ads = [
+    {: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'},
+    {:xsi_type => 'TextAd',
+     :headline => 'Luxury Cruise to Mars',
+     :description1 => 'Enjoy your stay at Red Planet.',
+     :description2 => 'Buy your tickets now!',
+     :url => 'http://www.example.com',
+     :display_url => 'www.example.com'}
+  ]
 
-  # Update ad.
-  response = ad_group_ad_srv.mutate([operation])
+  # Create ad 'ADD' operations.
+  text_ad_operations = text_ads.map do |text_ad|
+    {:operator => 'ADD',
+     :operand => {:ad_group_id => ad_group_id, :ad => text_ad}}
+  end
+
+  # Add ads.
+  response = ad_group_ad_srv.mutate(text_ad_operations)
   if response and response[:value]
-    ad = response[:value].first
-    puts 'Ad id %d was successfully updated, status set to %s.' %
-        [ad[:ad][:id], ad[:status]]
+    ads = response[:value]
+    puts "Added %d ad(s) to ad group ID %d:" % [ads.length, ad_group_id]
+    ads.each do |ad|
+      puts "\tAd ID %d, type '%s' and status '%s'" %
+          [ad[:ad][:id], ad[:ad][:ad_type], ad[:status]]
+    end
   else
-    puts 'No ads were updated.'
+    puts 'No ads were added.'
   end
 end
 
 if __FILE__ == $0
   begin
-    update_ad()
+    add_text_ads()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

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

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.sgomes@gmail.com (Sérgio Gomes)
 #
@@ -17,8 +18,8 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example deletes an ad using the 'REMOVE' operator. To get ads,
-# run get_all_ads.rb.
+# This example deletes an ad using the 'REMOVE' operator. To get ads, run
+# get_text_ads.rb.
 #
 # Tags: AdGroupAdService.mutate
 
@@ -57,7 +58,7 @@ def delete_ad()
   response = ad_group_ad_srv.mutate([operation])
   if response and response[:value]
     ad = response[:value].first
-    puts 'Ad id %d was successfully deleted.' % ad[:ad][:id]
+    puts "Ad ID %d was successfully deleted." % ad[:ad][:id]
   else
     puts 'No ads were deleted.'
   end

data/examples/v201109/{delete_ad_group.rb → basic_operations/delete_ad_group.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 deletes an ad group by setting the status to 'DELETED'.
-# To get ad groups, run get_all_ad_groups.rb.
+# This example deletes an ad group by setting the status to 'DELETED'. To get ad
+# groups, run get_ad_groups.rb.
 #
 # Tags: AdGroupService.mutate
 
@@ -40,19 +41,44 @@ def delete_ad_group()
 
   ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
 
+  # Retrieve the ad group to obtain it's name. This is optional but recommended
+  # to keep deleted objects searchable. In production the name is already known
+  # in most cases.
+  selector = {
+    :fields => ['Id', 'Name'],
+    :predicates => [
+      {:field => 'Id', :operator => 'EQUALS', :values => [ad_group_id]}
+    ]
+  }
+  result = ad_group_srv.get(selector)
+
+  if result.nil? or result[:entries].empty?
+    raise StandardError, "Ad group with ID %d was not found." % ad_group_id
+  end
+
+  # We recommend renaming object on delete to avoid name conflicts later.
+  ad_group_name = result[:entries].first[:name]
+  ad_group_name += Time.now.strftime(" (deleted on %Y-%m-%d %H:%M:%S)")
+
   # Prepare for deleting ad group.
   operation = {
     :operator => 'SET',
     :operand => {
-      :status => 'DELETED',
-      :id => ad_group_id
+      :id => ad_group_id,
+      :name => ad_group_name,
+      :status => 'DELETED'
     }
   }
 
   # Delete ad group.
   response = ad_group_srv.mutate([operation])
-  ad_group = response[:value].first
-  puts 'Ad group id %d was successfully deleted.' % ad_group[:id]
+  if response and response[:value]
+    ad_group = response[:value].first
+    puts "Ad group ID %d was successfully deleted and renamed to '%s'." %
+       [ad_group[:id], ad_group[:name]]
+  else
+    puts 'No ad group was updated.'
+  end
 end
 
 if __FILE__ == $0

data/examples/v201109/{delete_campaign.rb → basic_operations/delete_campaign.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 deletes a campaign by setting the status to 'DELETED'. To get
-# campaigns, run get_all_campaigns.rb.
+# campaigns, run get_campaigns.rb.
 #
 # Tags: CampaignService.mutate
 
@@ -40,20 +41,45 @@ def delete_campaign()
 
   campaign_id = 'INSERT_CAMPAIGN_ID_HERE'.to_i
 
+  # Retrieve the campaign to obtain it's name. This is optional but recommended
+  # to keep deleted objects searchable. In production the name is already known
+  # in most cases.
+  selector = {
+    :fields => ['Id', 'Name'],
+    :predicates => [
+      {:field => 'Id', :operator => 'EQUALS', :values => [campaign_id]}
+    ]
+  }
+  result = campaign_srv.get(selector)
+
+  if result.nil? or result[:entries].empty?
+    raise StandardError, "Campaign with ID %d was not found." % campaign_id
+  end
+
+  # We recommend renaming object on delete to avoid name conflicts later.
+  campaign_name = result[:entries].first[:name]
+  campaign_name += Time.now.strftime(" (deleted on %Y-%m-%d %H:%M:%S)")
+
   # Prepare for deleting campaign.
   operation = {
     :operator => 'SET',
     :operand => {
       :id => campaign_id,
+      :name => campaign_name,
       :status => 'DELETED',
     }
   }
 
   # Delete campaign.
   response = campaign_srv.mutate([operation])
-  campaign = response[:value].first
-  puts 'Campaign with name "%s" and id %d was deleted.' %
-      [campaign[:name], campaign[:id]]
+
+  if response and response[:value]
+    campaign = response[:value].first
+    puts "Campaign ID %d was renamed to '%s' and deleted." %
+        [campaign[:id], campaign[:name]]
+  else
+    puts 'No campaign was updated.'
+  end
 end
 
 if __FILE__ == $0

data/examples/v201109/{delete_ad_group_criterion.rb → basic_operations/delete_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 deletes an ad group criterion using the 'REMOVE' operator. To
-# get ad group criteria, run get_all_ad_group_criteria.rb.
+# This example deletes a keyword using the 'REMOVE' operator. To get list of
+# keywords, run get_keywords.rb.
 #
 # Tags: AdGroupCriterionService.mutate
 
@@ -27,7 +28,7 @@ require 'adwords_api'
 
 API_VERSION = :v201109
 
-def delete_ad_group_criterion()
+def delete_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 delete_ad_group_criterion()
   ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
   criterion_id = 'INSERT_CRITERION_ID_HERE'.to_i
 
-  # Prepare for deleting ad group criterion.
+  # Prepare for deleting keyword.
   operation = {
     :operator => 'REMOVE',
     :operand => {
@@ -57,16 +58,20 @@ def delete_ad_group_criterion()
     }
   }
 
-  # Delete criterion.
+  # Delete keyword.
   response = ad_group_criterion_srv.mutate([operation])
   ad_group_criterion = response[:value].first
-  puts 'Criterion id %d was successfully deleted.' %
-      ad_group_criterion[:criterion][:id]
+  if ad_group_criterion
+    puts "Keyword ID %d was successfully deleted." %
+        ad_group_criterion[:criterion][:id]
+  else
+    puts 'No keywords were deleted.'
+  end
 end
 
 if __FILE__ == $0
   begin
-    delete_ad_group_criterion()
+    delete_keyword()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{get_all_ad_groups.rb → basic_operations/get_ad_groups.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.
 #
@@ -26,8 +27,9 @@ require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109
+PAGE_SIZE = 500
 
-def get_all_ad_groups()
+def get_ad_groups()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -44,28 +46,40 @@ def get_all_ad_groups()
   selector = {
     :fields => ['Id', 'Name'],
     :ordering => [{:field => 'Name', :sort_order => 'ASCENDING'}],
-    :predicates => [{
-      :field => 'CampaignId',
-      :operator => 'IN',
-      :values => [campaign_id]
-    }]
+    :predicates => [
+      {:field => 'CampaignId', :operator => 'IN', :values => [campaign_id]}
+    ],
+    :paging => {
+      :start_index => 0,
+      :number_results => PAGE_SIZE
+    }
   }
-  response = ad_group_srv.get(selector)
-  if response and response[:entries]
-    ad_groups = response[:entries]
-    puts "Campaign ##{campaign_id} has #{ad_groups.length} ad group(s)."
-    ad_groups.each do |ad_group|
-      puts "  Ad group name is \"#{ad_group[:name]}\" and id is " +
-          "#{ad_group[:id]}."
+
+  # Set initial values.
+  offset, page = 0, {}
+
+  begin
+    page = ad_group_srv.get(selector)
+    if page[:entries]
+      page[:entries].each do |ad_group|
+        puts "Ad group name is '%s' and ID is %d" %
+            [ad_group[:name], ad_group[:id]]
+      end
+      # Increment values to request the next page.
+      offset += PAGE_SIZE
+      selector[:paging][:start_index] = offset
     end
-  else
-    puts "No ad groups found for campaign ##{campaign_id}."
+  end while page[:total_num_entries] > offset
+
+  if page.include?(:total_num_entries)
+    puts "\tCampaign ID %d has %d ad group(s)." %
+        [campaign_id, page[:total_num_entries]]
   end
 end
 
 if __FILE__ == $0
   begin
-    get_all_ad_groups()
+    get_ad_groups()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{get_all_campaigns.rb → basic_operations/get_campaigns.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.
 #
@@ -25,8 +26,9 @@ require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109
+PAGE_SIZE = 500
 
-def get_all_campaigns()
+def get_campaigns()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -37,27 +39,42 @@ def get_all_campaigns()
 
   campaign_srv = adwords.service(:CampaignService, API_VERSION)
 
-  # Get all the campaigns for this account; empty selector.
+  # Get all the campaigns for this account.
   selector = {
     :fields => ['Id', 'Name', 'Status'],
-    :ordering => [{:field => 'Name', :sort_order => 'ASCENDING'}]
+    :ordering => [
+      {:field => 'Name', :sort_order => 'ASCENDING'}
+    ],
+    :paging => {
+      :start_index => 0,
+      :number_results => PAGE_SIZE
+    }
   }
-  response = campaign_srv.get(selector)
 
-  if response and response[:entries]
-    campaigns = response[:entries]
-    campaigns.each do |campaign|
-      puts "Campaign name is \"#{campaign[:name]}\", id is #{campaign[:id]} " +
-          "and status is \"#{campaign[:status]}\"."
+  # Set initial values.
+  offset, page = 0, {}
+
+  begin
+    page = campaign_srv.get(selector)
+    if page[:entries]
+      page[:entries].each do |campaign|
+        puts "Campaign ID %d, name '%s' and status '%s'" %
+            [campaign[:id], campaign[:name], campaign[:status]]
+      end
+      # Increment values to request the next page.
+      offset += PAGE_SIZE
+      selector[:paging][:start_index] = offset
     end
-  else
-    puts "No campaigns were found."
+  end while page[:total_num_entries] > offset
+
+  if page.include?(:total_num_entries)
+    puts "\tTotal number of campaigns found: %d." % [page[:total_num_entries]]
   end
 end
 
 if __FILE__ == $0
   begin
-    get_all_campaigns()
+    get_campaigns()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e