adwords4r 15.0.1 → 15.1.0

data/lib/adwords4r/adwordslogger.rb

@@ -20,8 +20,16 @@ require 'logger'
 
 module AdWords
 
+  # Wrapper class to handle logging to console and/or files.
   class AdWordsLogger
 
+    # Constructor for AdWordsLogger.
+    #
+    # Args:
+    # - filename: the filename for the log file to be written (if log_to_file is
+    #   called)
+    # - log_to_console: boolean, indicates whether or not to log to the console
+    #
     def initialize(filename, log_to_console=false)
       @filename = filename
       @loggers = []
@@ -32,24 +40,25 @@ module AdWords
       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)
+    # Enables logging to a file.
+    # May be called several times to log to multiple files.
+    #
+    # Args:
+    # - path: where to write the file (defaults to current dir). Path only, do
+    #   not provide filename.
+    #
+    def log_to_file(path='.')
+      new_logger = Logger.new(File.join(path, @filename))
       new_logger.level = Logger::INFO
       @loggers << new_logger
 
       return nil
     end
 
-    # Overload << operator to perform logging
+    # Overload << operator to perform logging.
     def << (text)
       @loggers.each do |logger|
-        logger.info text
+        logger.info text.to_s
       end
     end
   end

data/lib/adwords4r/apiextensions.rb

@@ -17,31 +17,57 @@
 # Contains extensions to the API, that is, service helper methods provided in
 # client-side by the client library.
 
+require 'rexml/document'
+require 'csv'
+
 module AdWords
 
   module Extensions
 
-    # Maintains a list of all extensions, indexed by version and service
-    # Using camelCase to match API method names
+    # Maintains a list of all extension methods, indexed by version and service.
+    # Using camelCase to match API method names.
     @@extensions = {
-      [13, 'Report'] => ['downloadXmlReport']
+      [13, 'Report'] => ['downloadXmlReport', 'downloadCsvReport'],
+      [13, 'Info']   => ['getMethodUsage', 'getClientUnitsUsage']
     }
 
     # Defines the parameter list for every extension method
     @@methods = {
-      'downloadXmlReport' => ['job_id']
+      'downloadXmlReport'   => ['job_id'],
+      'downloadCsvReport'   => ['job_id'],
+      'getMethodUsage'      => ['start_date', 'end_date'],
+      'getClientUnitsUsage' => ['start_date', 'end_date']
     }
 
+    # Return list of all extension methods, indexed by version and service.
     def self.extensions
       return @@extensions
     end
 
+    # Return the parameter list for every extension method.
     def self.methods
       return @@methods
     end
 
-    # Download and return report data in XML format.
-    # Warning: this method is blocking for the calling thread.
+    #########################################################################
+    # NOTE: The following extension methods shouldn't be used directly; they
+    # should instead be used from the services wrappers they get mapped to.
+    # For example, you should use ReportServiceWrapper::downloadXmlReport
+    # instead of Extensions::downloadXmlReport.
+    #########################################################################
+
+    # <i>Extension method</i> -- Download and return report data in XML format.
+    #
+    # *Warning*: this method is blocking for the calling thread.
+    #
+    # Args:
+    # - wrapper: the service wrapper object for any API methods that need to be
+    #   called
+    # - job_id: the job id for the report to be downloaded
+    #
+    # Returns:
+    # The xml for the report (as a string)
+    #
     def self.downloadXmlReport(wrapper, job_id)
       sleep_interval = 30
 
@@ -75,5 +101,198 @@ module AdWords
         raise AdWords::Error::Error, 'Report generation failed.'
       end
     end
+
+    # <i>Extension method</i> -- Download and return report data in CSV format.
+    #
+    # *Warning*: this method is blocking for the calling thread.
+    #
+    # Args:
+    # - wrapper: the service wrapper object for any API methods that need to be
+    #   called
+    # - job_id: the job id for the report to be downloaded
+    # - xml: optional parameter used for testing and debugging
+    #
+    # Returns:
+    # The CSV data for the report (as a string)
+    #
+    def self.downloadCsvReport(wrapper, job_id, report_xml=nil)
+      # Get XML report data.
+      report_xml = downloadXmlReport(wrapper, job_id) if report_xml.nil?
+
+      begin
+        # Construct DOM object.
+        doc = REXML::Document.new(report_xml)
+
+        # Get data columns.
+        columns = []
+        doc.elements.each('report/table/columns/column') do |column_elem|
+          name = column_elem.attributes['name']
+          columns << name unless name.nil?
+        end
+
+        # Get data rows.
+        rows = []
+        doc.elements.each('report/table/rows/row') do |row_elem|
+          rows << row_elem.attributes unless row_elem.attributes.nil?
+        end
+
+        # Build CSV
+        csv = ''
+        CSV::Writer.generate(csv) do |writer|
+          writer << columns
+          rows.each do |row|
+            row_values = []
+            columns.each { |column| row_values << row[column] }
+            writer << row_values
+          end
+        end
+
+        return csv
+      rescue REXML::ParseException => e
+        # Error parsing XML
+        raise AdWords::Error::Error,
+            "Error parsing report XML: %s\nSource: %s" % [e, e.backtrace.first]
+      end
+    end
+
+    # <i>Extension method</i> -- Get a mapping between API methods and the
+    # number of units used through them for a given amount of time.
+    #
+    # Running this helper method will consume 71 units.
+    #
+    # *Note*: unit data is not available in real time.
+    #
+    # Args:
+    # - wrapper: the service wrapper object for any API methods that need to be
+    #   called
+    # - start_date: starting date for unit spend count (as a Date)
+    # - end_date: starting date for unit spend count (as a Date)
+    #
+    # Returns:
+    # Hash of <i>service</i>.<i>method</i> to the number of units used, e.g.,
+    #  { 'AccountService.getAccountInfo' => 10,
+    #    'AccountService.getClientAccountInfos' => 0, ...}
+    #
+    def self.getMethodUsage(wrapper, start_date, end_date)
+      op_rates = AdWords::Utils.get_operation_rates
+      usage = {}
+
+      op_rates.each do |op|
+        service, method = op
+        usage[service + '.' + method] = wrapper.getUnitCountForMethod(service,
+            method, start_date, end_date).getUnitCountForMethodReturn
+      end
+
+      return usage
+    end
+
+    # <i>Extension method</i> -- Gets the quota usage per child of the entire
+    # account tree below the root user. That is, for each child that is a client
+    # manager, all units below that client manager are summed upwards. The
+    # result is very useful for invoicing sub-MCCs that may have many clients
+    # that units may be spent on.
+    #
+    # *Note*: unit data is not available in real time.
+    #
+    # Args:
+    # - wrapper: the service wrapper object for any API methods that need to be
+    #   called
+    # - start_date: starting date for unit spend count (as a Date)
+    # - end_date: starting date for unit spend count (as a Date)
+    #
+    # Returns:
+    # - Hash of account to unit usage,
+    #  { 'account1@domain.tld' => 10,
+    #    'account2@domain.tld' => 0, ...}
+    # - List of double counted children (account emails)
+    #
+    def self.getClientUnitsUsage(wrapper, start_date, end_date)
+      # Create a new AdWords::API object to ensure thread-safety (we'll need to
+      # change the clientEmail)
+      adwords = AdWords::API.new(wrapper.api.credentials.dup)
+      adwords.credentials.set_header('clientEmail', '')
+      # Call unit_adder on the main user
+      unit_map = client_unit_adder(adwords, start_date, end_date)
+      # Pass back the spent unit information to the main AdWords::API object
+      wrapper.api.mutex.synchronize do
+        wrapper.api.last_units = adwords.total_units
+        wrapper.api.total_units += adwords.total_units
+      end
+      return unit_map
+    end
+
+    private
+
+    # Auxiliary recursive method to get the sum of units for an account and all
+    # those under it, if any.
+    #
+    # Args:
+    # - adwords: the AdWords::API object to be used for retrieving the client
+    #   data
+    # - start_date: starting date for unit spend count (as a Date)
+    # - end_date: starting date for unit spend count (as a Date)
+    #
+    # Returns:
+    # - Hash of account to unit usage,
+    #  { 'account1@domain.tld' => 10,
+    #    'account2@domain.tld' => 0, ...}
+    # - List of double counted children (account emails)
+    #
+    def self.client_unit_adder(adwords, start_date, end_date)
+      account_srv = adwords.get_service(13, 'Account')
+      if adwords.credentials.credentials['clientEmail'] == ''
+        account_email = adwords.credentials.credentials['email']
+      else
+        account_email = adwords.credentials.credentials['clientEmail']
+      end
+      # Get list of accounts under the current one
+      accounts = account_srv.getClientAccountInfos
+      unit_map = {}
+      doubles = []
+      clients = accounts.select { |account| !account.isCustomerManager }
+      managers = accounts.select { |account| account.isCustomerManager }
+      client_emails = clients.map { |account| account.emailAddress }
+      info_srv = adwords.get_service(13, 'Info')
+
+      # Get usage for clients
+      client_usage =
+          info_srv.getUnitCountForClients(client_emails, start_date, end_date)
+
+      client_usage.each do |record|
+        unit_map[record.clientEmail] = record.quotaUnits
+      end
+
+      managers.each do |account|
+        # Create a new AdWords::API object to ensure thread-safety (we'll need
+        # to change the clientEmail)
+        sub_mcc = AdWords::API.new(adwords.credentials.dup)
+        sub_mcc.credentials.set_header('clientEmail', account.emailAddress)
+        # Recurse for sub-MCCs
+        sub_unit_map, sub_doubles =
+            client_unit_adder(sub_mcc, start_date, end_date)
+        sub_unit_map.each_key do |entry|
+          # Add any accounts already accounted for to the doubles list
+          unless unit_map[entry].nil?
+            doubles << entry unless doubles.include?(entry)
+          end
+        end
+        # Merge unit maps, doubles and unit spend from the sub with the main
+        unit_map.merge! sub_unit_map
+        sub_doubles.each do |entry|
+          doubles << entry unless doubles.include?(entry)
+        end
+        doubles += sub_doubles
+        adwords.mutex.synchronize do
+          adwords.total_units += sub_mcc.total_units
+        end
+      end
+
+      # Calculate the sum for this account and add it to the hash as well
+      sum = accounts.inject(0) do |result, account|
+        result + unit_map[account.emailAddress]
+      end
+      unit_map[account_email] = sum
+      return unit_map, doubles
+    end
   end
 end

data/lib/adwords4r/authtoken.rb

@@ -23,7 +23,9 @@ require 'net/https'
 
 module AdWords
 
-  class AuthToken
+  # Module providing the mechanism to obtain auth tokens for logging in to the
+  # AdWords API (>= v200902).
+  module AuthToken
 
     ACCOUNT_TYPE = 'GOOGLE'
     AUTH_HOSTNAME = 'www.google.com'
@@ -31,12 +33,26 @@ module AdWords
     AUTH_PORT = 443
     SERVICE = 'adwords'
 
+    # Retrieve authentication token for logging in to the AdWords API.
+    #
+    # Args:
+    # - email: the email address for the account being accessed
+    # - password: the password for the account being accessed
+    #
+    # Returns:
+    # The auth token for the account (as a string).
+    #
+    # Raises:
+    # AdWords::Error::AuthError if authentication fails.
+    #
     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
+      # Avoid annoying warning
+      http_client.verify_mode = OpenSSL::SSL::VERIFY_NONE
 
       data = "accountType=#{ACCOUNT_TYPE}&Email=#{email}&Passwd=#{password}" +
         "&service=#{SERVICE}"

data/lib/adwords4r/credentials.rb

@@ -24,13 +24,18 @@ module AdWords
   # Handles the headers used in the v200902 sandbox requests
   class Sandbox200902HeaderHandler < SOAP::Header::SimpleHandler
 
-    # Receives an AdWordsCredentials object as parent
+    # Constructor for Sandbox200902HeaderHandler.
+    #
+    # Args:
+    # - parent: AdWordsCredentials object containing the login credentials.
+    #
     def initialize(parent)
       namespace = 'https://adwords.google.com/api/adwords/cm/v200902'
       super(XSD::QName.new(namespace, 'RequestHeader'))
       @parent = parent
     end
 
+    # Handles callback.
     def on_simple_outbound
       return { :authToken => @parent.auth_token,
                :clientEmail => @parent.credentials['clientEmail'] }
@@ -43,46 +48,77 @@ module AdWords
     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
+    # Constructor for Pre200902HeaderHandler.
+    #
+    # Args:
+    # - tag: XML tag name to be handled (email, password, etc.)
+    # - value: value to be sent inside tag on outgoing requests
+    #
     def initialize(tag, value)
       super(XSD::QName.new(nil, tag))
       @tag = tag
       @value = value
     end
 
+    # Handles callback.
     def on_simple_outbound
       @value
     end
   end
 
-  # Generic credentials class, used for any API version
+  # Generic credentials class, used for any API version.
   class AdWordsCredentials
 
-    attr_reader :credentials, :alternateUrl
+    # Hash of credentials (credential key to value)
+    attr_reader :credentials
+    # The alternate URL being used to connect to the service (if any).
+    # <= v13 only.
+    attr_reader :alternateUrl
 
     public
 
-    def initialize(*parm)
+    # Constructor for AdWordsCredentials.
+    #
+    # Args:
+    # - credentials: Hash of credentials (credential key to value). E.g.:
+    #    {
+    #     '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/'
+    #    }
+    #
+    def initialize(credentials=nil)
       @credentials = {}
       @alternateUrl = nil
       @auth_token = nil
       @handlers = []
-      if parm[0]
-        credentials = parm[0]
-      else
-        credentials = get_defaults()
-      end
+      credentials = get_defaults() if credentials.nil?
       credentials.each do |key, value|
         @credentials[key] = value if !(key =~ /^alternateUrl/)
       end
       @alternateUrl = credentials['alternateUrl']
+
+      # Fix potential problems with changing clientEmail, by forcing it to be
+      # created
+      @credentials['clientEmail'] = '' if @credentials['clientEmail'].nil?
+
       @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
+    # Return a list of handlers to be inserted into the driver's handler list.
+    #
+    # Args:
+    # - version: API version being used. Must be an integer.
+    #
+    # Returns:
+    # The list of handlers (subclasses of SOAP::Header::SimpleHandler)
+    #
     def get_handlers(version)
       if (version <= 13)
         return @handlers
@@ -91,15 +127,25 @@ module AdWords
       end
     end
 
-    # Returns the authentication token used with >= v200902 requests
+    # Returns the authentication token used with >= v200902 requests.
+    # Generates it if there's no valid token already generated.
+    #
+    # Returns:
+    # The auth token (as a string).
+    #
     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)
+    # Generates a new authentication token used with >= v200902 requests.
+    # The generated token is stored and can later be accessed with auth_token.
+    # It should only be necessary for user code to invoke this if the first
+    # token expires.
+    #
+    # Returns:
+    # The auth token (as a string).
+    #
     def generate_auth_token
       email = @credentials['email']
       password = @credentials['password']
@@ -117,7 +163,12 @@ module AdWords
       return @auth_token
     end
 
-    # Changes one of the headers
+    # Change one of the authentication headers.
+    #
+    # Args:
+    # - header: the name for the header being changed.
+    # - value: the new value for the header.
+    #
     def set_header(header, value)
       # Invalidate previous auth token if necessary
       @auth_token = nil if header == 'email' or header == 'password'
@@ -135,18 +186,36 @@ module AdWords
       end
     end
 
+    # Overloads the 'dup' method for AdWordsCredentials to correctly duplicate
+    # objects of this class.
+    #
+    # Returns:
+    # Duplicated AdWordsCredentials object
+    #
+    def dup
+      creds = @credentials.dup
+      creds['alternateUrl'] = @alternateUrl unless @alternateUrl.nil?
+      return AdWordsCredentials.new(creds)
+    end
+
     private
 
+    # Get the default credentials.
+    # Loads them from the adwords.properties file in the directory specified by
+    # the HOME environment variable.
+    #
+    # Returns:
+    # Hash with the credentials (credential key to value).
+    #
     def get_defaults
       cred = Hash.new
-      IO.foreach("#{ENV['HOME']}/adwords.properties") do |line|
-        add_credential(cred, line.split('=')) if !(line =~ /^#/)
+      IO.foreach(File.join(ENV['HOME'], 'adwords.properties')) do |line|
+        unless line =~ /^#/
+          split_line = line.split('=')
+          cred[split_line[0].strip] = split_line[1].strip
+        end
       end
       return cred
     end
-
-    def add_credential(cred, arr)
-      cred[arr[0]] = arr[1].strip
-    end
   end
 end