adwords4r 13.0.1 → 15.0.1

data/lib/adwords4r/adwordslogger.rb

@@ -0,0 +1,56 @@
+#!/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.
+#
+# Wrapper class to handle logging to console and/or files.
+
+require 'logger'
+
+module AdWords
+
+  class AdWordsLogger
+
+    def initialize(filename, log_to_console=false)
+      @filename = filename
+      @loggers = []
+      if log_to_console
+        stderr_logger = Logger.new(STDERR)
+        stderr_logger.level = Logger::INFO
+        @loggers << stderr_logger
+      end
+    end
+
+    # Enables logging to a file (path optional)
+    def log_to_file(path=".#{File::SEPARATOR}")
+      if path[-1, 1] == File::SEPARATOR
+        normalized_path = path
+      else
+        normalized_path = path + File::SEPARATOR
+      end
+      new_logger = Logger.new(normalized_path + @filename)
+      new_logger.level = Logger::INFO
+      @loggers << new_logger
+
+      return nil
+    end
+
+    # Overload << operator to perform logging
+    def << (text)
+      @loggers.each do |logger|
+        logger.info text
+      end
+    end
+  end
+end

data/lib/adwords4r/apiextensions.rb

@@ -0,0 +1,79 @@
+#!/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 extensions to the API, that is, service helper methods provided in
+# client-side by the client library.
+
+module AdWords
+
+  module Extensions
+
+    # Maintains a list of all extensions, indexed by version and service
+    # Using camelCase to match API method names
+    @@extensions = {
+      [13, 'Report'] => ['downloadXmlReport']
+    }
+
+    # Defines the parameter list for every extension method
+    @@methods = {
+      'downloadXmlReport' => ['job_id']
+    }
+
+    def self.extensions
+      return @@extensions
+    end
+
+    def self.methods
+      return @@methods
+    end
+
+    # Download and return report data in XML format.
+    # Warning: this method is blocking for the calling thread.
+    def self.downloadXmlReport(wrapper, job_id)
+      sleep_interval = 30
+
+      # Repeatedly check the report status until it is finished.
+      # 'Pending' and 'InProgress' statuses indicate the job is still being run.
+      status = wrapper.getReportJobStatus(job_id).getReportJobStatusReturn
+      while status != 'Completed' && status != 'Failed'
+        sleep(sleep_interval)
+        status = wrapper.getReportJobStatus(job_id).getReportJobStatusReturn
+      end
+
+      if status == 'Completed'
+        report_url =
+            wrapper.getReportDownloadUrl(job_id).getReportDownloadUrlReturn
+
+        # Download the report via the HTTPClient library and return its
+        # contents. The report is an XML document; the actual element names vary
+        # depending on the type of report run and columns requested.
+        begin
+          client = HTTPClient.new
+          return client.get_content(report_url)
+        rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => e
+          # This exception indicates a connection-level error.
+          # In general, it is likely to be transitory.
+          raise AdWords::Error::Error, "Connection Error: %s\nSource: %s" %
+              [e, e.backtrace.first]
+        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.
+        raise AdWords::Error::Error, 'Report generation failed.'
+      end
+    end
+  end
+end

data/lib/adwords4r/authtoken.rb

@@ -0,0 +1,56 @@
+#!/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 library connects to Google's ClientLogin service and generates an
+# AuthToken that can be used to login to the AdWords API.
+
+require 'cgi'
+require 'net/http'
+require 'net/https'
+
+module AdWords
+
+  class AuthToken
+
+    ACCOUNT_TYPE = 'GOOGLE'
+    AUTH_HOSTNAME = 'www.google.com'
+    AUTH_PATH = '/accounts/ClientLogin'
+    AUTH_PORT = 443
+    SERVICE = 'adwords'
+
+    def self.get_token(email, password)
+      email = CGI.escape(email)
+      password = CGI.escape(password)
+
+      http_client = Net::HTTP.new(AUTH_HOSTNAME, AUTH_PORT)
+      http_client.use_ssl = true
+
+      data = "accountType=#{ACCOUNT_TYPE}&Email=#{email}&Passwd=#{password}" +
+        "&service=#{SERVICE}"
+      headers = {'Content-Type' => 'application/x-www-form-urlencoded'}
+
+      response = http_client.post(AUTH_PATH, data, headers)
+
+      if response.code == '200'
+        return response.body[/Auth=(.*)/, 1]
+      else
+        raise AdWords::Error::AuthError,
+            "Login failed for email %s: %s (code %d)" %
+                [CGI.unescape(email), response.message, response.code]
+      end
+    end
+  end
+end

data/lib/adwords4r/credentials.rb

@@ -1,56 +1,152 @@
+#!/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.
+#
+# Handles credentials for the SOAP requests, for both <= v13 and >= v200902.
+
 require 'soap/header/simplehandler'
+require 'adwords4r/authtoken'
 
 module AdWords
 
-  class HeaderHandler < SOAP::Header::SimpleHandler
+  # Handles the headers used in the v200902 sandbox requests
+  class Sandbox200902HeaderHandler < SOAP::Header::SimpleHandler
+
+    # Receives an AdWordsCredentials object as parent
+    def initialize(parent)
+      namespace = 'https://adwords.google.com/api/adwords/cm/v200902'
+      super(XSD::QName.new(namespace, 'RequestHeader'))
+      @parent = parent
+    end
+
+    def on_simple_outbound
+      return { :authToken => @parent.auth_token,
+               :clientEmail => @parent.credentials['clientEmail'] }
+    end
+  end
+
+  # Handles the headers used in <= v13 (both sandbox and production)
+  class Pre200902HeaderHandler < SOAP::Header::SimpleHandler
+
     attr_reader :tag
     attr_writer :value
 
+    # Receives a tag name (email, password, etc.) and a value to be sent in that
+    # tag for outgoing requests
     def initialize(tag, value)
       super(XSD::QName.new(nil, tag))
       @tag = tag
       @value = value
     end
 
-    #the initial handler from the sample was wrong, it generated 2 level of tags
     def on_simple_outbound
       @value
     end
   end
 
+  # Generic credentials class, used for any API version
   class AdWordsCredentials
-    attr_reader :handlers, :alternateUrl
 
-    def getDefaults()
-      cred = Hash.new
-      IO.foreach("#{ENV['HOME']}/adwords.properties") {|line|
-        addCredential(cred, line.split('=')) if !(line =~ /^#/)}
-      return cred
-    end
+    attr_reader :credentials, :alternateUrl
 
-    def addCredential(cred, arr)
-      cred[arr[0]] = arr[1].strip
-    end
+    public
 
     def initialize(*parm)
-      @handlers = []
+      @credentials = {}
       @alternateUrl = nil
-      if parm[0] 
+      @auth_token = nil
+      @handlers = []
+      if parm[0]
         credentials = parm[0]
       else
-        credentials = getDefaults()
+        credentials = get_defaults()
+      end
+      credentials.each do |key, value|
+        @credentials[key] = value if !(key =~ /^alternateUrl/)
       end
-      credentials.each {|key, value|
-        @handlers << HeaderHandler.new(key, value) if !(key =~ /^alternateUrl/)}
       @alternateUrl = credentials['alternateUrl']
+      @credentials.each do |key, value|
+        @handlers << Pre200902HeaderHandler.new(key, value)
+      end
+    end
+
+    # Return a list of handlers to be inserted into the driver's handler list
+    def get_handlers(version)
+      if (version <= 13)
+        return @handlers
+      else
+        return [Sandbox200902HeaderHandler.new(self)]
+      end
     end
 
-    def setHeader(header, value)
-      handlers.each do |handler|
+    # Returns the authentication token used with >= v200902 requests
+    def auth_token
+      generate_auth_token if @auth_token.nil?
+      return @auth_token
+    end
+
+    # Generates a new authentication token used with >= v200902 requests
+    # (should only be necessary for user code to invoke this if the first token
+    # expires)
+    def generate_auth_token
+      email = @credentials['email']
+      password = @credentials['password']
+
+      if email.nil?
+        raise AdWords::Error::AuthError,
+            'Email address not included in credentials.'
+      end
+
+      if password.nil?
+        raise AdWords::Error::AuthError, 'Password not included in credentials.'
+      end
+
+      @auth_token = AdWords::AuthToken::get_token(email, password)
+      return @auth_token
+    end
+
+    # Changes one of the headers
+    def set_header(header, value)
+      # Invalidate previous auth token if necessary
+      @auth_token = nil if header == 'email' or header == 'password'
+
+      @credentials.each_key do |key|
+        if key == header then
+          @credentials[key] = value
+        end
+      end
+
+      @handlers.each do |handler|
         if handler.tag == header then
           handler.value = value
         end
       end
     end
+
+    private
+
+    def get_defaults
+      cred = Hash.new
+      IO.foreach("#{ENV['HOME']}/adwords.properties") do |line|
+        add_credential(cred, line.split('=')) if !(line =~ /^#/)
+      end
+      return cred
+    end
+
+    def add_credential(cred, arr)
+      cred[arr[0]] = arr[1].strip
+    end
   end
 end

data/lib/adwords4r/services.rb

@@ -1,31 +1,156 @@
+#!/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.
+#
+# Helper methods for loading and managing the available services
+
 module AdWords
+
   class Service
 
-    @services = {
-      12 => ["Account", "AdGroup", "Ad", "Campaign", "Criterion", "Info",
-        "KeywordTool", "Report", "SiteSuggestion", "TrafficEstimator"],
+    @@services = {
       13 => ["Account", "AdGroup", "Ad", "Campaign", "Criterion", "Info",
-        "KeywordTool", "Report", "SiteSuggestion", "TrafficEstimator"]
+             "KeywordTool", "Report", "SiteSuggestion", "TrafficEstimator"],
+      200902 => ["AdGroupAd", "AdGroupCriterion", "AdGroup",
+                 "CampaignCriterion", "Campaign", "CampaignTarget"]
     }
 
-    def self.getVersions
-      @services.keys
+    public
+
+    # Get the available API versions
+    def self.get_versions
+      @@services.keys
     end
 
-    def self.getServices(version)
-      @services[version]
+    # Get the list of service names for a given version
+    def self.get_services(version)
+      @@services[version]
     end
 
-    def self.doRequire(version)
-      getServices(version).each do |s|
+    # Perform the loading of the necessary source files for a version
+    def self.do_require(version)
+      get_services(version).each do |s|
         eval("require 'adwords4r/v#{version}/#{s}ServiceDriver'")
       end
     end
 
-    def self.getMethodMap(drivers)
-      methodMap = Hash.new
-      drivers.each_value {|d| d.class::Methods.each {|m| methodMap[m[1]] = d}}
-      return methodMap
+    # Generate the wrapper class for a given service.
+    # These classes make it easier to invoke the API methods, by removing the
+    # need to instance a <MethodName> object, instead allowing passing of the
+    # call parameters directly.
+    # Here is an example of a generated wrapper, with one API method and one
+    # extension:
+    # class SampleServiceWrapper
+    #
+    #   def initialize(driver)
+    #     @driver = driver
+    #   end
+    #
+    #   def getSomething(*arg)
+    #     begin
+    #       obj = AdWords::V13::GetSomething.new(*arg)
+    #       return @driver.getSomething(obj)
+    #     rescue SOAP::FaultError => fault
+    #       raise (Error::ApiError.new(fault),
+    #           "getSomething Call Failed: " + fault.faultstring.to_s, caller)
+    #     end
+    #   end
+    #
+    #   def doSomethingElseExtension(par1, par2)
+    #     return AdWords::Extensions.doSomethingElseExtension(self, par1, par2)
+    #   end
+    # end
+    def self.generate_wrapper_class(version, service)
+      wrapper = service + "ServiceWrapper"
+
+      mod = eval(get_module_name(version, service))
+
+      unless mod.const_defined? wrapper  # Avoid double initialization
+        driver = eval(get_interface_name(version, service))
+        class_def = <<-EOS
+          class #{wrapper}
+            def initialize(driver)
+              @driver = driver
+            end
+        EOS
+
+        # Add service methods
+        methods = driver::Methods
+        module_name = get_module_name(version, service)
+        methods.each do |method|
+          name = method[1]
+          method_def = <<-EOS
+            def #{name}(*arg)
+              begin
+                obj = #{module_name}::#{fix_case_up(name)}.new(*arg)
+                return @driver.#{name}(obj)
+              rescue SOAP::FaultError => fault
+                raise(Error::ApiError.new(fault),
+                    "#{name} Call Failed: " + fault.faultstring.to_s, caller)
+              end
+            end
+          EOS
+          class_def += method_def
+        end
+
+        # Add extension methods, if any
+        extensions = AdWords::Extensions::extensions[[version, service]]
+        unless extensions.nil?
+          extensions.each do |ext|
+            params = AdWords::Extensions::methods[ext].join(', ')
+            arglist = 'self'
+            arglist += ", #{params}" if params != ''
+            method_def = <<-EOS
+              def #{ext}(#{params})
+                return AdWords::Extensions.#{ext}(#{arglist})
+              end
+            EOS
+            class_def += method_def
+          end
+        end
+
+        class_def += "end"
+        mod.class_eval(class_def)
+      end
+      return nil
+    end
+
+    # Returns the full module name for a given service
+    def self.get_module_name(version, service)
+      return "AdWords::V#{version.to_s}::#{service}Service"
+    end
+
+    # Returns the full interface class name for a given service
+    def self.get_interface_name(version, service)
+      if (version <= 13)
+        return get_module_name(version, service) + "::#{service}Interface"
+      else
+        return get_module_name(version, service) +
+            "::#{service}ServiceInterface"
+      end
+    end
+
+    # Returns the full wrapper class name for a given service
+    def self.get_wrapper_name(version, service)
+      return get_module_name(version, service) + "::#{service}ServiceWrapper"
+    end
+
+    private
+
+    def self.fix_case_up(name)
+      return name[0, 1].upcase + name[1..-1]
     end
   end
 end