google-adwords-api 0.9.1 → 0.9.2

data/ChangeLog

@@ -1,3 +1,6 @@
+0.9.2:
+  - AdWords for Video API v201302 support and examples (beta feature).
+
 0.9.1:
   - Support and examples for AdGroupBidModifierService.
 

data/README

@@ -45,19 +45,24 @@ There is an example configuration file shipped with these libraries.
 You can also pass API a manually constructed config hash like:
    adwords = AdwordsApi::Api.new({
      :authentication => {
-         :method => 'ClientLogin',
+         :method => 'OAuth2',
+         :oauth2_client_id: 'INSERT_OAUTH2_CLIENT_ID_HERE'
+         :oauth2_client_secret: 'INSERT_OAUTH2_CLIENT_SECRET_HERE'
          :developer_token => 'DEVELOPER_TOKEN',
-         :user_agent => 'Ruby Sample',
-         :password => 'PASSWORD',
-         :email => 'user@domain.com',
-         :client_customer_id => '012-345-6789'
+         :client_customer_id => '012-345-6789',
+         :user_agent => 'Ruby Sample'
      },
      :service => {
        :environment => 'PRODUCTION'
      }
    })
 
-Then, just specify which service you're looking to use, and which version:
+To obtain OAuth2 client credentials, follow instructions on the wiki:
+
+  http://code.google.com/p/google-api-ads-ruby/wiki/OAuth2
+
+Once the library instance is create, specify which service you're looking to
+use, and which version:
    campaign_srv = adwords.service(:CampaignService, :v201302)
 
 and you should now be able to just use the API methods in the object you were
@@ -91,14 +96,12 @@ In order to make things more Ruby-like for our Ruby developers, we've renamed
 API objects and methods to more closely match Ruby conventions. This means using
 snake_case for methods and parameters, and UpperCamelCase for class names.
 
-For example, the 'getReportFields' method of the ReportDefinitionService is
-named 'get_report_fields' in the client library. You invoke it by doing:
-   response = report_def_srv.get_report_fields(report_type)
+For example, the 'startDate' field of the Campaign object is named 'start_date'
+in the client library. The 'get' method, returns a CampaignPage object which has
+an 'entries' and a 'total_num_entries' field. So, to access the return
+values, you would do this:
 
-The 'get' method, on the other hand, returns a ReportDefinitionPage object which
-has an 'entries' and a 'total_num_entries' field. So, to access the return
-values, you would do:
-   response = report_def_srv.get(selector)
+   response = campaign_srv.get(selector)
    num_entries = response[:total_num_entries]
 
 Essentially, all you have to do is follow Ruby conventions, and the library will
@@ -142,20 +145,23 @@ Request details and units spend are logged at the INFO log level, while raw HTTP
 headers and XML dumps are logged at the DEBUG log level. For more details on
 using Logger refer to the Ruby Logger documentation.
 
-=== 2.4 - Calculating unit spend:
+=== 2.4 - Calculating operations usage
+
+Each AdWords API operation performed consumes a certain number of operations as
+described in the rate sheet:
 
-Each AdWords API operation performed consumes a certain number of API units, as
-specified in the rate sheet:
-  http://code.google.com/apis/adwords/docs/ratesheet.html
+  https://developers.google.com/adwords/api/docs/ratesheet
 
-The amount of units spent is returned in the header part of the SOAP response.
-This information can be obtained by passing a user block during method call:
-  response = report_def_srv.get(selector) do |header|
-    puts "Units spent: %d" % header[:units]
+The amount of operations consumed is returned in the header part of the SOAP
+response. This information can be obtained by passing a user block during the
+method call:
+
+  response = campaign_srv.get(selector) do |header|
+    puts "Operations consumed: %d" % header[:operations]
   end
 
 You can also retrieve the response body as the second block parameter:
-  report_def_srv.get(selector) {|header, body| ... }
+  campaign_srv.get(selector) {|header, body| ... }
 
 === 2.5 - GZip compression
 
@@ -195,6 +201,11 @@ Questions can be asked on forum
 
   http://groups.google.com/group/adwords-api
 
+Make sure to subscribe to our Google Plus page for API change announcements and
+other news:
+
+  https://plus.google.com/+GoogleAdsDevelopers
+
 
 = Copyright/License Info
 

data/adwords_api.yml

@@ -4,14 +4,14 @@
 :authentication:
   # Authentication method, methods currently supported: OAUTH2, OAUTH2_JWT,
   # ClientLogin.
-  :method: ClientLogin
+  :method: OAuth2
 
   # Auth parameters for OAUTH2 method.
   # Set the OAuth2 client id and secret. Register your application here to
   # obtain these values:
   #   https://code.google.com/apis/console#access
-  #:oauth2_client_id: INSERT_OAUTH2_CLIENT_ID_HERE
-  #:oauth2_client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
+  :oauth2_client_id: INSERT_OAUTH2_CLIENT_ID_HERE
+  :oauth2_client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
   # Optional, see: https://developers.google.com/accounts/docs/OAuth2WebServer
   #:oauth2_callback: INSERT_OAUTH2_CALLBACK_URL_HERE
   #:oauth2_state: INSERT_OAUTH2_STATE_HERE
@@ -30,8 +30,8 @@
 
   # Auth parameters for ClientLogin method.
   # NOTE: ClientLogin method is deprecated, use OAuth2.0 instead.
-  :password: INSERT_YOUR_PASSWORD_HERE
-  :email: INSERT_YOUR_LOGIN_EMAIL_HERE
+  #:password: INSERT_YOUR_PASSWORD_HERE
+  #:email: INSERT_YOUR_LOGIN_EMAIL_HERE
   # To manage your auth tokens manually, use the 'auth_token' property.
   #:auth_token: INSERT_AUTH_TOKEN_HERE
 

data/examples/v201302/adwords_for_video/add_video_call_to_action.rb

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+# Encoding: utf-8
+#
+# Author:: api.dklimkin@gmail.com (Danial Klimkin)
+#
+# 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.
+#           You may obtain a copy of the License at
+#
+#           http://www.apache.org/licenses/LICENSE-2.0
+#
+#           Unless required by applicable law or agreed to in writing, software
+#           distributed under the License is distributed on an "AS IS" BASIS,
+#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+#           implied.
+#           See the License for the specific language governing permissions and
+#           limitations under the License.
+#
+# This example illustrates how to create a video call to action overlay.
+#
+# Note: AdWords for Video API is a Beta feature.
+#
+# Tags: VideoService.mutateCallToAction
+
+require 'adwords_api'
+
+def add_video_call_to_action(video_id)
+  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
+  # when called without parameters.
+  adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
+  video_srv = adwords.service(:VideoService, API_VERSION)
+
+  # Create VideoCallToAction locally.
+  video_call_to_action = {
+    :id => video_id,
+    :call_to_action => {
+      :creative => {
+        :headline => 'Mars cruises',
+        :description_line1 => 'Astonishing views',
+        :description_line2 => 'Mild climate',
+        :display_url => 'www.example.com/mars',
+        :destination_url => 'www.example.com/mars'
+      }
+    }
+  }
+
+  # Run a mutate request with ADD operator.
+  response = video_srv.mutate_call_to_action([
+      {:operator => 'SET', :operand => video_call_to_action}
+  ])
+
+  if response and response[:value]
+    response[:value].each do |video_call_to_action|
+      puts "CallToAction overlay was added to video ID '%s', headline '%s'." %
+          [video_call_to_action[:id],
+           video_call_to_action[:call_to_action][:creative][:headline]]
+    end
+  else
+    raise new StandardError, 'No call to action overlays were added.'
+  end
+end
+
+if __FILE__ == $0
+  API_VERSION = :v201302
+
+  begin
+    # Video ID to add call to action to.
+    video_id = 'INSERT_VIDEO_ID_HERE'
+
+    add_video_call_to_action(video_id)
+
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
+
+  # API errors.
+  rescue AdwordsApi::Errors::ApiException => e
+    puts "Message: %s" % e.message
+    puts 'Errors:'
+    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
+end

data/examples/v201302/adwords_for_video/add_video_campaign.rb

@@ -0,0 +1,103 @@
+#!/usr/bin/env ruby
+# Encoding: utf-8
+#
+# Author:: api.dklimkin@gmail.com (Danial Klimkin)
+#
+# 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.
+#           You may obtain a copy of the License at
+#
+#           http://www.apache.org/licenses/LICENSE-2.0
+#
+#           Unless required by applicable law or agreed to in writing, software
+#           distributed under the License is distributed on an "AS IS" BASIS,
+#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+#           implied.
+#           See the License for the specific language governing permissions and
+#           limitations under the License.
+#
+# This example illustrates how to create a video campaign.
+#
+# Note: AdWords for Video API is a Beta feature.
+#
+# Tags: VideoCampaignService.mutate, BudgetService.mutate
+
+require 'adwords_api'
+require 'date'
+
+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
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
+  budget_srv = adwords.service(:BudgetService, API_VERSION)
+  video_campaign_srv = adwords.service(:VideoCampaignService, API_VERSION)
+
+  # 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'
+  }
+  budget_operation = {:operator => 'ADD', :operand => budget}
+
+  # Add budget.
+  return_budget = budget_srv.mutate([budget_operation])
+  budget_id = return_budget[:value].first[:budget_id]
+
+  # 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 adding campaign.
+  operations = campaigns.map do |campaign|
+    {:operator => 'ADD', :operand => campaign}
+  end
+
+  # Add video campaign.
+  response = video_campaign_srv.mutate(operations)
+  if response and response[:value]
+    response[:value].each do |campaign|
+      puts "Campaign with name '%s' and ID %d was added." %
+          [campaign[:name], campaign[:id]]
+    end
+  else
+    raise new StandardError, 'No campaigns were added.'
+  end
+end
+
+if __FILE__ == $0
+  API_VERSION = :v201302
+
+  begin
+    add_video_campaign()
+
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
+
+  # API errors.
+  rescue AdwordsApi::Errors::ApiException => e
+    puts "Message: %s" % e.message
+    puts 'Errors:'
+    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
+end

data/examples/v201302/adwords_for_video/find_videos.rb

@@ -0,0 +1,92 @@
+#!/usr/bin/env ruby
+# Encoding: utf-8
+#
+# Author:: api.dklimkin@gmail.com (Danial Klimkin)
+#
+# 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.
+#           You may obtain a copy of the License at
+#
+#           http://www.apache.org/licenses/LICENSE-2.0
+#
+#           Unless required by applicable law or agreed to in writing, software
+#           distributed under the License is distributed on an "AS IS" BASIS,
+#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+#           implied.
+#           See the License for the specific language governing permissions and
+#           limitations under the License.
+#
+# This example illustrates how to find YouTube videos by a search string. It
+# retrieve details for the first 100 matching videos.
+#
+# Note: AdWords for Video API is a Beta feature.
+#
+# Tags: VideoService.search
+
+require 'adwords_api'
+
+def find_videos()
+  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
+  # when called without parameters.
+  adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
+  video_srv = adwords.service(:VideoService, API_VERSION)
+
+  # Search string to use.
+  query_str = 'AdWords API with Ruby'
+
+  # Create a selector.
+  selector = {
+    :search_type => 'VIDEO',
+    :query => query_str,
+    :paging => {
+      :start_index => 0,
+      :number_results => PAGE_SIZE
+    }
+  }
+
+  # 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 videos matching '%s' were found." % query_str
+  end
+end
+
+if __FILE__ == $0
+  API_VERSION = :v201302
+  PAGE_SIZE = 100
+
+  begin
+    find_videos()
+
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
+
+  # API errors.
+  rescue AdwordsApi::Errors::ApiException => e
+    puts "Message: %s" % e.message
+    puts 'Errors:'
+    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
+end

data/examples/v201302/adwords_for_video/get_keyword_criteria.rb

@@ -0,0 +1,101 @@
+#!/usr/bin/env ruby
+# Encoding: utf-8
+#
+# Author:: api.dklimkin@gmail.com (Danial Klimkin)
+#
+# 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.
+#           You may obtain a copy of the License at
+#
+#           http://www.apache.org/licenses/LICENSE-2.0
+#
+#           Unless required by applicable law or agreed to in writing, software
+#           distributed under the License is distributed on an "AS IS" BASIS,
+#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+#           implied.
+#           See the License for the specific language governing permissions and
+#           limitations under the License.
+#
+# This example show how to retrieve all keywords for a video campaign. To get
+# a list with all campaigns, run get_video_campaigns.rb.
+#
+# Note: AdWords for Video API is a Beta feature.
+#
+# Tags: VideoTargetingGroupCriterionService.get
+
+require 'adwords_api'
+
+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
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
+  vtgc_srv =
+      adwords.service(:VideoTargetingGroupCriterionService, API_VERSION)
+
+  # Get all the keywords for the campaign.
+  selector = {
+    :campaign_ids => [campaign_id],
+    :criterion_types => ['SEARCH_KEYWORD'],
+    :paging => {
+      :start_index => 0,
+      :number_results => PAGE_SIZE
+    }
+  }
+
+  # Set initial values.
+  offset, page = 0, {}
+
+  begin
+    page = vtgc_srv.get(selector)
+    if page[:entries]
+      page[:entries].each do |keyword|
+        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
+      selector[:paging][:start_index] = offset
+    end
+  end while page[:total_num_entries] > offset
+
+  if page.include?(:total_num_entries)
+    puts "\tTotal number of keywords found: %d." % [page[:total_num_entries]]
+  end
+end
+
+if __FILE__ == $0
+  API_VERSION = :v201302
+  PAGE_SIZE = 500
+
+  begin
+    # 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
+    puts "HTTP Error: %s" % e
+
+  # API errors.
+  rescue AdwordsApi::Errors::ApiException => e
+    puts "Message: %s" % e.message
+    puts 'Errors:'
+    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
+end