google-adwords-api 0.8.2 → 0.9.0

data/ChangeLog

@@ -1,3 +1,9 @@
+0.9.0:
+  - Shared set support and examples (beta feature).
+  - Updated feed services auto-generated code.
+  - AdWords for Video API support and examples (beta feature).
+  - Removed deprecated API version v201206.
+
 0.8.2:
   - Support and examples for v201302.
 

data/README

@@ -3,7 +3,7 @@
 Welcome to the next generation Google-developed Ruby client library for the
 AdWords and DoubleClick Ad Exchange Buyer API!
 
-It contains full support for v201206 and v201209, with full stubs, and a
+It contains full support for v201209 and v201302, with full stubs, and a
 simplified programming interface that lets you handle everything in native
 Ruby collections.
 
@@ -58,7 +58,7 @@ You can also pass API a manually constructed config hash like:
    })
 
 Then, just specify which service you're looking to use, and which version:
-   campaign_srv = adwords.service(:CampaignService, :v201209)
+   campaign_srv = adwords.service(:CampaignService, :v201302)
 
 and you should now be able to just use the API methods in the object you were
 returned:
@@ -200,7 +200,7 @@ Questions can be asked on forum
 
 == Licence
 
-Copyright 2010-2012, Google Inc. All Rights Reserved.
+Copyright 2010-2013, Google Inc. All Rights Reserved.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

data/examples/{v201206/basic_operations/delete_ad_group.rb → v201209/adwords_for_video/add_video_campaign.rb}

@@ -3,7 +3,7 @@
 #
 # Author:: api.dklimkin@gmail.com (Danial Klimkin)
 #
-# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
+# Copyright:: Copyright 2013, 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.
@@ -18,14 +18,16 @@
 #           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_ad_groups.rb.
+# This example illustrates how to create a video campaign.
 #
-# Tags: AdGroupService.mutate
+# Note: AdWords for Video API is a Beta feature.
+#
+# Tags: VideoCampaignService.mutate, BudgetService.mutate
 
 require 'adwords_api'
+require 'date'
 
-def delete_ad_group(ad_group_id)
+def add_video_campaign()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -34,55 +36,54 @@ def delete_ad_group(ad_group_id)
   # the configuration file or provide your own logger:
   # adwords.logger = Logger.new('adwords_xml.log')
 
-  ad_group_srv = adwords.service(:AdGroupService, API_VERSION)
+  budget_srv = adwords.service(:BudgetService, API_VERSION)
+  video_campaign_srv = adwords.service(:VideoCampaignService, API_VERSION)
 
-  # Retrieve the ad group to obtain its 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]}
-    ]
+  # Create a budget, which can be shared by multiple campaigns.
+  budget = {
+    :name => 'Video budget #%d' % (Time.new.to_f * 1000).to_i,
+    :amount => {:micro_amount => 50000000},
+    :delivery_method => 'STANDARD',
+    :period => 'DAILY'
   }
-  result = ad_group_srv.get(selector)
+  budget_operation = {:operator => 'ADD', :operand => budget}
 
-  if result.nil? or result[:entries].empty?
-    raise StandardError, "Ad group with ID %d was not found." % ad_group_id
-  end
+  # Add budget.
+  return_budget = budget_srv.mutate([budget_operation])
+  budget_id = return_budget[:value].first[:budget_id]
 
-  # 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)")
+  # Create video campaign.
+  campaigns = [{
+    :name => "Interplanetary Video #%d" % (Time.new.to_f * 1000).to_i,
+    :status => 'PAUSED',
+    :budget_id => budget_id,
+    # Optional fields:
+    :start_date =>
+        DateTime.parse((Date.today + 1).to_s).strftime('%Y%m%d'),
+  }]
 
-  # Prepare for deleting ad group.
-  operation = {
-    :operator => 'SET',
-    :operand => {
-      :id => ad_group_id,
-      :name => ad_group_name,
-      :status => 'DELETED'
-    }
-  }
+  # Prepare for adding campaign.
+  operations = campaigns.map do |campaign|
+    {:operator => 'ADD', :operand => campaign}
+  end
 
-  # Delete ad group.
-  response = ad_group_srv.mutate([operation])
+  # Add video campaign.
+  response = video_campaign_srv.mutate(operations)
   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]]
+    response[:value].each do |campaign|
+      puts "Campaign with name '%s' and ID %d was added." %
+          [campaign[:name], campaign[:id]]
+    end
   else
-    puts 'No ad group was updated.'
+    raise new StandardError, 'No campaigns were added.'
   end
 end
 
 if __FILE__ == $0
-  API_VERSION = :v201206
+  API_VERSION = :v201209
 
   begin
-    # ID of an ad group to delete.
-    ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
-    delete_ad_group(ad_group_id)
+    add_video_campaign()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/{v201206/basic_operations/pause_ad.rb → v201209/adwords_for_video/find_videos.rb}

@@ -3,7 +3,7 @@
 #
 # Author:: api.dklimkin@gmail.com (Danial Klimkin)
 #
-# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
+# Copyright:: Copyright 2013, 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.
@@ -18,14 +18,16 @@
 #           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_text_ads.rb.
+# This example illustrates how to find YouTube videos by a search string. It
+# retrieve details for the first 100 matching videos.
 #
-# Tags: AdGroupAdService.mutate
+# Note: AdWords for Video API is a Beta feature.
+#
+# Tags: VideoService.search
 
 require 'adwords_api'
 
-def pause_ad(ad_group_id, ad_id)
+def find_videos()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -34,37 +36,43 @@ def pause_ad(ad_group_id, ad_id)
   # the configuration file or provide your own logger:
   # adwords.logger = Logger.new('adwords_xml.log')
 
-  ad_group_ad_srv = adwords.service(:AdGroupAdService, API_VERSION)
+  video_srv = adwords.service(:VideoService, API_VERSION)
+
+  # Search string to use.
+  query_str = 'AdWords API with Ruby'
 
-  # Prepare operation for updating ad.
-  operation = {
-    :operator => 'SET',
-    :operand => {
-      :ad_group_id => ad_group_id,
-      :status => 'PAUSED',
-      :ad => {:id => ad_id}
+  # Create a selector.
+  selector = {
+    :search_type => 'VIDEO',
+    :query => query_str,
+    :paging => {
+      :start_index => 0,
+      :number_results => PAGE_SIZE
     }
   }
 
-  # 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'." %
-        [ad[:ad][:id], ad[:status]]
+  # Run the query.
+  page = video_srv.search(selector)
+
+  if page[:entries]
+    page[:entries].each do |video|
+      puts "YouTube video ID '%s' with title '%s' found." %
+          [video[:id], video[:title]]
+    end
+    if page.include?(:total_num_entries)
+      puts "\tTotal number of matching videos: %d." % [page[:total_num_entries]]
+    end
   else
-    puts 'No ads were updated.'
+    puts "No videos matching '%s' were found." % query_str
   end
 end
 
 if __FILE__ == $0
-  API_VERSION = :v201206
+  API_VERSION = :v201209
+  PAGE_SIZE = 100
 
   begin
-    # IDs of ad to pause and its ad group.
-    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)
+    find_videos()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/{v201206/basic_operations/get_keywords.rb → v201209/adwords_for_video/get_keyword_criteria.rb}

@@ -3,7 +3,7 @@
 #
 # Author:: api.dklimkin@gmail.com (Danial Klimkin)
 #
-# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
+# Copyright:: Copyright 2013, 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.
@@ -18,14 +18,16 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example illustrates how to retrieve all keywords for an ad group. To add
-# keywords to an existing ad group, run add_keywords.rb.
+# This example show how to retrieve all keywords for a video campaign. To get
+# a list with all campaigns, run get_video_campaigns.rb.
 #
-# Tags: AdGroupCriterionService.get
+# Note: AdWords for Video API is a Beta feature.
+#
+# Tags: VideoTargetingGroupCriterionService.get
 
 require 'adwords_api'
 
-def get_keywords(ad_group_id)
+def get_keyword_criteria(campaign_id)
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -34,19 +36,13 @@ def get_keywords(ad_group_id)
   # the configuration file or provide your own logger:
   # adwords.logger = Logger.new('adwords_xml.log')
 
-  ad_group_criterion_srv =
-      adwords.service(:AdGroupCriterionService, API_VERSION)
+  vtgc_srv =
+      adwords.service(:VideoTargetingGroupCriterionService, API_VERSION)
 
-  # Get all keywords for this ad group.
+  # Get all the keywords for the campaign.
   selector = {
-    :fields => ['Id', 'CriteriaType', 'KeywordText'],
-    :ordering => [
-      {:field => 'Id', :sort_order => 'ASCENDING'}
-    ],
-    :predicates => [
-      {:field => 'AdGroupId', :operator => 'EQUALS', :values => [ad_group_id]},
-      {:field => 'CriteriaType', :operator => 'EQUALS', :values => ['KEYWORD']}
-    ],
+    :campaign_ids => [campaign_id],
+    :criterion_types => ['SEARCH_KEYWORD'],
     :paging => {
       :start_index => 0,
       :number_results => PAGE_SIZE
@@ -57,13 +53,15 @@ def get_keywords(ad_group_id)
   offset, page = 0, {}
 
   begin
-    page = ad_group_criterion_srv.get(selector)
+    page = vtgc_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]]
+        negative_string =
+            ('NegativeTargetingGroupCriterion'.eql?(keyword[:xsi_type])) ?
+            ' (negative)' : ''
+        puts "Criterion%s ID %d, targeting group ID %d and text '%s'" %
+            [negative_string, keyword[:criterion][:id],
+             keyword[:targeting_group_id], keyword[:criterion][:text]]
       end
       # Increment values to request the next page.
       offset += PAGE_SIZE
@@ -72,19 +70,18 @@ def get_keywords(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]]
+    puts "\tTotal number of keywords found: %d." % [page[:total_num_entries]]
   end
 end
 
 if __FILE__ == $0
-  API_VERSION = :v201206
+  API_VERSION = :v201209
   PAGE_SIZE = 500
 
   begin
-    # Ad group ID to get keywords for.
-    ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
-    get_keywords(ad_group_id)
+    # Campaign ID to get criteria for.
+    campaign_id = 'INSERT_CAMPAIGN_ID_HERE'.to_i
+    get_keyword_criteria(campaign_id)
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/{v201206/basic_operations/get_campaigns_with_awql.rb → v201209/adwords_for_video/get_targeting_groups.rb}

@@ -3,7 +3,7 @@
 #
 # Author:: api.dklimkin@gmail.com (Danial Klimkin)
 #
-# Copyright:: Copyright 2012, Google Inc. All Rights Reserved.
+# Copyright:: Copyright 2013, 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.
@@ -18,14 +18,15 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example illustrates how to retrieve all the campaigns for an account with
-# AWQL.
+# This example show how to retrieve all targeting groups for an account.
 #
-# Tags: CampaignService.query
+# Note: AdWords for Video API is a Beta feature.
+#
+# Tags: VideoTargetingGroupService.get
 
 require 'adwords_api'
 
-def get_campaigns_with_awql()
+def get_targeting_groups()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -34,46 +35,53 @@ def get_campaigns_with_awql()
   # the configuration file or provide your own logger:
   # adwords.logger = Logger.new('adwords_xml.log')
 
-  campaign_srv = adwords.service(:CampaignService, API_VERSION)
+  video_targeting_group_srv =
+      adwords.service(:VideoTargetingGroupService, API_VERSION)
 
-  # Get all the campaigns for this account.
-  query = 'SELECT Id, Name, Status ORDER BY Name'
+  # Get all targeting groups for this account.
+  selector = {
+    :paging => {
+      :start_index => 0,
+      :number_results => PAGE_SIZE
+    }
+  }
 
   # Set initial values.
   offset, page = 0, {}
 
   begin
-    page_query = query + ' LIMIT %d,%d' % [offset, PAGE_SIZE]
-    page = campaign_srv.query(page_query)
+    page = video_targeting_group_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]]
+      page[:entries].each do |group|
+        puts "Targeting group ID %d, campaign ID %d and name '%s'" %
+            [group[:id], group[:campaign_id], group[:name]]
       end
       # Increment values to request the next page.
       offset += PAGE_SIZE
+      selector[:paging][:start_index] = offset
     end
   end while page[:total_num_entries] > offset
 
   if page.include?(:total_num_entries)
-    puts "\tTotal number of campaigns found: %d." % page[:total_num_entries]
+    puts "\tTotal number of targeting groups found: %d." %
+        [page[:total_num_entries]]
   end
 end
 
 if __FILE__ == $0
-  API_VERSION = :v201206
+  API_VERSION = :v201209
   PAGE_SIZE = 500
 
   begin
-    get_campaigns_with_awql()
+    get_targeting_groups()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e
-    puts 'HTTP Error: %s' % e
+    puts "HTTP Error: %s" % e
 
   # API errors.
   rescue AdwordsApi::Errors::ApiException => e
-    puts 'Message: %s' % e.message
+    puts "Message: %s" % e.message
     puts 'Errors:'
     e.errors.each_with_index do |error, index|
       puts "\tError [%d]:" % (index + 1)

data/examples/{v201206/basic_operations/get_ad_groups.rb → v201209/adwords_for_video/get_video_campaign_criteria.rb}

@@ -3,7 +3,7 @@
 #
 # Author:: api.dklimkin@gmail.com (Danial Klimkin)
 #
-# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
+# Copyright:: Copyright 2013, 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.
@@ -18,14 +18,15 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example illustrates how to retrieve all the ad groups for a campaign. To
-# create an ad group, run add_ad_group.rb.
+# This example demonstrates how to retrieve all campaign-level criteria.
 #
-# Tags: AdGroupService.get
+# Note: AdWords for Video API is a Beta feature.
+#
+# Tags: VideoCampaignCriterionService.get
 
 require 'adwords_api'
 
-def get_ad_groups(campaign_id)
+def get_video_campaign_criteria(campaign_id)
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -34,15 +35,12 @@ def get_ad_groups(campaign_id)
   # the configuration file or provide your own logger:
   # adwords.logger = Logger.new('adwords_xml.log')
 
-  ad_group_srv = adwords.service(:AdGroupService, API_VERSION)
+  vtgc_srv =
+      adwords.service(:VideoCampaignCriterionService, API_VERSION)
 
-  # Get all the ad groups for this campaign.
+  # Get all criteria for the campaign.
   selector = {
-    :fields => ['Id', 'Name'],
-    :ordering => [{:field => 'Name', :sort_order => 'ASCENDING'}],
-    :predicates => [
-      {:field => 'CampaignId', :operator => 'IN', :values => [campaign_id]}
-    ],
+    :campaign_ids => [campaign_id],
     :paging => {
       :start_index => 0,
       :number_results => PAGE_SIZE
@@ -53,11 +51,14 @@ def get_ad_groups(campaign_id)
   offset, page = 0, {}
 
   begin
-    page = ad_group_srv.get(selector)
+    page = vtgc_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]]
+      page[:entries].each do |criterion|
+        negative_str =
+            (criterion[:xsi_type] == 'NegativeVideoCampaignCriterion') ?
+            ' negative' : ''
+        puts "Video%s criterion ID %d or type '%s'" % [negative_str,
+            criterion[:criterion][:id], criterion[:criterion][:xsi_type]]
       end
       # Increment values to request the next page.
       offset += PAGE_SIZE
@@ -66,19 +67,19 @@ def get_ad_groups(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]]
+    puts "\tTotal number of criteria found: %d." % [page[:total_num_entries]]
   end
 end
 
 if __FILE__ == $0
-  API_VERSION = :v201206
+  API_VERSION = :v201209
   PAGE_SIZE = 500
 
   begin
-    # Campaign ID to get ad groups for.
+    # Campaign ID to get criteria for.
     campaign_id = 'INSERT_CAMPAIGN_ID_HERE'.to_i
-    get_ad_groups(campaign_id)
+
+    get_video_campaign_criteria(campaign_id)
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e