google-adwords-api 0.1.1 → 0.1.2

data/examples/v201101/download_mcc_report.rb

@@ -17,12 +17,19 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example gets and downloads a report from a report definition. To get a
-# report definition, run add_keywords_performance_report_definition.rb.
+# This example gets and downloads a report from a report definition using MCC
+# (cross-client) feature. To create a report definition, run
+# add_mcc_report_definition.rb.
+#
+# Please note: This feature is still under development and may change before it
+# is released.
+#
+# Tags: ReportDefinitionService
 
 require 'rubygems'
 gem 'google-adwords-api'
 require 'adwords_api'
+require 'pp'
 
 API_VERSION = :v201101
 MAX_RETRIES = 10
@@ -36,31 +43,48 @@ def download_mcc_report()
 
   report_definition_id = 'INSERT_REPORT_ID_HERE'.to_i
 
-  # Initially run with qt = 'new'
-  qt = 'new'
-  retries_count = 0
+  # Poll for the report.
+  report_data = poll_for_report(report_def_srv, report_definition_id)
 
-  begin
+  # Check the response code.
+  case report_data[:code]
+    when 301
+      puts "Acquired report data of size: %d" % report_data[:report_data].size
+    when 500
+      puts "Received a failure: %s" % report_data[:body]['failureReason']
+      if report_data[:body]['failures']
+        puts "Failures info:"
+        pp report_data[:body]['failures']
+      end
+    else
+      puts "Report returned with unexpected code %d and body: %s" % [
+        report_data[:code], report_data[:body]]
+  end
+end
+
+def poll_for_report(report_def_srv, report_definition_id)
+  # Initially run with query_token = 'new'.
+  query_token = 'new'
+
+  MAX_RETRIES.times do |retry_count|
     # Acquire report or report status with "download_mcc_report" extension
     # method.
-    report_data = report_def_srv.download_mcc_report(report_definition_id, qt)
-    # Saving query id for following queries.
-    qt = report_data[:body]['qt']
-    # Checking the response code.
-    case report_data[:code]
-      when 200
-        puts "Acquired report of size: %d" % report_data[:body].size
-        break
-      when 206
-        puts "Received a status update: %s" % report_data[:body]['stateName']
-        puts "Waiting for %d seconds to retry..." % RETRY_INTERVAL
-      when 500
-        puts "Received a failure: %s" % report_data[:body]['stateName']
-        break
+    report_data = report_def_srv.download_mcc_report(report_definition_id,
+        query_token)
+    if report_data[:body]
+      # Save query id for following queries.
+      query_token = report_data[:body]['queryToken']
+      # Print current query status.
+      puts "Received a status update: %s" % report_data[:body]['state']
     end
-    sleep(RETRY_INTERVAL)
-    retries_count += 1
-  end while retries_count < MAX_RETRIES
+    if report_data[:code] == 200
+      puts "Try %d/%d: still processing, retry in %d seconds..." % [
+          retry_count + 1, MAX_RETRIES, RETRY_INTERVAL]
+      sleep(RETRY_INTERVAL)
+    else
+      return report_data
+    end
+  end
 end
 
 if __FILE__ == $0

data/examples/v201101/download_mcc_report_as_file.rb

@@ -0,0 +1,118 @@
+#!/usr/bin/ruby
+#
+# Author:: api.dklimkin@gmail.com (Danial Klimkin)
+#
+# Copyright:: Copyright 2010, 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 gets and saves a report from a report definition using MCC
+# (cross-client) feature to a given path. To create a report definition, run
+# add_mcc_report_definition.rb.
+#
+# Please note: This feature is still under development and may change before it
+# is released.
+#
+# Tags: ReportDefinitionService
+
+require 'rubygems'
+gem 'google-adwords-api'
+require 'adwords_api'
+require 'pp'
+
+API_VERSION = :v201101
+MAX_RETRIES = 10
+RETRY_INTERVAL = 30
+
+def download_mcc_report_as_file()
+  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
+  # when called without parameters.
+  adwords = AdwordsApi::Api.new
+  report_def_srv = adwords.service(:ReportDefinitionService, API_VERSION)
+
+  report_definition_id = 'INSERT_REPORT_ID_HERE'.to_i
+  file_name = 'INSERT_OUTPUT_FILE_NAME_HERE'
+
+  # Poll for the report.
+  report_data = poll_for_report(report_def_srv, report_definition_id, file_name)
+
+  # Check the response code.
+  case report_data[:code]
+    when 301
+      puts "Saved report into a file: %s" % file_name
+    when 500
+      puts "Received a failure: %s" % report_data[:body]['failureReason']
+      if report_data[:body]['failures']
+        puts "Failures info:"
+        pp report_data[:body]['failures']
+      end
+    else
+      puts "Report returned with unexpected code %d and body: %s" % [
+        report_data[:code], report_data[:body]]
+  end
+end
+
+def poll_for_report(report_def_srv, report_definition_id, file_name)
+  # Initially run with query_token = 'new'.
+  query_token = 'new'
+
+  MAX_RETRIES.times do |retry_count|
+    # Acquire report or report status with "download_mcc_report_as_file"
+    # extension method.
+    report_data = report_def_srv.download_mcc_report_as_file(
+        report_definition_id, query_token, file_name)
+    if report_data[:body]
+      # Save query id for following queries.
+      query_token = report_data[:body]['queryToken']
+      # Print current query status.
+      puts "Received a status update: %s" % report_data[:body]['state']
+    end
+    if report_data[:code] == 200
+      puts "Try %d/%d: still processing, retry in %d seconds..." % [
+          retry_count + 1, MAX_RETRIES, RETRY_INTERVAL]
+      sleep(RETRY_INTERVAL)
+    else
+      return report_data
+    end
+  end
+end
+
+if __FILE__ == $0
+  begin
+    download_mcc_report_as_file()
+
+  # Connection error. Likely transitory.
+  rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => e
+    puts 'Connection Error: %s' % e
+    puts 'Source: %s' % e.backtrace.first
+
+  # API Error.
+  rescue AdwordsApi::Errors::ApiException => e
+    puts 'API Exception caught.'
+    puts 'Message: %s' % e.message
+    puts 'Code: %d' % e.code if e.code
+    puts 'Trigger: %s' % e.trigger if e.trigger
+    puts 'Errors:'
+    if e.errors
+      e.errors.each_with_index do |error, index|
+        puts ' %d. Error type is %s. Fields:' % [index + 1, error[:xsi_type]]
+        error.each_pair do |field, value|
+          if field != :xsi_type
+            puts '     %s: %s' % [field, value]
+          end
+        end
+      end
+    end
+  end
+end

data/examples/v201101/get_bulk_mutate_job.rb

@@ -75,7 +75,7 @@ if __FILE__ == $0
   # To enable logging of SOAP requests, set the ADWORDSAPI_DEBUG environment
   # variable to 'true'. This can be done either from your operating system
   # environment or via code, as done below.
-  ENV['ADWORDSAPI_DEBUG'] = 'true'
+  ENV['ADWORDSAPI_DEBUG'] = 'false'
 
   begin
     get_all_bulk_mutate_jobs()

data/examples/v201101/perform_bulk_mutate_job.rb

@@ -190,7 +190,7 @@ if __FILE__ == $0
   # To enable logging of SOAP requests, set the ADWORDSAPI_DEBUG environment
   # variable to 'true'. This can be done either from your operating system
   # environment or via code, as done below.
-  ENV['ADWORDSAPI_DEBUG'] = 'true'
+  ENV['ADWORDSAPI_DEBUG'] = 'false'
 
   begin
     perform_bulk_mutate_job()

data/lib/adwords_api.rb

@@ -22,7 +22,7 @@
 
 require 'rubygems'
 gem 'soap4r', '=1.5.8'
-gem 'google-ads-common', '~>0.2.0'
+gem 'google-ads-common', '~>0.2.1'
 require 'thread'
 require 'uri'
 require 'ads_common/logger'
@@ -261,13 +261,9 @@ module AdwordsApi
     #   configuration rather than use the default
     #
     def load_config(provided_config = nil)
-      @config = AdsCommon::Config.new
-      if !provided_config
-        filename = File.join(ENV['HOME'], 'adwords_api.yml')
-        @config.load(filename)
-      else
-        @config.set_all(provided_config)
-      end
+      @config = (provided_config.nil?) ?
+          AdsCommon::Config.new(File.join(ENV['HOME'], 'adwords_api.yml')) :
+          AdsCommon::Config.new(provided_config)
     end
   end
 end

data/lib/adwords_api/api_config.rb

@@ -40,7 +40,7 @@ module AdwordsApi
     # Set other constants
     API_NAME = 'AdwordsApi'
     API_PATH = 'adwords_api'
-    CLIENT_LIB_VERSION = '0.1.1'
+    CLIENT_LIB_VERSION = '0.1.2'
 
     # Configure the services available to each version
     @@service_config = {

data/lib/adwords_api/auth/v13_login_handler.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/ruby
 #
-# Authors:: api.sgomes@gmail.com (Sérgio Gomes)
+# Authors:: api.dklimkin@gmail.com (Danial Klimkin)
 #
 # Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
 #
@@ -24,12 +24,9 @@ require 'ads_common/auth/base_handler'
 module AdwordsApi
   module Auth
     class V13LoginHandler < AdsCommon::Auth::BaseHandler
-
-      # Ensure that clientEmail and clientCustomerId are always present
       def header_list(credentials)
-        creds = credentials.keys.dup
-        creds << :clientEmail unless creds.include? :clientEmail
-        creds << :clientCustomerId unless creds.include? :clientCustomerId
+        # Ensure that clientEmail and clientCustomerId are always present.
+        return credentials.keys.dup() | [:clientEmail, :clientCustomerId]
       end
     end
   end

data/lib/adwords_api/extensions.rb

@@ -23,7 +23,6 @@
 require 'rexml/document'
 require 'csv'
 require 'ads_common/http'
-require 'json'
 
 module AdwordsApi
 
@@ -38,15 +37,19 @@ module AdwordsApi
       [:v201008, :ReportDefinitionService] => [:download_report,
           :download_report_as_file],
       [:v201101, :ReportDefinitionService] => [:download_report,
-          :download_report_as_file]
+          :download_report_as_file, :download_mcc_report,
+          :download_mcc_report_as_file]
     }
 
-    # Defines the parameter list for every extension method
+    # Defines the parameter list for every extension method.
     @@methods = {
       :download_xml_report     => [:job_id],
       :download_csv_report     => [:job_id],
       :download_report         => [:report_definition_id],
-      :download_report_as_file => [:report_definition_id, :path]
+      :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]
     }
 
     # Return list of all extension methods, indexed by version and service.
@@ -84,7 +87,7 @@ module AdwordsApi
       status_field = nil
       download_field = nil
 
-      if wrapper.api.config.read('service.use_ruby_names')
+      if wrapper.api.config.read('service.use_ruby_names', true)
         status_field = :get_report_job_status_return
         download_field = :get_report_download_url_return
       else
@@ -116,7 +119,7 @@ module AdwordsApi
       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 AdwordsApi::Error::Error, 'Report generation failed.'
+        raise AdwordsApi::Errors::ApiException, 'Report generation failed.'
       end
     end
 
@@ -168,7 +171,7 @@ module AdwordsApi
         return csv
       rescue REXML::ParseException => e
         # Error parsing XML
-        raise AdwordsApi::Error::Error,
+        raise AdwordsApi::Errors::ApiException,
             "Error parsing report XML: %s\nSource: %s" % [e, e.backtrace.first]
       end
     end
@@ -188,12 +191,7 @@ module AdwordsApi
     #
     def self.download_report_as_file(wrapper, report_definition_id, path)
       report_data = download_report(wrapper, report_definition_id)
-
-      # Write to file (if provided)
-      if path
-        open(path, 'w') { |file| file.puts(report_data) }
-      end
-
+      save_to_file(report_data, path)
       return nil
     end
 
@@ -210,21 +208,103 @@ module AdwordsApi
     # The data for the report (as a string)
     #
     def self.download_report(wrapper, report_definition_id)
-      report_response = get_report_response(wrapper, "?__rd=%s" %
-          report_definition_id)
+      url = get_report_url(wrapper, "?__rd=%s" % report_definition_id)
+      report_response = get_report_response(wrapper, url)
       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, report_definition_id, query_token)
+      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, report_definition_id,
+        query_token, path)
+      do_download_mcc_report(wrapper, report_definition_id, query_token, path)
+    end
+
     private
 
-    # Gets a report response for a given parameters.
-    def self.get_report_response(wrapper, parameters)
-      # Get download URL.
-      url = AdwordsApi::ApiConfig.report_download_url(
+    # 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, 'w') { |file| file.puts(data) } if path
+    end
+
+    # Generates default report URL with given parameters.
+    def self.get_report_url(wrapper, parameters)
+      return AdwordsApi::ApiConfig.report_download_url(
           wrapper.api.config.read('service.environment'),
-          wrapper.version)
+          wrapper.version) + parameters
+    end
 
-      # Set HTTP headers.
+    # Gets a report response for a given parameters.
+    def self.get_report_response(wrapper, url)
+      headers = get_report_request_headers(wrapper)
+      report_response = AdsCommon::Http.get_response(url, wrapper.api.config,
+          headers)
+      return report_response
+    end
+
+    def self.get_report_request_headers(wrapper)
       headers = {}
       credentials = wrapper.api.credential_handler.credentials
       auth_handler = wrapper.api.client_login_handler
@@ -234,12 +314,63 @@ module AdwordsApi
         headers['clientEmail'] = credentials[:clientEmail]
       elsif credentials[:clientCustomerId]
         headers['clientCustomerId'] = credentials[:clientCustomerId]
+      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
 
-      # Download report data.
-      report_response = AdsCommon::Http.get_response(url + parameters,
-          wrapper.api.config, headers)
-      return report_response
+    # Converts xml into a convenient hash.
+    def self.xml_to_hash(xml)
+      result = {}
+      xml.elements.each do |item|
+        value = case item.has_elements?
+          when true: xml_to_hash(item)
+          else item.get_text()
+        end
+        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 Array.new if object.nil?
+      return object.is_a?(Array) ? object : [object]
+    end
+
+    # Checks for old-style pre-MCC reporting error.
+    def self.check_old_error(response_text)
+      error_message_regex = '^!!!(-?\d+)\|\|\|(-?\d+)\|\|\|(.*)\?\?\?'
+      matches = response_text.match(error_message_regex)
+      if matches
+        message = (matches[3].nil?) ? response_text : matches[3]
+        raise AdwordsApi::Errors::ApiException,
+            "Report download error occured: %s" % message
+      end
+      return nil
     end
   end
 end