google-adwords-api 0.4.0 → 0.4.1

data/lib/adwords_api.rb

@@ -20,18 +20,18 @@
 #
 # Contains the main classes for the client library.
 
-gem 'google-ads-common', '~>0.5.0'
-
-require 'savon'
+gem 'google-ads-common', '~>0.5.2'
 
 require 'ads_common/api'
 require 'ads_common/auth/oauth_handler'
+require 'ads_common/savon_service'
 require 'ads_common/savon_headers/oauth_header_handler'
 require 'ads_common/savon_headers/simple_header_handler'
 require 'adwords_api/api_config'
 require 'adwords_api/client_login_header_handler'
 require 'adwords_api/credential_handler'
 require 'adwords_api/errors'
+require 'adwords_api/report_utils'
 require 'adwords_api/v13_login_handler'
 
 # Main namespace for all the client library's modules and classes.
@@ -56,10 +56,7 @@ module AdwordsApi
     # Sets the logger to use.
     def logger=(logger)
       super(logger)
-      Savon.configure do |config|
-        config.log_level = :debug
-        config.logger = logger
-      end
+      AdsCommon::SavonService.logger = logger
     end
 
     # Retrieve single NestedHeaderHandler for v20xx and one SingleHeaderHandler
@@ -76,8 +73,7 @@ module AdwordsApi
     # - a list of SOAP header handlers; one per provided header
     #
     def soap_header_handlers(auth_handler, header_list, version, namespace)
-      auth_method = @config.read('authentication.method',
-          'ClientLogin').to_s.upcase.to_sym
+      auth_method = @config.read('authentication.method', :CLIENTLOGIN)
 
       handlers = []
 
@@ -113,8 +109,7 @@ module AdwordsApi
     # support is available.
     def client_login_handler()
       if @client_login_handler.nil?
-        auth_method_str = @config.read('authentication.method', 'ClientLogin')
-        auth_method = auth_method_str.to_s.upcase.to_sym
+        auth_method = @config.read('authentication.method', :CLIENTLOGIN)
         environment = @config.read('service.environment')
         if auth_method == :CLIENTLOGIN
           # We use client login, so we can reuse general AuthHandler.
@@ -138,20 +133,14 @@ module AdwordsApi
     # - accepts a block, which it will execute as an MCC-level operation
     #
     # Returns:
-    # - Boolean indicating whether MCC-level operations are currently enabled or
-    # disabled
+    # - block execution result, if block given
+    # - boolean indicating whether MCC-level operations are currently
+    #   enabled or disabled, if no block provided
     #
-    def use_mcc
-      if block_given?
-        previous = @credential_handler.use_mcc
-        begin
-          @credential_handler.use_mcc = true
-          yield
-        ensure
-          @credential_handler.use_mcc = previous
-        end
-      end
-      return @credential_handler.use_mcc
+    def use_mcc(&block)
+      return (block_given?) ?
+        run_with_temporary_flag(:@use_mcc, true, block) :
+        @credential_handler.use_mcc
     end
 
     # Helper method to provide a simple way of doing an MCC-level operation
@@ -173,20 +162,14 @@ module AdwordsApi
     # - accepts a block, which it will execute as a validate-only operation
     #
     # Returns:
-    # - Boolean indicating whether validate-only operations are currently
-    #   enabled or disabled
+    # - block execution result, if block given
+    # - boolean indicating whether validate-only operations are currently
+    #   enabled or disabled, if no block provided
     #
-    def validate_only
-      if block_given?
-        previous = @credential_handler.validate_only
-        begin
-          @credential_handler.validate_only = true
-          yield
-        ensure
-          @credential_handler.validate_only = previous
-        end
-      end
-      return @credential_handler.validate_only
+    def validate_only(&block)
+      return (block_given?) ?
+        run_with_temporary_flag(:@validate_only, true, block) :
+        @credential_handler.validate_only
     end
 
     # Helper method to provide a simple way of performing validate-only
@@ -208,20 +191,14 @@ module AdwordsApi
     # - accepts a block, which it will execute as a partial failure operation
     #
     # Returns:
-    # - Boolean indicating whether partial failure operations are currently
-    # enabled or disabled
+    # - block execution result, if block given
+    # - boolean indicating whether partial failure operations are currently
+    # enabled or disabled, if no block provided
     #
-    def partial_failure
-      if block_given?
-        previous = @credential_handler.partial_failure
-        begin
-          @credential_handler.partial_failure = true
-          yield
-        ensure
-          @credential_handler.partial_failure = previous
-        end
-      end
-      return @credential_handler.partial_failure
+    def partial_failure(&block)
+      return (block_given?) ?
+        run_with_temporary_flag(:partial_failure, true, block) :
+        @credential_handler.partial_failure
     end
 
     # Helper method to provide a simple way of performing requests with support
@@ -234,6 +211,21 @@ module AdwordsApi
       @credential_handler.partial_failure = value
     end
 
+    # Returns an instance of ReportUtils object with all utilities relevant to
+    # the reporting.
+    #
+    # Args:
+    # - version: version of the API to use (optional).
+    #
+    def report_utils(version = nil)
+      version = api_config.default_version if version.nil?
+      # Check if version exists.
+      if !api_config.versions.include?(version)
+        raise AdsCommon::Errors::Error, "Unknown version '%s'" % version
+      end
+      return AdwordsApi::ReportUtils.new(self, version)
+    end
+
     private
 
     # Overrides AdsCommon::Api.get_auth_handler to allow version-specific
@@ -259,5 +251,17 @@ module AdwordsApi
       return (version == :v13) ?
           AdwordsApi::V13LoginHandler.new : super(environment)
     end
+
+    # Executes block with a temporary flag set to a given value. Returns block
+    # result.
+    def run_with_temporary_flag(flag_name, flag_value, block)
+      previous = @credential_handler.instance_variable_get(flag_name)
+      @credential_handler.instance_variable_set(flag_name, flag_value)
+      begin
+        return block.call
+      ensure
+        @credential_handler.instance_variable_set(flag_name, previous)
+      end
+    end
   end
 end

data/lib/adwords_api/api_config.rb

@@ -35,19 +35,19 @@ module AdwordsApi
     end
 
     # Set defaults
-    DEFAULT_VERSION = :v201101
+    DEFAULT_VERSION = :v201109
     DEFAULT_ENVIRONMENT = :PRODUCTION
-    LATEST_VERSION = :v201101
+    LATEST_VERSION = :v201109
 
     # Set other constants
     API_NAME = 'AdwordsApi'
     API_PATH = 'adwords_api'
-    CLIENT_LIB_VERSION = '0.4.0'
+    CLIENT_LIB_VERSION = '0.4.1'
     DEFAULT_CONFIG_FILENAME = 'adwords_api.yml'
 
     # Configure the services available to each version
     @@service_config = {
-      :v13 => [:AccountService, :ReportService, :TrafficEstimatorService],
+      :v13 => [:AccountService, :ReportService],
       :v200909 => [:AdExtensionOverrideService, :AdGroupAdService,
                    :AdGroupCriterionService, :AdGroupService, :AdParamService,
                    :BulkMutateJobService, :CampaignAdExtensionService,
@@ -81,7 +81,19 @@ module AdwordsApi
                    :GeoLocationService, :InfoService, :MediaService,
                    :ReportDefinitionService, :ServicedAccountService,
                    :TargetingIdeaService, :TrafficEstimatorService,
-                   :UserListService]
+                   :UserListService],
+      :v201109 => [:AdExtensionOverrideService, :AdGroupAdService,
+                   :AdGroupCriterionService, :AdGroupService, :AdParamService,
+                   :AlertService, :BulkMutateJobService,
+                   :BulkOpportunityService, :CampaignAdExtensionService,
+                   :CampaignCriterionService, :CampaignService,
+                   :CampaignTargetService, :ConversionTrackerService,
+                   :CustomerSyncService, :DataService, :ExperimentService,
+                   :GeoLocationService, :InfoService, :MediaService,
+                   :ReportDefinitionService, :ServicedAccountService,
+                   :TargetingIdeaService, :TrafficEstimatorService,
+                   :UserListService, :ConstantDataService,
+                   :LocationCriterionService, :MutateJobService]
     }
 
     # Configure the different environments, with the base URL for each one
@@ -92,7 +104,8 @@ module AdwordsApi
         :v200909 => 'https://adwords.google.com/api/adwords/',
         :v201003 => 'https://adwords.google.com/api/adwords/',
         :v201008 => 'https://adwords.google.com/api/adwords/',
-        :v201101 => 'https://adwords.google.com/api/adwords/'
+        :v201101 => 'https://adwords.google.com/api/adwords/',
+        :v201109 => 'https://adwords.google.com/api/adwords/'
       },
       :SANDBOX => {
         :oauth_scope => 'https://adwords-sandbox.google.com/api/adwords/',
@@ -100,7 +113,8 @@ module AdwordsApi
         :v200909 => 'https://adwords-sandbox.google.com/api/adwords/',
         :v201003 => 'https://adwords-sandbox.google.com/api/adwords/',
         :v201008 => 'https://adwords-sandbox.google.com/api/adwords/',
-        :v201101 => 'https://adwords-sandbox.google.com/api/adwords/'
+        :v201101 => 'https://adwords-sandbox.google.com/api/adwords/',
+        :v201109 => 'https://adwords-sandbox.google.com/api/adwords/'
       }
     }
 
@@ -110,7 +124,6 @@ module AdwordsApi
       # v13
       [:v13, :AccountService] => '',
       [:v13, :ReportService] => '',
-      [:v13, :TrafficEstimatorService] => '',
       # v200909
       [:v200909, :AdExtensionOverrideService] => 'cm/',
       [:v200909, :AdGroupAdService] => 'cm/',
@@ -189,7 +202,35 @@ module AdwordsApi
       [:v201101, :ServicedAccountService] => 'mcm/',
       [:v201101, :TargetingIdeaService] => 'o/',
       [:v201101, :TrafficEstimatorService] => 'o/',
-      [:v201101, :UserListService] => 'cm/'
+      [:v201101, :UserListService] => 'cm/',
+      # v201109
+      [:v201109, :AdExtensionOverrideService] => 'cm/',
+      [:v201109, :AdGroupAdService] => 'cm/',
+      [:v201109, :AdGroupCriterionService] => 'cm/',
+      [:v201109, :AdGroupService] => 'cm/',
+      [:v201109, :AdParamService] => 'cm/',
+      [:v201109, :AlertService] => 'mcm/',
+      [:v201109, :BulkMutateJobService] => 'job/',
+      [:v201109, :BulkOpportunityService] => 'o/',
+      [:v201109, :CampaignAdExtensionService] => 'cm/',
+      [:v201109, :CampaignCriterionService] => 'cm/',
+      [:v201109, :CampaignService] => 'cm/',
+      [:v201109, :CampaignTargetService] => 'cm/',
+      [:v201109, :ConversionTrackerService] => 'cm/',
+      [:v201109, :CustomerSyncService] => 'ch/',
+      [:v201109, :DataService] => 'cm/',
+      [:v201109, :ExperimentService] => 'cm/',
+      [:v201109, :GeoLocationService] => 'cm/',
+      [:v201109, :InfoService] => 'info/',
+      [:v201109, :MediaService] => 'cm/',
+      [:v201109, :ReportDefinitionService] => 'cm/',
+      [:v201109, :ServicedAccountService] => 'mcm/',
+      [:v201109, :TargetingIdeaService] => 'o/',
+      [:v201109, :TrafficEstimatorService] => 'o/',
+      [:v201109, :UserListService] => 'cm/',
+      [:v201109, :ConstantDataService] => 'cm/',
+      [:v201109, :LocationCriterionService] => 'cm/',
+      [:v201109, :MutateJobService] => 'cm/'
     }
 
     # Configure the auth servers to use for each environment
@@ -278,17 +319,32 @@ module AdwordsApi
     #
     # Args:
     # - environment: the service environment to be used (as a string)
-    # - version: the API version (as an integer)
+    # - version: the API version (as a symbol)
     #
     # Returns:
-    # The endpoint URL (as a string)
+    # - The endpoint URL (as a string)
     #
     def self.report_download_url(environment, version)
+      base = get_wsdl_base(environment, version)
+      if base and service_config[version].include?(:ReportDefinitionService)
+        base += 'reportdownload'
+      end
+      return base
+    end
+
+    # Get the download URL for Ad Hoc reports.
+    #
+    # Args:
+    # - environment: the service environment to be used (as a string)
+    # - version: the API version (as a symbol)
+    #
+    # Returns:
+    # - The endpoint URL (as a string)
+    #
+    def self.adhoc_report_download_url(environment, version)
       base = get_wsdl_base(environment, version)
       if base
-        path = service_config[version].include?(:ReportDefinitionService) ?
-            'reportdownload' : nil
-        base += path.to_s
+        base += 'reportdownload/%s' % version.to_s
       end
       return base
     end

data/lib/adwords_api/credential_handler.rb

@@ -42,9 +42,8 @@ module AdwordsApi
     # Create the list of credentials to be used by the auth handler for header
     # generation.
     def credentials(version = nil)
-      validate_headers_for_server
-      method = @credentials[:method].to_s.upcase.to_sym
-      result = case method
+      validate_headers_for_server(version)
+      result = case @credentials[:method]
         when :CLIENTLOGIN
           {:email => @credentials[:email],
            :password => @credentials[:password]}
@@ -55,19 +54,20 @@ module AdwordsApi
            :oauth_token => @credentials[:oauth_token],
            :oauth_token_secret => @credentials[:oauth_token_secret],
            :oauth_callback => @credentials[:oauth_callback],
-           :oauth_method => @credentials[:oauth_method]}
+           :oauth_method => @credentials[:oauth_method],
+           :oauth_request_token => @credentials[:oauth_request_token]}
       end
-      client_lib = 'Ruby-AwApi-%s|' % AdwordsApi::ApiConfig::CLIENT_LIB_VERSION
+      client_lib = 'AwApi-Ruby-%s|' % AdwordsApi::ApiConfig::CLIENT_LIB_VERSION
       user_agent = @credentials[:user_agent] || $0
       user_agent = client_lib + user_agent
       user_agent_symbol = (version == :v13) ? :useragent : :userAgent
       result[user_agent_symbol] = user_agent
       result[:developerToken] = @credentials[:developer_token]
       unless @use_mcc
-        if @credentials[:client_email]
-          result[:clientEmail] = @credentials[:client_email]
-        elsif @credentials[:client_customer_id]
+        if @credentials[:client_customer_id]
           result[:clientCustomerId] = @credentials[:client_customer_id]
+        elsif @credentials[:client_email] and version != :v201109
+          result[:clientEmail] = @credentials[:client_email]
         end
       end
       if version != :v13
@@ -82,15 +82,33 @@ module AdwordsApi
     # Validates that the right credentials are being used for the chosen
     # environment.
     #
+    # Args:
+    # - version: API version to validate for
+    #
     # Raises:
-    # Adwordsapi::Error::EnvironmentMismatchError if sandbox credentials are
+    # - AdsCommon::Error::EnvironmentMismatchError if sandbox credentials are
     # being used for production or vice-versa.
+    # - AdwordsApi::Errors:BadCredentialsError if supplied credentials are not
+    # valid.
     #
-    def validate_headers_for_server
-      method = @credentials[:method].to_s.upcase.to_sym
+    def validate_headers_for_server(version)
       token = @credentials[:developer_token]
       client_email = @credentials[:client_email]
-      (sandbox_token, sandbox_client) = case method
+
+      if client_email and version == :v201109
+        raise AdwordsApi::Errors::BadCredentialsError, 'Deprecated header ' +
+            'clientEmail is no longer supported, please use clientCustomerId'
+      end
+
+      client_customer_id = @credentials[:client_customer_id]
+      if client_customer_id and
+          !(client_customer_id.is_a?(Integer) or
+            (client_customer_id =~ /\d+-\d+-\d+/))
+        raise AdwordsApi::Errors::BadCredentialsError,
+            'Invalid client customer ID: %s' % client_customer_id.to_s
+      end
+
+      (sandbox_token, sandbox_client) = case @credentials[:method]
         when :CLIENTLOGIN
           email = @credentials[:email]
           [(token =~ /#{Regexp.escape(email)}\+\+[a-zA-Z]{3}/),
@@ -113,7 +131,7 @@ module AdwordsApi
         when :SANDBOX
           # Check if either the token or client email do not follow the
           # correct format. Client email may not exist, though.
-          if (!sandbox_token or (!client_email.empty? and !sandbox_client))
+          if (!sandbox_token or (client_email and !sandbox_client))
             raise AdsCommon::Errors::EnvironmentMismatchError,
                 'Attempting to connect to the sandbox with malformatted ' +
                 'credentials. Please check ' +
@@ -121,6 +139,7 @@ module AdwordsApi
                 'adwords_api_sandbox.html#requestheaders for details.'
           end
       end
+      return nil
     end
   end
 end

data/lib/adwords_api/errors.rb

@@ -55,5 +55,17 @@ module AdwordsApi
         return @array_fields.include?(field.to_s)
       end
     end
+
+    # Error for invalid credentials sush as malformed ID.
+    class BadCredentialsError < AdsCommon::Errors::ApiException
+    end
+
+    # Error for malformed report definition.
+    class InvalidReportDefinitionError < AdsCommon::Errors::ApiException
+    end
+
+    # Error for server-side report error.
+    class ReportError < AdsCommon::Errors::ApiException
+    end
   end
 end

data/lib/adwords_api/extensions.rb

@@ -37,8 +37,9 @@ module AdwordsApi
       [:v201008, :ReportDefinitionService] => [:download_report,
           :download_report_as_file],
       [:v201101, :ReportDefinitionService] => [:download_report,
-          :download_report_as_file, :download_mcc_report,
-          :download_mcc_report_as_file]
+          :download_report_as_file],
+      [:v201109, :ReportDefinitionService] => [:download_report,
+          :download_report_as_file]
     }
 
     # Defines the parameter list for every extension method.
@@ -46,10 +47,7 @@ module AdwordsApi
       :download_xml_report     => [:job_id],
       :download_csv_report     => [:job_id],
       :download_report         => [:report_definition_id],
-      :download_report_as_file => [:report_definition_id, :path],
-      :download_mcc_report     => [:report_definition_id, :query_token],
-      :download_mcc_report_as_file =>
-          [:report_definition_id, :query_token, :path]
+      :download_report_as_file => [:report_definition_id, :path]
     }
 
     # Return list of all extension methods, indexed by version and service.
@@ -209,78 +207,8 @@ module AdwordsApi
       return report_response.body
     end
 
-    # <i>Extension method</i> -- Download and return a MCC report.
-    #
-    # *Warning*: this method is blocking for the calling thread.
-    #
-    # Args:
-    # - wrapper: the service wrapper object for any API methods that need to be
-    #   called
-    # - report_definition_id: the id for the report definition
-    # - query_token: id from previous calls to the method
-    #
-    # Returns:
-    # A hash with HTTP code and report service response
-    #
-    def self.download_mcc_report(wrapper, args)
-      (report_definition_id, query_token) = args
-      do_download_mcc_report(wrapper, report_definition_id, query_token, nil)
-    end
-
-    # <i>Extension method</i> -- Download and save a MCC report to file.
-    #
-    # *Warning*: this method is blocking for the calling thread.
-    #
-    # Args:
-    # - wrapper: the service wrapper object for any API methods that need to be
-    #   called
-    # - report_definition_id: the id for the report definition
-    # - query_token: id from previous calls to the method
-    # - path: filename to save downloaded report to
-    #
-    # Returns:
-    # A hash with HTTP code and report service response
-    #
-    def self.download_mcc_report_as_file(wrapper, args)
-      (report_definition_id, query_token, path) = args
-      do_download_mcc_report(wrapper, report_definition_id, query_token, path)
-    end
-
     private
 
-    # Polls the service once and downloads report into a file or to a hash.
-    def self.do_download_mcc_report(wrapper, report_definition_id, query_token,
-        path = nil)
-      query_token = 'new' if query_token.nil? or query_token.empty?
-      url = get_report_url(wrapper,
-          "?__rd=%s&qt=%s" % [report_definition_id, query_token])
-      report_response = get_report_response(wrapper, url)
-      check_old_error(report_response.body)
-      mcc_response = report_response_to_hash(report_response)
-      result = case report_response.code
-        when 200, 500
-          mcc_response
-        when 301
-          return_or_save_mcc_report_data(wrapper, mcc_response, path)
-        else
-          raise AdwordsApi::Errors::ApiException,
-              "Unknown HTTP error code %d message: %s" %
-              [report_response.code, report_response.body]
-      end
-      return result
-    end
-
-    # Downloads a report body into a hash or a file.
-    def self.return_or_save_mcc_report_data(wrapper, mcc_response, path = nil)
-      report_data = get_report_response(wrapper, mcc_response[:location]).body
-      if path.nil?
-        mcc_response[:report_data] = report_data
-      else
-        save_to_file(report_data, path)
-      end
-      return mcc_response
-    end
-
     # Saves raw data to a file.
     def self.save_to_file(data, path)
       open(path, 'wb') { |file| file.puts(data) } if path
@@ -307,55 +235,17 @@ module AdwordsApi
       auth_handler = wrapper.api.client_login_handler
       headers['Authorization'] = "GoogleLogin auth=%s" %
           auth_handler.headers(credentials)[:authToken]
-      if credentials[:clientEmail]
-        headers['clientEmail'] = credentials[:clientEmail]
-      elsif credentials[:clientCustomerId]
+      if credentials[:clientCustomerId]
         headers['clientCustomerId'] = credentials[:clientCustomerId]
+      elsif credentials[:clientEmail]
+        headers['clientEmail'] = credentials[:clientEmail]
       elsif credentials[:email]
         headers['clientEmail'] = credentials[:email]
       end
       return headers
     end
 
-    # Converts report response data into a convenient hash.
-    def self.report_response_to_hash(response)
-      result = {}
-      result[:code] = response.code
-      xml = REXML::Document.new(response.body)
-      result[:body] = xml_to_hash(xml.root) if xml and xml.root
-      if !response.headers.nil? and !response.headers['Location'].nil?
-        result[:location] = response.headers['Location']
-      end
-      # Special case for accounts list in failures.
-      if result[:body] and result[:body][:failures]
-        result[:body][:failures][:account] =
-            arrayize(result[:body][:failures][:account])
-      end
-      return result
-    end
-
-    # Converts xml into a convenient hash.
-    def self.xml_to_hash(xml)
-      result = {}
-      xml.elements.each do |item|
-        value = (item.has_elements?) ? xml_to_hash(item) : item.get_text()
-        if result[item.name].nil?
-          result[item.name] = value
-        else
-          result[item.name] = arrayize(result[item.name])
-          result[item.name] << value
-        end
-      end
-      return result
-    end
-
-    # Makes sure object is an array.
-    def self.arrayize(object)
-      return [] if object.nil?
-      return object.is_a?(Array) ? object : [object]
-    end
-
-    # Checks for old-style pre-MCC reporting error.
+    # Checks for old-style v13 reporting error.
     def self.check_old_error(response_text)
       error_message_regex = '^!!!(-?\d+)\|\|\|(-?\d+)\|\|\|(.*)\?\?\?'
       matches = response_text.match(error_message_regex)