google-adx-buyer-api 0.4.0 → 0.4.1

data/examples/{v201101/get_all_ad_groups.rb → v201109/basic_operations/get_ad_groups.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.sgomes@gmail.com (Sérgio Gomes)
 #
@@ -22,13 +23,9 @@
 #
 # Tags: AdGroupService.get
 
-require 'rubygems'
-gem 'google-adwords-api'
 require 'adwords_api'
 
-API_VERSION = :v201101
-
-def get_all_ad_groups()
+def get_all_ad_groups(campaign_id)
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -39,8 +36,6 @@ def get_all_ad_groups()
 
   ad_group_srv = adwords.service(:AdGroupService, API_VERSION)
 
-  campaign_id = 'INSERT_CAMPAIGN_ID_HERE'.to_i
-
   # Get all the ad groups for this campaign.
   selector = {
     :fields => ['Id', 'Name'],
@@ -52,42 +47,33 @@ def get_all_ad_groups()
     }]
   }
   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]}."
-    end
-  else
-    puts "No ad groups found for campaign ##{campaign_id}."
+  ad_groups = response[:entries]
+  puts "Campaign ID %d has %d ad group(s)." % [campaign_id, ad_groups.length]
+  ad_groups.each do |ad_group|
+    puts "\tAd group name is '%s' and ID is %d" %
+        [ad_group[:name], ad_group[:id]]
   end
 end
 
 if __FILE__ == $0
+  API_VERSION = :v201109
+
   begin
-    get_all_ad_groups()
+    campaign_id = 'INSERT_CAMPAIGN_ID_HERE'.to_i
+    get_all_ad_groups(campaign_id)
 
-  # Connection error. Likely transitory.
-  rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => e
-    puts 'Connection Error: %s' % e
-    puts 'Source: %s' % e.backtrace.first
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
 
-  # API Error.
+  # API errors.
   rescue AdwordsApi::Errors::ApiException => e
-    puts 'API Exception caught.'
-    puts 'Message: %s' % e.message
-    puts 'Code: %d' % e.code if e.code
-    puts 'Trigger: %s' % e.trigger if e.trigger
+    puts "Message: %s" % e.message
     puts 'Errors:'
-    if e.errors
-      e.errors.each_with_index do |error, index|
-        puts ' %d. Error type is %s. Fields:' % [index + 1, error[:xsi_type]]
-        error.each_pair do |field, value|
-          if field != :xsi_type
-            puts '     %s: %s' % [field, value]
-          end
-        end
+    e.errors.each_with_index do |error, index|
+      puts "\tError [%d]:" % (index + 1)
+      error.each do |field, value|
+        puts "\t\t%s: %s" % [field, value]
       end
     end
   end

data/examples/{v201101/get_all_campaigns.rb → v201109/basic_operations/get_campaigns.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.sgomes@gmail.com (Sérgio Gomes)
 #
@@ -21,12 +22,8 @@
 #
 # Tags: CampaignService.get
 
-require 'rubygems'
-gem 'google-adwords-api'
 require 'adwords_api'
 
-API_VERSION = :v201101
-
 def get_all_campaigns()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
@@ -52,34 +49,28 @@ def get_all_campaigns()
           "and status is \"#{campaign[:status]}\"."
     end
   else
-    puts "No campaigns were found."
+    puts 'No campaigns were found.'
   end
 end
 
 if __FILE__ == $0
+  API_VERSION = :v201109
+
   begin
     get_all_campaigns()
 
-  # Connection error. Likely transitory.
-  rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => e
-    puts 'Connection Error: %s' % e
-    puts 'Source: %s' % e.backtrace.first
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
 
-  # API Error.
+  # API errors.
   rescue AdwordsApi::Errors::ApiException => e
-    puts 'API Exception caught.'
-    puts 'Message: %s' % e.message
-    puts 'Code: %d' % e.code if e.code
-    puts 'Trigger: %s' % e.trigger if e.trigger
+    puts "Message: %s" % e.message
     puts 'Errors:'
-    if e.errors
-      e.errors.each_with_index do |error, index|
-        puts ' %d. Error type is %s. Fields:' % [index + 1, error[:xsi_type]]
-        error.each_pair do |field, value|
-          if field != :xsi_type
-            puts '     %s: %s' % [field, value]
-          end
-        end
+    e.errors.each_with_index do |error, index|
+      puts "\tError [%d]:" % (index + 1)
+      error.each do |field, value|
+        puts "\t\t%s: %s" % [field, value]
       end
     end
   end

data/examples/{v201008/get_all_ad_group_criteria.rb → v201109/basic_operations/get_placements.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,14 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example illustrates how to retrieve all the 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 the placements for an ad group.
+# To add a placement to an existing ad group, run add_placements.rb.
 #
 # Tags: AdGroupCriterionService.get
 
-require 'rubygems'
-gem 'google-adwords-api'
 require 'adwords_api'
 
-API_VERSION = :v201008
-
-def get_all_ad_group_criteria()
+def get_placements(ad_group_id)
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -40,51 +37,55 @@ def get_all_ad_group_criteria()
   ad_group_criterion_srv =
       adwords.service(:AdGroupCriterionService, API_VERSION)
 
-  ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
-
   # Get all the criteria for this ad group.
   selector = {
-    :id_filters => [{
-      :ad_group_id => ad_group_id
-    }]
+    :fields => ['Id', 'PlacementUrl'],
+    :ordering => [
+      {:field => 'AdGroupId', :sort_order => 'ASCENDING'}
+    ],
+    :predicates => [
+      {:field => 'AdGroupId', :operator => 'IN', :values => [ad_group_id]},
+      {
+        :field => 'CriteriaType',
+        :operator => 'EQUALS',
+        :values => ['PLACEMENT']
+      }
+    ]
   }
   response = ad_group_criterion_srv.get(selector)
   if response and response[:entries]
     ad_group_criteria = response[:entries]
-    puts "Ad group ##{ad_group_id} has #{ad_group_criteria.length} criteria."
+    puts "Ad group ID %d has %d placements." %
+        [ad_group_id, ad_group_criteria.length]
     ad_group_criteria.each do |ad_group_criterion|
-      puts "  Criterion id is #{ad_group_criterion[:criterion][:id]} and " +
-          "type is #{ad_group_criterion[:criterion][:xsi_type]}."
+      puts "\tPlacement ID is %d and URL is '%s'." %
+          [ad_group_criterion[:criterion][:id],
+           ad_group_criterion[:criterion][:placement_url]]
     end
   else
-    puts "No criteria found for ad group ##{ad_group_id}."
+    puts "No placements found for ad group ID %d" % ad_group_id
   end
 end
 
 if __FILE__ == $0
+  API_VERSION = :v201109
+
   begin
-    get_all_ad_group_criteria()
+    ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
+    get_placements(ad_group_id)
 
-  # Connection error. Likely transitory.
-  rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => e
-    puts 'Connection Error: %s' % e
-    puts 'Source: %s' % e.backtrace.first
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
 
-  # API Error.
+  # API errors.
   rescue AdwordsApi::Errors::ApiException => e
-    puts 'API Exception caught.'
-    puts 'Message: %s' % e.message
-    puts 'Code: %d' % e.code if e.code
-    puts 'Trigger: %s' % e.trigger if e.trigger
+    puts "Message: %s" % e.message
     puts 'Errors:'
-    if e.errors
-      e.errors.each_with_index do |error, index|
-        puts ' %d. Error type is %s. Fields:' % [index + 1, error[:xsi_type]]
-        error.each_pair do |field, value|
-          if field != :xsi_type
-            puts '     %s: %s' % [field, value]
-          end
-        end
+    e.errors.each_with_index do |error, index|
+      puts "\tError [%d]:" % (index + 1)
+      error.each do |field, value|
+        puts "\t\t%s: %s" % [field, value]
       end
     end
   end

data/examples/v201109/{get_all_ads.rb → basic_operations/get_thirdparty_redirect_ads.rb}

@@ -1,8 +1,9 @@
-#!/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.
+# 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.
@@ -17,18 +18,15 @@
 #           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 third party redirect ads for an
+# ad group. To add third party redirect ad to an existing ad group, run
+# add_thirdparty_redirect_ad.rb.
 #
 # Tags: AdGroupAdService.get
 
-require 'rubygems'
-gem 'google-adwords-api'
 require 'adwords_api'
 
-API_VERSION = :v201109
-
-def get_all_ads()
+def get_all_ads(ad_group_id)
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -39,11 +37,9 @@ def get_all_ads()
 
   ad_group_ad_srv = adwords.service(:AdGroupAdService, API_VERSION)
 
-  ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
-
-  # Get all the ads for this ad group.
+  # Create selector to get all third party redirect ads for this ad group.
   selector = {
-    :fields => ['Id', 'Status'],
+    :fields => ['Id', 'Status', 'Url', 'DisplayUrl'],
     :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.
@@ -53,46 +49,51 @@ def get_all_ads()
         :field => 'Status',
         :operator => 'IN',
         :values => ['ENABLED', 'PAUSED', 'DISABLED']
+      },
+      {
+        :field => 'AdType',
+        :operator => 'EQUALS',
+        :values => ['THIRD_PARTY_REDIRECT_AD']
       }
     ]
   }
+
+  # Request the ads.
   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)."
+    puts "Ad group ID %d has %d third party redirect ads." %
+        [ad_group_id, ads.length]
     ads.each do |ad|
-      puts "  Ad id is #{ad[:ad][:id]}, type is #{ad[:ad][:xsi_type]} and " +
-          "status is \"#{ad[:status]}\"."
+      puts "\tAd ID is %d, type is '%s', status is '%s'" %
+          [ad[:ad][:id], ad[:ad][:xsi_type], ad[:status]]
+      puts "\tURL:         %s" % ad[:url]
+      puts "\tDisplay URL: %s" % ad[:display_url]
     end
   else
-    puts "No ads found for ad group ##{ad_group_id}."
+    puts "No ads found for ad group ID %d." % ad_group_id
   end
 end
 
 if __FILE__ == $0
+  API_VERSION = :v201109
+
   begin
-    get_all_ads()
+    ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
+    get_all_ads(ad_group_id)
 
-  # Connection error. Likely transitory.
-  rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => e
-    puts 'Connection Error: %s' % e
-    puts 'Source: %s' % e.backtrace.first
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
 
-  # API Error.
+  # API errors.
   rescue AdwordsApi::Errors::ApiException => e
-    puts 'API Exception caught.'
-    puts 'Message: %s' % e.message
-    puts 'Code: %d' % e.code if e.code
-    puts 'Trigger: %s' % e.trigger if e.trigger
+    puts "Message: %s" % e.message
     puts 'Errors:'
-    if e.errors
-      e.errors.each_with_index do |error, index|
-        puts ' %d. Error type is %s. Fields:' % [index + 1, error[:xsi_type]]
-        error.each_pair do |field, value|
-          if field != :xsi_type
-            puts '     %s: %s' % [field, value]
-          end
-        end
+    e.errors.each_with_index do |error, index|
+      puts "\tError [%d]:" % (index + 1)
+      error.each do |field, value|
+        puts "\t\t%s: %s" % [field, value]
       end
     end
   end

data/examples/v201109/{get_client_customer_id.rb → basic_operations/pause_ad.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.dklimkin@gmail.com (Danial Klimkin)
 #
@@ -17,19 +18,14 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example illustrates how to find a client customer ID for a client email.
-# We recommend to use this script as a one off to convert your identifiers to
-# IDs and store them for future use.
+# This example illustrates how to pause an ad, setting its status to 'PAUSED'.
+# To create ads, run add_thirdparty_redirect_ad.rb.
 #
-# Tags: InfoService.get
+# Tags: AdGroupAdService.mutate
 
-require 'rubygems'
 require 'adwords_api'
-require 'adwords_api/utils'
 
-API_VERSION = :v201109
-
-def get_client_customer_id()
+def pause_ad(ad_group_id, ad_id)
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -38,36 +34,34 @@ def get_client_customer_id()
   # the configuration file or provide your own logger:
   # adwords.logger = Logger.new('adwords_xml.log')
 
-  info_srv = adwords.service(:InfoService, API_VERSION)
-
-  # Email address to find ID for.
-  client_email = 'INSERT_EMAIL_ADDRESS_HERE'
+  ad_group_ad_srv = adwords.service(:AdGroupAdService, API_VERSION)
 
-  today = Time.new.strftime('%Y%m%d')
-
-  selector = {
-    :client_emails => [client_email],
-    :api_usage_type => 'UNIT_COUNT_FOR_CLIENTS',
-    :include_sub_accounts => true,
-    :date_range => {:min => today, :max => today}
+  # Prepare for updating ad.
+  operation = {
+    :operator => 'SET',
+    :operand => {
+      :ad_group_id => ad_group_id,
+      :status => 'PAUSED',
+      :ad => {
+        :id => ad_id
+      }
+    }
   }
 
-  # Get the information for client email address.
-  info = adwords.use_mcc() {info_srv.get(selector)}
-
-  if info and info[:api_usage_records]
-    api_usage_records = info[:api_usage_records]
-    api_usage_records.each do |record|
-      puts "Found record with client email '%s' and ID %s." %
-          [record[:client_email],
-           AdwordsApi::Utils.format_id(record[:client_customer_id])]
-    end
-  end
+  # Update ad.
+  response = ad_group_ad_srv.mutate([operation])
+  ad = response[:value].first
+  puts "Ad ID %d was successfully updated, status set to '%s'." %
+      [ad[:ad][:id], ad[:status]]
 end
 
 if __FILE__ == $0
+  API_VERSION = :v201109
+
   begin
-    get_client_customer_id()
+    ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
+    ad_id = 'INSERT_AD_ID_HERE'.to_i
+    pause_ad(ad_group_id, ad_id)
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e