google-adwords-api 0.4.5 → 0.5.0

data/examples/v201109/{add_campaign_ad_extension.rb → campaign_management/add_location_extension.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,7 +18,7 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example illustrates how to create a campaign ad extension for an existing
+# This example illustrates how to create a location ad extension for an existing
 # campaign. To create a campaign, run add_campaign.rb.
 #
 # Tags: GeoLocationService.get, CampaignAdExtensionService.mutate
@@ -27,7 +28,7 @@ require 'adwords_api'
 
 API_VERSION = :v201109
 
-def add_campaign_ad_extension()
+def add_location_extension()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -60,48 +61,38 @@ def add_campaign_ad_extension()
     ]
   }
 
-  # Get the geo location info for the various addresses and build the operations
-  # with that information.
+  # Get the geo location info for the various addresses and build a list of
+  # operations with that information.
   locations = geo_location_srv.get(selector)
-  if locations
-    operations = []
-    locations.each do |location|
-      operation = {
-        :operator => 'ADD',
-        :operand => {
-          :campaign_id => campaign_id,
-          :status => 'ACTIVE',
-          :ad_extension => {
-            # 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 => 'LocationExtension',
-            :address => location[:address],
-            :geo_point => location[:geo_point],
-            :encoded_location => location[:encoded_location],
-            :source => 'ADWORDS_FRONTEND'
-          }
-        }
-      }
-      operations << operation
-    end
-  else
-    puts "Unable to retrieve geo locations."
-    exit
+  raise StandardError, 'Unable to retrieve geo locations.' if locations.nil?
+
+  operations = locations.map do |location|
+    {:operator => 'ADD',
+     :operand => {
+       :campaign_id => campaign_id,
+       :status => 'ACTIVE',
+       :ad_extension => {
+         # 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 => 'LocationExtension',
+         :address => location[:address],
+         :geo_point => location[:geo_point],
+         :encoded_location => location[:encoded_location],
+         :source => 'ADWORDS_FRONTEND'}}}
   end
 
-  # Add campaign ad extensions.
+  # Add location ad extensions.
   response = campaign_ad_ext_srv.mutate(operations)
-  extensions = response[:value]
-  extensions.each do |extension|
-    puts "Campaign extension id #{extension[:ad_extension][:id]} and status " +
-        "#{extension[:status]} successfully added."
+  response[:value].each do |extension|
+    puts "Location extension ID %d and status '%s' successfully added." %
+        [extension[:ad_extension][:id], extension[:status]]
   end
 end
 
 if __FILE__ == $0
   begin
-    add_campaign_ad_extension()
+    add_location_extension()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{add_ad_extension_override.rb → campaign_management/add_location_extension_override.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,8 +19,8 @@
 #           limitations under the License.
 #
 # This example illustrates override an ad extension for a specific ad, by
-# creating an ad extension override. To create a campaign, run add_campaign.rb.
-# To create an ad, run add_ads.rb.
+# creating a location extension override. To create a campaign, run
+# add_campaign.rb, to create an ad, run add_text_ads.rb.
 #
 # Tags: AdExtensionOverrideService.mutate
 
@@ -28,7 +29,7 @@ require 'adwords_api'
 
 API_VERSION = :v201109
 
-def add_ad_extension_override()
+def add_location_extension_override()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -41,7 +42,7 @@ def add_ad_extension_override()
       adwords.service(:AdExtensionOverrideService, API_VERSION)
 
   ad_id = 'INSERT_AD_ID_HERE'.to_i
-  campaign_ad_extension_id = 'INSERT_CAMPAIGN_AD_EXTENSION_ID_HERE'.to_i
+  location_extension_id = 'INSERT_LOCATION_EXTENSION_ID_HERE'.to_i
 
   # Create operation.
   operation = {
@@ -49,20 +50,21 @@ def add_ad_extension_override()
     :operand => {
       :ad_id => ad_id,
       :ad_extension => {
-        :id => campaign_ad_extension_id
+        :id => location_extension_id
       }
     }
   }
 
   # Add override.
   response = ad_ext_override_srv.mutate([operation])
-  ad_ext_override = response[:value].first
-  puts 'Ad extension override was successfully added.'
+  location_extension_override = response[:value].first
+  puts "Location extension override with ID %d was successfully added." %
+      location_extension_override[:id]
 end
 
 if __FILE__ == $0
   begin
-    add_ad_extension_override()
+    add_location_extension_override()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

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

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.sgomes@gmail.com (Sérgio Gomes)
 #
@@ -18,7 +19,7 @@
 #           limitations under the License.
 #
 # This example illustrates how to retrieve all the disapproved ads in a given
-# ad group. To add ads, run add_ads.rb.
+# ad group. To add ads, run add_text_ads.rb.
 #
 # Tags: AdGroupAdService.get
 

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

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.sgomes@gmail.com (Sérgio Gomes)
 #
@@ -18,8 +19,7 @@
 #           limitations under the License.
 #
 # This example promotes an experiment, which permanently applies all the
-# experiment changes made to its related ad groups, criteria and ads. To get
-# experiments, run get_all_experiments.rb.
+# experiment changes made to its related ad groups, criteria and ads.
 #
 # Tags: ExperimentService.mutate
 
@@ -53,7 +53,7 @@ def promote_experiment()
   # Update experiment.
   response = experiment_srv.mutate([operation])
   experiment = response[:value].first
-  puts 'Experiment with name "%s" and id %d was promoted.' %
+  puts "Experiment with name '%s' and ID %d was promoted." %
       [experiment[:name], experiment[:id]]
 end
 

data/examples/v201109/{set_ad_params.rb → campaign_management/set_ad_parameters.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.sgomes@gmail.com (Sérgio Gomes)
 #
@@ -18,8 +19,7 @@
 #           limitations under the License.
 #
 # This example illustrates how to create a text ad with ad parameters. To add an
-# ad group, run add_ad_group.rb. To add an ad group criterion, run
-# add_ad_group_criterion.rb.
+# ad group, run add_ad_group.rb. To add a keyword, run add_keywords.rb.
 #
 # Tags: AdGroupAdService.mutate, AdParamService.mutate
 
@@ -28,7 +28,7 @@ require 'adwords_api'
 
 API_VERSION = :v201109
 
-def set_ad_params()
+def set_ad_parameters()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -74,7 +74,7 @@ def set_ad_params()
       :ad_group_id => ad_group_id,
       :criterion_id => criterion_id,
       :param_index => 1,
-      :insertion_text => "$100"
+      :insertion_text => '$100'
     }
   }
 
@@ -84,7 +84,7 @@ def set_ad_params()
       :ad_group_id => ad_group_id,
       :criterion_id => criterion_id,
       :param_index => 2,
-      :insertion_text => "50"
+      :insertion_text => '50'
     }
   }
 
@@ -95,7 +95,7 @@ end
 
 if __FILE__ == $0
   begin
-    set_ad_params()
+    set_ad_parameters()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/{v201003/delete_ad.rb → v201109/campaign_management/validate_text_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.
 #
@@ -17,17 +18,17 @@
 #           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 shows how to use the 'validate only' header. No objects will be
+# created, but exceptions will still be thrown.
 #
-# Tags: AdGroupAdService.mutate
+# Tags: CampaignService.mutate
 
 require 'rubygems'
 require 'adwords_api'
 
-API_VERSION = :v201003
+API_VERSION = :v201109
 
-def delete_ad()
+def validate_text_ad()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -39,33 +40,56 @@ def delete_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 deleting ad.
+  # Enable 'validate only' option.
+  adwords.validate_only = true
+
+  # Prepare for adding text ad.
   operation = {
-    :operator => 'REMOVE',
+    :operator => 'ADD',
     :operand => {
       :ad_group_id => ad_group_id,
       :ad => {
-        :xsi_type => 'Ad',
-        :id => ad_id
+        :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'
       }
     }
   }
 
-  # Delete ad.
+  # Validate text ad add operation.
   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 "Unexpected ad creation! Name '%s', ID %d and status '%s'." %
+        [campaign[:name], campaign[:id], campaign[:status]]
   else
-    puts 'No ads were deleted.'
+    puts 'Text ad validated, no error thrown and no ad created.'
+  end
+
+  # Now let's check an invalid ad using extra punctuation to trigger an error.
+  operation[:operand][:ad][:headline] = 'Luxury Cruise to Mars!!!!!'
+
+  # Validate text ad add operation.
+  begin
+    response = ad_group_ad_srv.mutate([operation])
+    if response and response[:value]
+      ad = response[:value].first
+      puts "Unexpected ad creation! Name '%s', ID %d and status '%s'." %
+          [campaign[:name], campaign[:id], campaign[:status]]
+    end
+  rescue AdwordsApi::Errors::ApiException => e
+    puts "Validation correctly failed with an exception: %s" % e.class
+    raise e
   end
 end
 
 if __FILE__ == $0
   begin
-    delete_ad()
+    validate_text_ad()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{handle_partial_failures.rb → error_handling/handle_partial_failures.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/{handle_policy_violation_error.rb → error_handling/handle_policy_violation_error.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/{handle_second_factor.rb → error_handling/handle_two_factor_authorization_error.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.dklimkin@gmail.com (Danial Klimkin)
 #
@@ -17,14 +18,14 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example illustrates how to handle 2 factor authorization errors.
+# This example illustrates how to handle 'two factor' authorization error.
 
 require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109
 
-def handle_second_factor()
+def handle_two_factor_authorization_error()
   # Set up credentials with an account that has 2Factor enabled.
   config = {
       :authentication => {
@@ -67,7 +68,7 @@ end
 
 if __FILE__ == $0
   begin
-    handle_second_factor()
+    handle_two_factor_authorization_error()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{get_all_images.rb → misc/get_all_images_and_videos.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,9 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example illustrates how to retrieve all images. To upload an image, run
-# upload_image.rb.
+# This example illustrates how to retrieve all images and videos. To upload an
+# image, run upload_image.rb. To upload video, see:
+#   http://adwords.google.com/support/aw/bin/answer.py?hl=en&answer=39454.
 #
 # Tags: MediaService.get
 
@@ -27,8 +29,9 @@ require 'adwords_api'
 require 'adwords_api/utils'
 
 API_VERSION = :v201109
+PAGE_SIZE = 500
 
-def get_all_images()
+def get_all_images_and_videos()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -39,30 +42,47 @@ def get_all_images()
 
   media_srv = adwords.service(:MediaService, API_VERSION)
 
-  # Get all the images.
+  # Get all the images and videos.
   selector = {
     :fields => ['MediaId', 'Height', 'Width', 'MimeType', 'Urls'],
-    :ordering => [{:field => 'MediaId', :sort_order => 'ASCENDING'}],
-    :predicates => [{:field => 'Type', :operator => 'IN', :values => ['IMAGE']}]
+    :ordering => [
+      {:field => 'MediaId', :sort_order => 'ASCENDING'}
+    ],
+    :predicates => [
+      {:field => 'Type', :operator => 'IN', :values => ['IMAGE', 'VIDEO']}
+    ],
+    :paging => {
+      :start_index => 0,
+      :number_results => PAGE_SIZE
+    }
   }
-  response = media_srv.get(selector)
-  if response and response[:entries]
-    images = response[:entries]
-    puts "#{images.length} images(s) found."
-    images.each do |image|
-      dimensions = AdwordsApi::Utils.map(image[:dimensions])
-      puts "  Image id is #{image[:media_id]}, dimensions are " +
-          "#{dimensions['FULL'][:height]}x#{dimensions['FULL'][:width]} " +
-          "and MIME type is \"#{image[:mime_type]}\"."
+
+  # Set initial values.
+  offset, page = 0, {}
+
+  begin
+    page = media_srv.get(selector)
+    if page[:entries]
+      page[:entries].each do |entry|
+        dimensions = AdwordsApi::Utils.map(entry[:dimensions])
+        puts "Entry ID %d with dimensions %dx%d and MIME type is '%s'" %
+            [entry[:media_id], dimensions['FULL'][:height],
+             dimensions['FULL'][:width], entry[:mime_type]]
+      end
+      # Increment values to request the next page.
+      offset += PAGE_SIZE
+      selector[:paging][:start_index] = offset
     end
-  else
-    puts "No images found."
+  end while page[:total_num_entries] > offset
+
+  if page.include?(:total_num_entries)
+    puts "\tFound %d entries." % page[:total_num_entries]
   end
 end
 
 if __FILE__ == $0
   begin
-    get_all_images()
+    get_all_images_and_videos()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e