google-adwords-api 0.4.1 → 0.4.2

data/ChangeLog

@@ -1,3 +1,8 @@
+0.4.2:
+  - Updated Reporting error codes handling.
+  - Fix for old v13 services compatibility.
+  - Require google-ads-common 0.5.4 or later from now on.
+
 0.4.1:
   - Support for v201109.
   - Added support and example for AdHoc reports.

data/README

@@ -29,7 +29,7 @@ which is installed automatically as a dependency.
 The following gem libraries are required:
   - savon v0.9.6
   - httpclient v2.1.2 or greater
-  - google-ads-common v0.5.2 or later.
+  - google-ads-common v0.5.4 or later.
 
 
 == 2 - Using the client library:

data/Rakefile

@@ -48,7 +48,7 @@ spec = Gem::Specification.new do |s|
   s.test_files = tests
   s.has_rdoc = true
   s.extra_rdoc_files = docs
-  s.add_dependency('google-ads-common', '~> 0.5.2')
+  s.add_dependency('google-ads-common', '~> 0.5.4')
   s.add_dependency('savon', '= 0.9.6')
 end
 
@@ -71,7 +71,7 @@ task :generate do
   api_config = AdwordsApi::ApiConfig
   versions = api_config.versions()
   versions.each do |version|
-    code_path = "lib/%s/%s" % [api_config.api_path, version]
+    code_path = "lib/%s/%s" % [api_config.api_name.to_s.snakecase, version]
     wsdls = AdwordsApi::ApiConfig.get_wsdls(version)
     wsdls.each do |service_name, wsdl_url|
       logger.info("Processing %s at [%s]..." % [service_name, wsdl_url])

data/examples/v201109/oauth_report_download.rb

@@ -0,0 +1,97 @@
+#!/usr/bin/ruby
+#
+# Author:: api.dklimkin@gmail.com (Danial Klimkin)
+#
+# Copyright:: Copyright 2011, 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 downloads an Ad Hoc report from a XML report definition
+# using OAuth as authorization method.
+
+require 'rubygems'
+require 'adwords_api'
+
+API_VERSION = :v201109
+MAX_RETRIES = 3
+
+def oauth_report_download()
+  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
+  # when called without parameters.
+  adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
+  # Get report utilities for the version.
+  report_utils = adwords.report_utils(API_VERSION)
+
+  # File name to write report to. To retrieve the report as return value, use
+  # "download_report" method.
+  file_name = 'INSERT_OUTPUT_FILE_NAME_HERE'
+
+  # Define report definition. You can also pass your own XML text as a string.
+  report_definition = {
+    :selector => {
+        :fields => ['CampaignId', 'Id', 'Impressions', 'Clicks', 'Cost'],
+        # Predicates are optional.
+        :predicates => {
+          :field => 'Status',
+          :operator => 'IN',
+          :values => ['ENABLED', 'PAUSED']
+        }
+      },
+      :report_name => 'Custom ADGROUP_PERFORMANCE_REPORT',
+      :report_type => 'ADGROUP_PERFORMANCE_REPORT',
+      :download_format => 'CSV',
+      :date_range_type => 'LAST_7_DAYS',
+      # Enable to get rows with zero impressions.
+      :include_zero_impressions => false
+  }
+
+  retry_count = 0
+
+  begin
+    # Download report, using "download_report_as_file" utility method.
+    report_utils.download_report_as_file(report_definition, file_name)
+    puts "Report was downloaded to '%s'." % file_name
+  rescue AdsCommon::Errors::OAuthVerificationRequired => e
+    if retry_count < MAX_RETRIES
+      puts "Hit Auth error, please navigate to URL:\n\t%s" % e.oauth_url
+      print 'log in and type the verification code: '
+      verification_code = gets.chomp
+      adwords.credential_handler.set_credential(
+          :oauth_verification_code, verification_code)
+      retry_count += 1
+      retry
+    else
+      raise AdsCommon::Errors::AuthError, 'Failed to authenticate.'
+    end
+  end
+end
+
+if __FILE__ == $0
+  begin
+    oauth_report_download()
+
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
+
+  # API errors.
+  rescue AdwordsApi::Errors::ReportError => e
+    puts "Reporting Error: %s" % e.message
+  end
+end

data/lib/adwords_api.rb

@@ -20,7 +20,7 @@
 #
 # Contains the main classes for the client library.
 
-gem 'google-ads-common', '~>0.5.2'
+gem 'google-ads-common', '~>0.5.4'
 
 require 'ads_common/api'
 require 'ads_common/auth/oauth_handler'
@@ -84,7 +84,7 @@ module AdwordsApi
         end
         handlers = header_list.map do |header|
           AdsCommon::SavonHeaders::SimpleHeaderHandler.new(
-              @credential_handler, auth_handler, header, nil, version)
+              @credential_handler, auth_handler, header, namespace, version)
         end
       else
         handlers = case auth_method
@@ -226,8 +226,6 @@ module AdwordsApi
       return AdwordsApi::ReportUtils.new(self, version)
     end
 
-    private
-
     # Overrides AdsCommon::Api.get_auth_handler to allow version-specific
     # handlers.
     def get_auth_handler(environment, version = nil)
@@ -237,6 +235,8 @@ module AdwordsApi
       return @auth_handler
     end
 
+    private
+
     # Creates an appropriate authentication handler for each service (reuses the
     # ClientLogin one to avoid generating multiple tokens unnecessarily).
     #
@@ -249,7 +249,7 @@ module AdwordsApi
     #
     def create_auth_handler(environment, version = nil)
       return (version == :v13) ?
-          AdwordsApi::V13LoginHandler.new : super(environment)
+          AdwordsApi::V13LoginHandler.new(@config) : super(environment)
     end
 
     # Executes block with a temporary flag set to a given value. Returns block

data/lib/adwords_api/api_config.rb

@@ -41,8 +41,7 @@ module AdwordsApi
 
     # Set other constants
     API_NAME = 'AdwordsApi'
-    API_PATH = 'adwords_api'
-    CLIENT_LIB_VERSION = '0.4.1'
+    CLIENT_LIB_VERSION = '0.4.2'
     DEFAULT_CONFIG_FILENAME = 'adwords_api.yml'
 
     # Configure the services available to each version
@@ -265,10 +264,6 @@ module AdwordsApi
       API_NAME
     end
 
-    def self.api_path
-      API_PATH
-    end
-
     def self.service_config
       @@service_config
     end
@@ -293,32 +288,10 @@ module AdwordsApi
       @@headers_config
     end
 
-    # Returns the full interface class name for a given service. Overriding this
-    # method from ads_common to fix odd behaviour with v13 class names.
-    #
-    # Args:
-    # - version: the API version (as an integer)
-    # - service: the service name (as a string)
-    #
-    # Returns:
-    # The full interface class name for the given service (as a string)
-    #
-    def self.interface_name(version, service)
-      service_str = service.to_s
-      service_str = service_str.sub(/Service$/, '') if version == :v13
-      return module_name(version, service) + "::" + service_str
-    end
-
-    def self.do_require(version, service)
-      service_name = service.to_s.snakecase()
-      filename = "%s/%s/%s" % [api_path, version, service_name]
-      require filename
-    end
-
     # Get the download URL for reports.
     #
     # Args:
-    # - environment: the service environment to be used (as a string)
+    # - environment: the service environment to be used
     # - version: the API version (as a symbol)
     #
     # Returns:
@@ -335,7 +308,7 @@ module AdwordsApi
     # Get the download URL for Ad Hoc reports.
     #
     # Args:
-    # - environment: the service environment to be used (as a string)
+    # - environment: the service environment to be used
     # - version: the API version (as a symbol)
     #
     # Returns:

data/lib/adwords_api/client_login_header_handler.rb

@@ -60,6 +60,23 @@ module AdwordsApi
     end
 
     private
+    # Generates SOAP request header with login credentials and namespace
+    # definition.
+    #
+    # Args:
+    #  - None
+    #
+    # Returns:
+    #  - Hash containing a header with filled in credentials
+    #
+    def generate_request_header()
+      headers = @auth_handler.headers(@credential_handler.credentials(@version))
+      return headers.inject({}) do |request_header, (header, value)|
+        request_header[prepend_namespace(header)] = value
+        request_header
+      end
+    end
+
     # Skips namespace prefixes for all elements except top level. Use default
     # (inherited) prefixing for the top level key.
     #

data/lib/adwords_api/errors.rb

@@ -66,6 +66,12 @@ module AdwordsApi
 
     # Error for server-side report error.
     class ReportError < AdsCommon::Errors::ApiException
+      attr_reader :http_code
+
+      def initialize(http_code, message)
+        super(message)
+        @http_code = http_code
+      end
     end
   end
 end

data/lib/adwords_api/extensions.rb

@@ -20,8 +20,10 @@
 # Contains extensions to the API, that is, service helper methods provided in
 # client-side by the client library.
 
-require 'rexml/document'
 require 'csv'
+require 'httpi/request'
+require 'rexml/document'
+
 require 'ads_common/http'
 
 module AdwordsApi
@@ -223,18 +225,19 @@ module AdwordsApi
 
     # Gets a report response for a given parameters.
     def self.get_report_response(wrapper, url)
-      headers = get_report_request_headers(wrapper)
+      headers = get_report_request_headers(wrapper, url)
       report_response = AdsCommon::Http.get_response(url, wrapper.api.config,
           headers)
       return report_response
     end
 
-    def self.get_report_request_headers(wrapper)
+    def self.get_report_request_headers(wrapper, url)
       headers = {}
       credentials = wrapper.api.credential_handler.credentials
-      auth_handler = wrapper.api.client_login_handler
-      headers['Authorization'] = "GoogleLogin auth=%s" %
-          auth_handler.headers(credentials)[:authToken]
+      auth_handler = wrapper.api.get_auth_handler(
+          wrapper.api.config.read('service.environment'), wrapper.version)
+      headers['Authorization'] = auth_handler.auth_string(credentials,
+        HTTPI::Request.new(url))
       if credentials[:clientCustomerId]
         headers['clientCustomerId'] = credentials[:clientCustomerId]
       elsif credentials[:clientEmail]

data/lib/adwords_api/report_utils.rb

@@ -20,6 +20,7 @@
 # Contains utility methods specific to reporting.
 
 require 'gyoku'
+require 'httpi/request'
 
 require 'adwords_api/errors'
 
@@ -89,10 +90,10 @@ module AdwordsApi
     # Send POST request for a report and returns Response object.
     def get_report_response(report_definition)
       definition_text = get_report_definition_text(report_definition)
-      data = {"__rdxml" => definition_text}
+      data = {'__rdxml' => definition_text}
       url = @api.api_config.adhoc_report_download_url(
           @api.config.read('service.environment'), @version)
-      headers = get_report_request_headers()
+      headers = get_report_request_headers(url)
       response = AdsCommon::Http.post_response(url, data, @api.config, headers)
       check_for_errors(response)
       return response
@@ -102,8 +103,8 @@ module AdwordsApi
     # and Hash (renders XML).
     def get_report_definition_text(report_definition)
       return case report_definition
-        when String: report_definition
-        when Hash: report_definition_to_xml(report_definition)
+        when String then report_definition
+        when Hash then report_definition_to_xml(report_definition)
         else
           raise AdwordsApi::Errors::InvalidReportDefinitionError,
               "Unknown object for report definition: %s" %
@@ -112,13 +113,17 @@ module AdwordsApi
     end
 
     # Prepares headers for report request.
-    def get_report_request_headers()
+    def get_report_request_headers(url)
       credentials = @api.credential_handler.credentials
-      auth_string = @api.client_login_handler.headers(credentials)[:authToken]
+      auth_handler = @api.get_auth_handler(
+          @api.config.read('service.environment'), @version)
+      auth_string = auth_handler.auth_string(
+          credentials, HTTPI::Request.new(url))
       headers = {
-          'Authorization' => "GoogleLogin auth=%s" % auth_string,
+          'Authorization' => auth_string,
           'ClientCustomerId' => credentials[:clientCustomerId],
-          'Content-Type' => 'multipart/form-data'
+          'Content-Type' => 'multipart/form-data',
+          'developerToken' => credentials[:developerToken]
       }
       return headers
     end
@@ -131,20 +136,23 @@ module AdwordsApi
     # Checks downloaded data for error signature. Raises ReportError if it
     # detects an error.
     def check_for_errors(response)
-      # Check for error code.
-      unless response.code == 200
-        raise AdwordsApi::Errors::ReportError,
-            "Report download error occured, http code: %d" % response.code
-      end
       # Check for error in body.
       report_body = response.body
-      error_message_regex = '^!!!(-?\d+)\|\|\|(-?\d+)\|\|\|(.*)\?\?\?'
-      data = report_body.slice(0, 1024)
-      matches = data.match(error_message_regex)
-      if matches
-        message = (matches[3].nil?) ? data : matches[3]
-        raise AdwordsApi::Errors::ReportError,
-            "Report download error occured: %s" % message
+      if report_body
+        error_message_regex = '^!!!(-?\d+)\|\|\|(-?\d+)\|\|\|(.*)\?\?\?'
+        data = report_body.slice(0, 1024)
+        matches = data.match(error_message_regex)
+        if matches
+          message = (matches[3].nil?) ? data : matches[3]
+          raise AdwordsApi::Errors::ReportError.new(response.code,
+              "Report download error occured: %s" % message)
+        end
+      end
+      # Check for error code.
+      unless response.code == 200
+        raise AdwordsApi::Errors::ReportError.new(response.code,
+            "Report download error occured, http code: %d, body: %s" %
+            [response.code, response.body])
       end
       return nil
     end

data/test/adwords_api/test_api_config.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/ruby
+#
+# Author:: api.dklimkin@gmail.com (Danial Klimkin)
+#
+# Copyright:: Copyright 2011, 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.
+#
+# Tests the general API features.
+
+require 'rubygems'
+require 'test/unit'
+require 'adwords_api'
+
+class TestApiConfig < Test::Unit::TestCase
+  # Initialize tests.
+  def setup
+    @config = AdwordsApi::ApiConfig
+  end
+
+  # Test correct require path.
+  def test_do_require
+    name1 = @config.do_require(:v201109, :InfoService)
+    assert_equal('adwords_api/v201109/info_service', name1)
+    name2 = @config.do_require(:v13, :AccountService)
+    assert_equal('adwords_api/v13/account_service', name2)
+  end
+
+  # Test correct module name.
+  def test_module_name
+    name1 = @config.module_name(:v201109, :InfoService)
+    assert_equal('AdwordsApi::V201109::InfoService', name1)
+    name2 = @config.module_name(:v13, :AccountService)
+    assert_equal('AdwordsApi::V13::AccountService', name2)
+  end
+
+  # Test correct interface name.
+  def test_interface_name
+    name1 = @config.interface_name(:v201109, :InfoService)
+    assert_equal('AdwordsApi::V201109::InfoService::InfoService', name1)
+    name2 = @config.interface_name(:v13, :AccountService)
+    assert_equal('AdwordsApi::V13::AccountService::AccountService', name2)
+  end
+end

data/test/adwords_api/test_report_utils.rb

@@ -0,0 +1,110 @@
+#!/usr/bin/ruby
+#
+# Author:: api.dklimkin@gmail.com (Danial Klimkin)
+#
+# Copyright:: Copyright 2011, 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.
+#
+# Tests report utils.
+
+require 'rubygems'
+require 'test/unit'
+require 'adwords_api'
+
+API_VERSION = :v201109
+
+# Overriding default access levels to public for tests.
+module AdwordsApi
+  class ReportUtils
+    public :check_for_errors
+  end
+end
+
+# Stub class for HTTP response.
+class ResponseStub
+  attr_reader :code
+  attr_reader :body
+
+  def initialize(code, body)
+    @code, @body = code, body
+  end
+end
+
+# Typical reply types.
+REPLY_TYPES = [
+    {:reply => '!!!2|||-1|||Improperly formatted report request???',
+     :message => 'Improperly formatted report request'},
+    {:reply => "!!!2|||-1|||ReportDefinitionError.INVALID_FIELD_NAME_FOR_REPORT @ ; trigger:'bCampaignId'???",
+     :message => "ReportDefinitionError.INVALID_FIELD_NAME_FOR_REPORT @ ; trigger:'bCampaignId'"}
+]
+
+VALID_REPORT = '"Custom ADGROUP_PERFORMANCE_REPORT (Oct 20, 2011-Oct 26, 2011)"\nCampaign ID,Ad group ID,Impressions,Clicks,Cost\nTotal, --,0,0,0.00'
+
+class TestReportUtils < Test::Unit::TestCase
+  # Initialize tests.
+  def setup
+    @api = AdwordsApi::Api.new
+    @report_utils = @api.report_utils(API_VERSION)
+  end
+
+  # Testing HTTP code 400.
+  def test_check_for_errors_400
+    REPLY_TYPES.each do |reply_type|
+      begin
+        response = ResponseStub.new(400, reply_type[:reply])
+        @report_utils.check_for_errors(response)
+        assert(false, 'No exception thrown for code 400')
+      rescue AdwordsApi::Errors::ReportError => e
+        assert_equal(400, e.http_code)
+        assert(e.message.include?(reply_type[:message]))
+      end
+    end
+  end
+
+  # Testing HTTP code 500.
+  def test_check_for_errors_500
+    REPLY_TYPES.each do |reply_type|
+      begin
+        response = ResponseStub.new(500, nil)
+        @report_utils.check_for_errors(response)
+        assert(false, 'No exception thrown for code 500')
+      rescue AdwordsApi::Errors::ReportError => e
+        assert_equal(500, e.http_code)
+      end
+    end
+  end
+
+  # Testing HTTP code 200 with success.
+  def test_check_for_errors_200_success
+    response = ResponseStub.new(200, VALID_REPORT)
+    assert_nothing_raised do
+      @report_utils.check_for_errors(response)
+    end
+  end
+
+  # Testing HTTP code 200 with failure.
+  def test_check_for_errors_200_success
+    REPLY_TYPES.each do |reply_type|
+      begin
+        response = ResponseStub.new(200, reply_type[:reply])
+        @report_utils.check_for_errors(response)
+        assert(false, 'No exception thrown for code 200')
+      rescue AdwordsApi::Errors::ReportError => e
+        assert_equal(200, e.http_code)
+        assert(e.message.include?(reply_type[:message]))
+      end
+    end
+  end
+end

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: google-adwords-api
 version: !ruby/object:Gem::Version 
-  hash: 13
   prerelease: false
   segments: 
   - 0
   - 4
-  - 1
-  version: 0.4.1
+  - 2
+  version: 0.4.2
 platform: ruby
 authors: 
 - Danial Klimkin
@@ -15,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-10-20 00:00:00 +04:00
+date: 2011-11-01 00:00:00 +04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -26,12 +25,11 @@ dependencies:
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
-        hash: 15
         segments: 
         - 0
         - 5
-        - 2
-        version: 0.5.2
+        - 4
+        version: 0.5.4
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
@@ -42,7 +40,6 @@ dependencies:
     requirements: 
     - - "="
       - !ruby/object:Gem::Version 
-        hash: 55
         segments: 
         - 0
         - 9
@@ -517,6 +514,7 @@ files:
 - examples/v201109/get_geo_location_info.rb
 - examples/v201109/get_all_languages.rb
 - examples/v201109/delete_ad_group.rb
+- examples/v201109/oauth_report_download.rb
 - examples/v201109/download_report.rb
 - examples/v201109/get_all_images.rb
 - examples/v201109/check_campaigns.rb
@@ -569,6 +567,8 @@ files:
 - examples/v201109/get_total_usage_units_per_month.rb
 - Rakefile
 - test/bugs/test_issue_00000031.rb
+- test/adwords_api/test_api_config.rb
+- test/adwords_api/test_report_utils.rb
 - README
 - COPYING
 - ChangeLog
@@ -586,7 +586,6 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
@@ -595,7 +594,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
@@ -608,3 +606,5 @@ specification_version: 3
 summary: Ruby Client libraries for AdWords API
 test_files: 
 - test/bugs/test_issue_00000031.rb
+- test/adwords_api/test_api_config.rb
+- test/adwords_api/test_report_utils.rb