adwords4r 13.0.1 → 15.0.1

data/examples/multiple_versions.rb

@@ -0,0 +1,167 @@
+#!/usr/bin/ruby
+#
+# Copyright 2009, 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.
+# 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 code sample illustrates how to access services from multiple API versions
+# simultaneously. It gets a list of all campaigns with stats using v2009, and
+# then schedules a campaign performance report for the ones with less than 10
+# impressions, using v13.
+
+require 'rubygems'
+gem 'soap4r', '= 1.5.8'
+require 'adwords4r'
+
+
+def main()
+  begin
+    # AdWords::AdWordsCredentials.new will read a credentials file from
+    # ENV['HOME']/adwords.properties when called without parameters.
+    # The latest versioned release of the API will be assumed.
+    #
+    # Credentials for this example must be for the Sandbox environment.
+    # Sandbox environment credentials overview:
+    # http://www.google.com/apis/adwords/developer/adwords_api_sandbox.html
+    #
+    # Instead of reading them from a file, the credentials can be
+    # specified inline as a hash:
+    #
+    # creds = {
+    #     'developerToken' => 'user@domain.com++USD',
+    #     'useragent' => 'Sample User Agent',
+    #     'password' => 'password',
+    #     'email' => 'user@domain.com',
+    #     'clientEmail' => 'client_1+user@domain.com',
+    #     'applicationToken' => 'IGNORED',
+    #     'alternateUrl' => 'https://sandbox.google.com/api/adwords/v13/'
+    # }
+    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds))
+    adwords = AdWords::API.new
+
+    # Get the v200902 campaign service and the v13 report service
+    campaign_srv = adwords.get_service(200902, 'Campaign')
+    report_srv = adwords.get_service(13, 'Report')
+
+    # Retrieve list of all campaigns with their stats for this year, via v200902
+    selector = AdWords::V200902::CampaignService::CampaignSelector.new
+    stats_selector = {
+      :dateRange => {
+        :min => {
+          :day => 1,
+          :month => 1,
+          :year => Time.new.year
+        },
+        :max => {
+          :day => 31,
+          :month => 12,
+          :year => Time.new.year
+        }
+      }
+    }
+    response = campaign_srv.get(selector)
+    campaigns = response.rval.entries
+    campaigns.each do |campaign|
+      puts 'Campaign id %d was successfully retrieved.' % campaign.id.id
+    end
+
+    # Schedule yearly campaign report for all campaigns with less than 10
+    # impressions, using v13
+    report_name = 'Campaign Report-%s' % DateTime.now.to_s
+    job = AdWords::V13::ReportService::DefinedReportJob.new
+    job.selectedReportType = 'Campaign'
+    job.aggregationTypes = 'Yearly'
+    job.name = report_name
+    job.selectedColumns = %w{Campaign CampaignId Clicks Impressions}
+    job.startDay = Time.new.year.to_s + '-01-01'
+    job.endDay = Time.new.year.to_s + '-01-31'
+    campaign_ids = []
+    campaigns.each do |campaign|
+      campaign_ids << campaign.id.id if campaign.stats.impressions < 10
+    end
+    job.campaigns = campaign_ids
+
+    # Validate the report definition to make sure it is valid.
+    # If it is not, an AdWords::Error::ApiError will be thrown.
+    report_srv.validateReportJob(job)
+
+    # Since validation passed, schedule the report.
+    job_id = report_srv.scheduleReportJob(job).scheduleReportJobReturn
+    sleep_interval = 10
+    puts 'Scheduled report with id %d. Now sleeping %d seconds.' %
+        [job_id, sleep_interval]
+    sleep(sleep_interval)
+
+    puts 'Waiting for report to become available for download...'
+    begin
+      # Invoke client-side method that handles waiting and downloading the
+      # report. This method is blocking for the calling thread.
+      report_data = report_srv.downloadXmlReport(job_id)
+      file_name = '%s.xml' % report_name  # Add path to write report elsewhere.
+      open(file_name, 'w') {|file| file.puts(report_data)}
+      puts 'Report has been written to %s' % file_name
+    rescue AdWords::Error::Error => e
+      puts 'Error downloading report: %s' % e
+    rescue Errno::ENOENT, Errno::EACCES => e
+      puts 'Unable to write file: %s' % e
+    end
+
+  rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => e
+    # This exception indicates a connection-level error.
+    # In general, it is likely to be transitory.
+    puts 'Connection Error: %s' % e
+    puts 'Source: %s' % e.backtrace.first
+
+  rescue AdWords::Error::UnknownAPICall => e
+    # This exception is thrown when an unknown SOAP method is invoked.
+    puts e
+    puts 'Source: %s' % e.backtrace.first
+
+  rescue AdWords::Error::ApiError => e
+    # This exception maps to receiving a SOAP Fault back from the service.
+    # The e.soap_faultstring_ex, e.code_ex, and potentially e.trigger_ex
+    # attributes are the most useful, but other attributes may be populated
+    # as well. To display all attributes, the following can be used:
+    #
+    # e.instance_variables.each do |var|
+    #   value = e.instance_variable_get(var)
+    #   if ! value.nil?
+    #     puts '%s => %s' % [var, value]
+    #   end
+    # end
+    puts 'SOAP Error: %s (code: %d)' % [e.soap_faultstring_ex, e.code_ex]
+    puts 'Trigger: %s' % e.trigger_ex unless e.trigger_ex.nil?
+    puts 'Source: %s' % e.backtrace.first
+
+  ensure
+    # Display API unit usage info. This data is stored as a class variable
+    # in the AdWords::API class and accessed via static methods.
+    # total_units() returns a running total of units used in the scope of the
+    # current program. last_units() returns the number used in the last call.
+    puts
+    puts '%d API units consumed total (%d in last call).' %
+        [adwords.total_units, adwords.last_units]
+  end
+end
+
+
+if __FILE__ == $0
+  # The adwords4r library can log all SOAP requests and responses to files.
+  # This is often useful for debugging purposes.
+  # To enable this, set the ADWORDS4R_DEBUG environement varaible to 'true'.
+  # This can be done either from your operating system environment or via
+  # code, as done below.
+  ENV['ADWORDS4R_DEBUG'] = 'false'
+
+  main()
+end

data/examples/reports.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/ruby
 #
-# Copyright 2008, Google Inc. All Rights Reserved.
+# Copyright 2009, 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.
@@ -18,7 +18,7 @@
 # using the adwords4r client library.
 
 require 'rubygems'
-gem 'soap4r', '>= 1.5.8'
+gem 'soap4r', '= 1.5.8'
 require 'adwords4r'
 
 
@@ -38,96 +38,62 @@ def main()
     # specified inline as a hash:
     #
     # creds = {
-    #   'developerToken' => 'user@domain.com++USD',
-    #   'useragent' => 'Sample User Agent',
-    #   'password' => 'password',
-    #   'email' => 'user@domain.com',
-    #   'clientEmail' => 'client_1+user@domain.com',
-    #   'applicationToken' => 'IGNORED',
-    #   'alternateUrl' => 'https://sandbox.google.com/api/adwords/v13/',
+    #     'developerToken' => 'user@domain.com++USD',
+    #     'useragent' => 'Sample User Agent',
+    #     'password' => 'password',
+    #     'email' => 'user@domain.com',
+    #     'clientEmail' => 'client_1+user@domain.com',
+    #     'applicationToken' => 'IGNORED',
+    #     'alternateUrl' => 'https://sandbox.google.com/api/adwords/v13/',
     # }
-    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds), 13)
-
+    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds))
     adwords = AdWords::API.new
-    
+
     report_name = 'Report-%s' % DateTime.now.to_s
-    
+
     # The following example creates a Structure report with Keyword aggregation.
     # Because it is a Structure report, startDay and endDay values are ignored.
     # See http://www.google.com/apis/adwords/developer/ReportService.html for
     # more information about the different reports you can create.
-
-    job = AdWords::DefinedReportJob.new
+    job = AdWords::V13::ReportService::DefinedReportJob.new
     job.selectedReportType = 'Structure'
     job.aggregationTypes = 'Keyword'
     job.name = report_name
     job.selectedColumns = %w{Campaign AdGroup Keyword KeywordTypeDisplay}
-    job.startDay = '2008-01-01'
-    job.endDay = '2008-01-31'
-    
+    job.startDay = '2009-01-01'
+    job.endDay = '2009-01-31'
+
+    report_srv = adwords.get_service(13, 'Report')
     # Validate the report definition to make sure it is valid.
     # If it is not, an AdWords::Error::ApiError will be thrown.
+    report_srv.validateReportJob(job)
 
-    adwords.validateReportJob(job)
-    
     # Since validation passed, schedule the report.
-
-    job_id = adwords.scheduleReportJob(job).scheduleReportJobReturn
+    job_id = report_srv.scheduleReportJob(job).scheduleReportJobReturn
     sleep_interval = 10
     puts 'Scheduled report with id %d. Now sleeping %d seconds.' %
-      [job_id, sleep_interval]
+        [job_id, sleep_interval]
     sleep(sleep_interval)
-    
-    # Repeatedly check the report status until it is finished.
-    # 'Pending' and 'InProgress' statuses indicate the job is still being run.
-
-    status = adwords.getReportJobStatus(job_id).getReportJobStatusReturn
-    while status != 'Completed' && status != 'Failed'
-      puts 'Report status is %s. Now sleeping another %d seconds.' %
-	[status, sleep_interval]
-      sleep(sleep_interval)
-      status = adwords.getReportJobStatus(job_id).getReportJobStatusReturn
-    end
-    
-    if status == 'Completed'
-      report_url = adwords.getReportDownloadUrl(job_id).
-        getReportDownloadUrlReturn
-      puts 'Report is completed. Downloading report from %s' % report_url
-      
-      # Download the report via the HTTPClient library and write it to disk.
-      # The report is an XML document; the actual element names vary depending
-      # on what type of report run and columns requested.
 
-      client = HTTPClient.new
-      report_data = client.get_content(report_url)
+    puts 'Waiting for report to become available for download...'
+    begin
+      # Invoke client-side method that handles waiting and downloading the
+      # report. This method is blocking for the calling thread.
+      report_data = report_srv.downloadXmlReport(job_id)
       file_name = '%s.xml' % report_name  # Add path to write report elsewhere.
-      begin
-        open(file_name, 'w') {|file| file.puts(report_data)}
-        puts 'Report has been written to %s' % file_name
-
-      rescue Errno::ENOENT, Errno::EACCES => e
-	puts 'Unable to write file: %s' % e
-      end
-    else
-      # Reports that pass validation will normally not fail, but if there is
-      # an error in the report generation service it can sometimes happen.
-
-      puts 'Report generation failed.'
+      open(file_name, 'w') {|file| file.puts(report_data)}
+      puts 'Report has been written to %s' % file_name
+    rescue AdWords::Error::Error => e
+      puts 'Error downloading report: %s' % e
+    rescue Errno::ENOENT, Errno::EACCES => e
+      puts 'Unable to write file: %s' % e
     end
-    
-  rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => e
-    # This exception indicates a connection-level error.
-    # In general, it is likely to be transitory.
 
-    puts 'Connection Error: %s' % e
-    puts 'Source: %s' % e.backtrace.first
-    
   rescue AdWords::Error::UnknownAPICall => e
     # This exception is thrown when an unknown SOAP method is invoked.
-
     puts e
     puts 'Source: %s' % e.backtrace.first
-    
+
   rescue AdWords::Error::ApiError => e
     # This exception maps to receiving a SOAP Fault back from the service.
     # The e.soap_faultstring_ex, e.code_ex, and potentially e.trigger_ex
@@ -140,21 +106,18 @@ def main()
     #     puts '%s => %s' % [var, value]
     #   end
     # end
-
     puts 'SOAP Error: %s (code: %d)' % [e.soap_faultstring_ex, e.code_ex]
     puts 'Trigger: %s' % e.trigger_ex unless e.trigger_ex.nil?
     puts 'Source: %s' % e.backtrace.first
 
   ensure
-    # Display API unit usage information. This data is stored as a class
-    # variable in the AdWords::API class and accessed via static methods.
-    # AdWords::API.get_total_units() returns a running total of units used in
-    # the scope of the current program.
-    # AdWords::API.get_last_units() returns the number used in the last call.
-
+    # Display API unit usage info. This data is stored as a class variable
+    # in the AdWords::API class and accessed via static methods.
+    # total_units() returns a running total of units used in the scope of the
+    # current program. last_units() returns the number used in the last call.
     puts
     puts '%d API units consumed total (%d in last call).' %
-      [AdWords::API.get_total_units(), AdWords::API.get_last_units()]
+        [adwords.total_units, adwords.last_units]
   end
 end
 
@@ -165,7 +128,6 @@ if __FILE__ == $0
   # To enable this, set the ADWORDS4R_DEBUG environement varaible to 'true'.
   # This can be done either from your operating system environment or via
   # code, as done below.
-
   ENV['ADWORDS4R_DEBUG'] = 'false'
 
   main()

data/lib/adwords4r.rb

@@ -1,129 +1,107 @@
+#!/usr/bin/ruby
+#
+# Copyright 2009, 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.
+# 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.
+
+# Contains the main classes for the client library.
+
 require 'rubygems'
 begin
-  gem 'soap4r'
+  gem 'soap4r', '=1.5.8'
 rescue
-  require_gem 'soap4r'
+  require_gem 'soap4r', '=1.5.8'
 end
-require 'soap/soap'
-require 'soap/mapping'
-require 'soap/rpc/driver'
+require 'thread'
+require 'uri'
+require 'adwords4r/soap4rpatches'
 require 'adwords4r/credentials'
 require 'adwords4r/services'
-
-# Fix an issue with SOAPDate. Google complains if the dates have any timezone
-# info in them. There are probably better ways to fix this.
-module SOAP
-  class SOAPDate
-    def of2tz(offset)
-      diffmin = offset * 24 * 60
-      if diffmin.zero?
-        ''
-      else
-        ((diffmin < 0) ? '-' : '+') << format('%02d:%02d',
-          (diffmin.abs / 60.0).to_i, (diffmin.abs % 60.0).to_i)
-      end
-    end
-  end
-end
+require 'adwords4r/adwordslogger'
+require 'adwords4r/apiextensions'
 
 module AdWords
-  
+
+  # Wrapper class that serves as the main point of access for all the API usage
   class API
 
-    @@total_units = 0
-    @@last_units = 0
+    attr_reader :credentials, :drivers, :xml_logger, :unit_logger, :mutex
+    attr_accessor :last_units, :total_units
 
-    def API.add_total_units(increment)
-      @@total_units += increment
-    end
-    
-    def API.get_total_units()
-      return @@total_units
-    end
-    
-    def API.set_last_units(value)
-      @@last_units = value
-    end
-    
-    def API.get_last_units()
-      return @@last_units
-    end
-    
-    attr_reader :credentials, :drivers, :version
-    @methodMap = Hash.new
-    
-    def initialize(credentials = AdWordsCredentials.new,
-		   version = Service.getVersions.sort.last)
-      @credentials, @version = credentials, version
-      @drivers = Hash.new
-      prepareDrivers
-    end
+    public
 
-    def method_missing(m, *args)
-      methodName = m.id2name
-      requestName = AdWords::fix_case_up(m.id2name) # upper first character
-      if valid_call?(methodName)
-        driver = getDriver(methodName)
-        moduleName = driver.class.name.split("::")[0..-2].join("::")
-        constructor = eval("#{moduleName}::#{requestName}.method('new')")
-        req = constructor.call(*args)
-        return driver.send(methodName, req)
-      else
-        raise(Error::UnknownAPICall, "Unknown API Call: #{requestName}", caller)
+    def initialize(credentials = AdWordsCredentials.new)
+      @credentials = credentials
+      @drivers = Hash.new
+      @wrappers = Hash.new
+      @total_units = 0
+      @last_units = 0
+      log_to_console = !ENV['ADWORDS4R_DEBUG'].nil? &&
+          ENV['ADWORDS4R_DEBUG'].upcase == 'TRUE'
+      @xml_logger = AdWordsLogger.new('soap_xml', log_to_console)
+      @unit_logger = AdWordsLogger.new('request_info')
+      @mutex = Mutex.new
+      prepare_drivers
+    end
+
+    # Returns a service, given a version and its name. nil if not found.
+    def get_service(version, name)
+      return @wrappers[[version, name]]
+    end
+
+    private
+
+    # Load all drivers and place them in a Hash, with version and name as key
+    def prepare_drivers()
+      Service.get_versions().each do |v|
+        Service.do_require(v)
+        Service.get_services(v).each do |s|
+          @drivers[[v, s]], @wrappers[[v, s]] = prepare_driver(v, s)
+        end
       end
-    # Handle AdWords Application-level error
-    rescue SOAP::FaultError => fault
-      raise(Error::ApiError.new(fault),
-          "#{methodName} Call Failed: #{fault.faultstring.to_s}", caller)
-    end
-
-    def prepareDrivers()
-      Service.doRequire(@version)
-      Service.getServices(@version).each {|s| @drivers[s] = prepareDriver(s)}
-      @methodMap = Service.getMethodMap(@drivers)
     end
 
-    #pass in call name, get the driver back
-    def getDriver(call)
-      return @methodMap[call]
-    end
-
-    def prepareDriver(s)
-      # Include the module for this service
-      AdWords.class_eval("include #{s}Service")
-
-      #set alternateurl if it has been set in credentials
-      if (@credentials.alternateUrl) then
+    def prepare_driver(v, s)
+      # Set alternateurl if it has been set in credentials
+      if (@credentials.alternateUrl and v <= 13) then
         endpointUrl = @credentials.alternateUrl + s + 'Service'
-        driver = eval("AdWords::#{getServiceName(s)}.new(\"#{endpointUrl}\")")
+        driver =
+            eval("#{Service.get_interface_name(v, s)}.new(\"#{endpointUrl}\")")
       elsif
-        driver = eval("AdWords::#{getServiceName(s)}.new")
+        driver = eval("#{Service.get_interface_name(v, s)}.new")
       end
-      @credentials.handlers.each {|h| driver.headerhandler << h}
-      
-      # Add response filter to this driver for API unit usage processing.
-      driver.filterchain << ResponseFilter.new
-
-      if !ENV['ADWORDS4R_DEBUG'].nil? && ENV['ADWORDS4R_DEBUG'].upcase == 'TRUE'
-        driver.wiredump_file_base = "SOAP_#{$$}"
+      @credentials.get_handlers(v).each do |handler|
+        driver.headerhandler << handler
       end
 
+      # Add response handler to this driver for API unit usage processing.
+      driver.callbackhandler = ResponseHandler.new(self)
+      # Plug the wiredump to our XML logger
+      driver.wiredump_dev = @xml_logger
       driver.options['protocol.http.ssl_config.verify_mode'] = nil
-      #set driver.proxy if you are behing a proxy
-      return driver
-    end
+      # NOTE: Set driver.proxy if you are behing a proxy
 
-    def getServiceName(s)
-      s + "Interface"
+      # Generate wrapper class for this driver
+      Service.generate_wrapper_class(v, s)
+      # and create an instance of it
+      wrapper = eval("#{Service.get_wrapper_name(v, s)}.new(driver)")
+      return driver, wrapper
     end
-
-    def valid_call?(call)
-      return @methodMap.has_key?(call)
-    end
-
   end
 
+  # Error class to wrap several error types in Ruby objects
   class Error
+
     class Error < StandardError; end
 
     # Raised if a call is made to a method that does not exist
@@ -134,9 +112,14 @@ module AdWords
     # in the AdWords SOAP API
     class UnknownType < Error; end
 
+    # Raised if an attempt is made to authenticate in >= v200902 with missing or
+    # wrong information
+    class AuthError < Error; end
+
     # Raised if a call returns with a SOAP error,
     # gives you easy access to adwords error fields
     class ApiError < Error
+
       attr_accessor :soap_faultcode
       attr_accessor :soap_faultstring
       attr_accessor :top_code
@@ -150,7 +133,7 @@ module AdWords
       attr_accessor :textIndex
       attr_accessor :textLength
       attr_accessor :trigger
-      
+
       # These *_ex attributes have been added to correct deficiencies with the
       # initial implementation.
       # They should expose more useful information (i.e. text of errors instead
@@ -189,6 +172,7 @@ module AdWords
       end
 
       private
+
       def protect(&block)
         begin
           block.call
@@ -199,33 +183,49 @@ module AdWords
     end
   end
 
-  # SOAP filter to process response messages for API unit usage information.
-  class ResponseFilter < SOAP::Filter::Handler
-    def on_inbound(xml, opt)
-      # Parse the response XML string for the <operations> header value.
-      if xml =~ %r{<units.+?>(\d+)</units>}
-        units = $1.to_i
-        # Since we don't really have an instance of a useful class here,
-        # we're stuck sticking the value in a class variable for AdWords::API.
-        AdWords::API.set_last_units(units)
-        AdWords::API.add_total_units(units)
-      end
+  # Handler class to process response messages for API unit usage and statistics
+  # information.
+  class ResponseHandler < SOAP::RPC::CallbackHandler
 
-      return xml
+    def initialize(parent)
+      @parent = parent
     end
-  end
 
-  # These class module methods are helper functions
-  class <<self 
+    def on_callback(method_name, endpoint, envelope)
+      units = nil
+      operations = nil
+      response_time = nil
+      request_id = nil
 
-    def fix_case_up(name)
-      name[0] = name[0, 1].upcase # upper first character
-      name
-    end
+      header = envelope.header
 
-    def fix_case_down(name)
-      name[0] = name[0, 1].downcase
-      name
+      @parent.mutex.synchronize do
+        unless header['units'].nil?
+          units = header['units'].element.text.to_i
+          @parent.last_units = units
+          @parent.total_units = @parent.total_units + units
+        end
+
+        unless header['operations'].nil?
+          operations = header['operations'].element.text.to_i
+        end
+
+        unless header['responseTime'].nil?
+          response_time = header['responseTime'].element.text.to_i
+        end
+
+        unless header['requestId'].nil?
+          request_id = header['requestId'].element.text.to_s
+        end
+
+        host = URI.parse(endpoint).host
+
+        data = "host=#{host} method=#{method_name} " +
+               "responseTime=#{response_time} operations=#{operations} " +
+               "units=#{units} requestId=#{request_id}"
+
+        @parent.unit_logger << data
+      end
     end
   end
 end