google-adwords-api 0.2.0 → 0.2.1

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.2.0'
+    CLIENT_LIB_VERSION = '0.2.1'
     DEFAULT_CONFIG_FILENAME = 'adwords_api.yml'
 
     # Configure the services available to each version
@@ -85,6 +85,7 @@ module AdwordsApi
     # Configure the different environments, with the base URL for each one
     @@environment_config = {
       :PRODUCTION => {
+        :oauth_scope => 'https://adwords.google.com/api/adwords/',
         :v13 => 'https://adwords.google.com/api/adwords/',
         :v200909 => 'https://adwords.google.com/api/adwords/',
         :v201003 => 'https://adwords.google.com/api/adwords/',
@@ -92,6 +93,7 @@ module AdwordsApi
         :v201101 => 'https://adwords.google.com/api/adwords/'
       },
       :SANDBOX => {
+        :oauth_scope => 'https://adwords-sandbox.google.com/api/adwords/',
         :v13 => 'https://sandbox.google.com/api/adwords/',
         :v200909 => 'https://adwords-sandbox.google.com/api/adwords/',
         :v201003 => 'https://adwords-sandbox.google.com/api/adwords/',

data/lib/adwords_api/credential_handler.rb

@@ -1,6 +1,7 @@
 #!/usr/bin/ruby
 #
 # Authors:: api.sgomes@gmail.com (Sérgio Gomes)
+#           api.dklimkin@gmail.com (Danial Klimkin)
 #
 # Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
 #
@@ -24,8 +25,6 @@ require 'adwords_api/api_config'
 
 module AdwordsApi
   class CredentialHandler < AdsCommon::CredentialHandler
-    SERVICE_NAME = 'adwords'
-
     # Whether we're making MCC-level requests.
     attr_accessor :use_mcc
     # Whether we're making validate-only requests.
@@ -34,7 +33,7 @@ module AdwordsApi
     attr_accessor :partial_failure
 
     def initialize(config)
-      super
+      super(config)
       @use_mcc = false
       @validate_only = false
       @partial_failure = false
@@ -44,18 +43,25 @@ module AdwordsApi
     # generation.
     def credentials(version = nil)
       validate_headers_for_server
-      result = {}
+      method = @credentials[:method].to_s.upcase.to_sym
+      result = case method
+        when :CLIENTLOGIN
+          {:email => @credentials[:email],
+           :password => @credentials[:password]}
+        when :OAUTH
+          {:oauth_consumer_key => @credentials[:oauth_consumer_key],
+           :oauth_consumer_secret => @credentials[:oauth_consumer_secret],
+           :oauth_verification_code => @credentials[:oauth_verification_code],
+           :oauth_token => @credentials[:oauth_token],
+           :oauth_token_secret => @credentials[:oauth_token_secret],
+           :oauth_callback => @credentials[:oauth_callback],
+           :oauth_method => @credentials[:oauth_method]}
+      end
       client_lib = 'Ruby-AwApi-%s|' % AdwordsApi::ApiConfig::CLIENT_LIB_VERSION
-      user_agent = @credentials[:user_agent]
-      user_agent = $0 if user_agent.nil?
+      user_agent = @credentials[:user_agent] || $0
       user_agent = client_lib + user_agent
-      if (version == :v13)
-        result[:useragent] = user_agent
-      else
-        result[:userAgent] = user_agent
-      end
-      result[:email] = @credentials[:email]
-      result[:password] = @credentials[:password]
+      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]
@@ -64,13 +70,11 @@ module AdwordsApi
           result[:clientCustomerId] = @credentials[:client_customer_id]
         end
       end
-      if version != :v13 and @validate_only
-        result[:validateOnly] = 'true'
-      end
-      if version != :v13 and @partial_failure
-        result[:partialFailure] = 'true'
+      if version != :v13
+        result[:validateOnly] = 'true' if @validate_only
+        result[:partialFailure] = 'true' if @partial_failure
       end
-      return result
+      return result.reject {|k,v| v.nil?}
     end
 
     private
@@ -83,28 +87,39 @@ module AdwordsApi
     # being used for production or vice-versa.
     #
     def validate_headers_for_server
-      email = @credentials[:email]
+      method = @credentials[:method].to_s.upcase.to_sym
       token = @credentials[:developer_token]
-      client = @credentials[:client_email]
-      environment = @config.read('service.environment').to_s.upcase
-
-      sandbox_token = (token =~ /#{Regexp.escape(email)}\+\+[a-zA-Z]{3}/)
-      sandbox_client = (client =~ /client_[1-5]\+#{Regexp.escape(email)}/)
-
-      # Only check the token, because 'client_n+x@y.tld' may be a valid client
-      # email for some customers.
-      if environment == 'PRODUCTION' and sandbox_token
-        raise AdsCommon::Errors::EnvironmentMismatchError,
-            'Attempting to connect to production with sandbox credentials.'
-      # Check if either the token or client email do not follow the correct
-      # format. Client email may not exist, though.
-      elsif environment == 'SANDBOX' and (!sandbox_token or
-          (client.length > 0 and !sandbox_client))
-        raise AdsCommon::Errors::EnvironmentMismatchError,
-            'Attempting to connect to the sandbox with malformatted ' +
-            'credentials. Please check ' +
-            'http://code.google.com/apis/adwords/docs/developer/' +
-            'adwords_api_sandbox.html#requestheaders for details.'
+      client_email = @credentials[:client_email]
+      (sandbox_token, sandbox_client) = case method
+        when :CLIENTLOGIN
+          email = @credentials[:email]
+          [(token =~ /#{Regexp.escape(email)}\+\+[a-zA-Z]{3}/),
+           (client_email =~ /client_[1-5]\+#{Regexp.escape(email)}/)]
+        when :OAUTH
+          [(token =~ /.+@.+\+\+[a-zA-Z]{3}/),
+           (client_email =~ /client_[1-5]\+.+@.+/)]
+        else
+          [nil, nil]
+      end
+      environment = @config.read('service.environment')
+      case environment
+        when :PRODUCTION
+          # Only check the token, because 'client_n+x@y.tld' may be a valid
+          # client email for some customers.
+          if sandbox_token
+            raise AdsCommon::Errors::EnvironmentMismatchError,
+                'Attempting to connect to production with sandbox credentials.'
+          end
+        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))
+            raise AdsCommon::Errors::EnvironmentMismatchError,
+                'Attempting to connect to the sandbox with malformatted ' +
+                'credentials. Please check ' +
+                'http://code.google.com/apis/adwords/docs/developer/' +
+                'adwords_api_sandbox.html#requestheaders for details.'
+          end
       end
     end
   end

data/lib/adwords_api/extensions.rb

@@ -354,7 +354,7 @@ module AdwordsApi
 
     # Makes sure object is an array.
     def self.arrayize(object)
-      return Array.new if object.nil?
+      return [] if object.nil?
       return object.is_a?(Array) ? object : [object]
     end
 

data/lib/adwords_api/nested_header_handler.rb

@@ -0,0 +1,47 @@
+#!/usr/bin/ruby
+#
+# Authors:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# 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.
+#
+# Handles soap headers for AdWords v2009-style SOAP requests (nested headers).
+
+require 'soap/header/simplehandler'
+
+module AdwordsApi
+  class NestedHeaderHandler < SOAP::Header::SimpleHandler
+
+    def initialize(credential_handler, auth_handler, top_element_name,
+        top_namespace, inner_namespace, version = nil)
+      super(XSD::QName.new(top_namespace, top_element_name))
+      @credential_handler = credential_handler
+      @auth_handler = auth_handler
+      @ns = inner_namespace
+      @version = version
+    end
+
+    # Handles callback.
+    def on_simple_outbound
+      main_header = SOAP::SOAPElement.new(nil)
+      credentials = @credential_handler.credentials
+      @auth_handler.headers(credentials).each do |cred, value|
+        cred_header = SOAP::SOAPElement.new(XSD::QName.new(@ns, cred), value)
+        main_header.add(cred_header)
+      end
+      return main_header
+    end
+  end
+end

data/lib/adwords_api/single_header_handler.rb

@@ -0,0 +1,41 @@
+#!/usr/bin/ruby
+#
+# Authors:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# 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.
+#
+# Handles soap headers for AdWords v13-style SOAP requests (flat headers).
+
+require 'soap/header/simplehandler'
+
+module AdwordsApi
+  class SingleHeaderHandler < SOAP::Header::SimpleHandler
+
+    def initialize(credential_handler, auth_handler,
+        element_name, element_namespace = nil, version = nil)
+      super(XSD::QName.new(element_namespace, element_name))
+      @credential_handler = credential_handler
+      @auth_handler = auth_handler
+      @element_name = element_name
+      @version = version
+    end
+
+    def on_simple_outbound
+      credentials = @credential_handler.credentials
+      return @auth_handler.headers(credentials)[@element_name]
+    end
+  end
+end

data/lib/adwords_api/soap4r/rake_common.rb

@@ -0,0 +1,345 @@
+#!/usr/bin/ruby
+#
+# Authors:: api.sgomes@gmail.com (Sérgio Gomes)
+#           api.jeffy@gmail.com (Jeffrey Posnick)
+#           chanezon@google.com (Patrick Chanezon)
+#           leavengood@gmail.com (Ryan Leavengood)
+#
+# 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.
+#
+# Common Rake tasks for Soap4r-based AdWords client library.
+
+require 'rubygems'
+gem 'rake'
+gem 'soap4r', '=1.5.8'
+require 'fileutils'
+require 'logger'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/clean'
+require 'rake/testtask'
+require 'wsdl/soap/wsdl2ruby'
+require 'xsd/codegen/classdef'
+
+require 'ads_common/http'
+
+require 'adwords_api/soap4r/soap4r_patches'
+
+$API_CONFIG = $MODULE::ApiConfig
+
+$WSDLDIR = 'wsdl'
+$LIBDIR = 'lib'
+$DOCDIR = 'doc'
+$TESTDIR = 'test'
+$GENDIR = File.join($LIBDIR, $PROJECT_NAME)
+$PKG_VERSION = ENV['REL'] ? ENV['REL'] : $CURRENT_VERSION
+
+SRC_RB = FileList["#{$LIBDIR}/**/*.rb"]
+
+logger = Logger.new(STDOUT)
+logger.level = Logger::INFO
+
+CLEAN.include($WSDLDIR)
+CLEAN.include($DOCDIR)
+$API_CONFIG.versions.each do |version|
+  CLEAN.include(File.join($GENDIR, version.to_s))
+end
+
+CLOBBER.include('pkg')
+
+# ====================================================================
+# Create a default task to prepare library for usage.
+desc "gets the wsdl and generates the classes"
+task :default => [:getwsdl, :generate]
+
+# ====================================================================
+# Create a task to retrieve the WSDL files for the services.
+desc "gets the wsdl files for API services"
+task :getwsdl do
+  $API_CONFIG.versions.each do |version|
+    urls = $API_CONFIG.get_wsdls(version)
+    mkdir_p File.join($WSDLDIR, version.to_s)
+    config = Generator.config
+    config.set('library.logger', logger)
+    urls.each do |service, url|
+      logger.info("Getting #{url}...")
+      save(AdsCommon::Http.get(url, config),
+           get_wsdl_file_name(version.to_s, service.to_s))
+    end
+  end
+end
+
+# Return the full file name of the WSDL file for a given version and service
+def get_wsdl_file_name(version, service)
+  File.join($WSDLDIR, version.to_s, service.to_s) + '.wsdl'
+end
+
+# Apply fixes to the WSDL content in order to make it understandable for the
+# soap4r code generator. The fixes are applied to the original object.
+def fix_wsdl!(wsdl)
+  ['type', 'base'].each do |name|
+    ['long', 'string', 'date', 'int', 'boolean'].each do |type|
+      # Fix this attribute over the entire document
+      wsdl.gsub!(Regexp.new("#{name}=\"#{type}\""), "#{name}=\"xsd:#{type}\"")
+    end
+  end
+  schema_ns = "xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\""
+  if wsdl !~ Regexp.new(schema_ns)
+    wsdl.gsub!(/(<wsdl:definitions[^>]*)>/, '\1 ' + schema_ns + '>')
+  end
+  return wsdl
+end
+
+# Saves this document to the specified path.
+# Doesn't create the file if a 404 error page is returned.
+def save(content, path)
+  if content !~ /<H2>Error 404<\/H2>/
+    File::open(path, 'w') {|f| f.write(fix_wsdl!(content))}
+  end
+end
+
+# ====================================================================
+# Set the default generation task to use soap4r (can be overriden for client
+# libraries).
+desc "generates API classes from the wsdl files"
+task :generate => [:soap4r_generate]
+
+# ====================================================================
+# Create a task to generate all the service classes with soap4r.
+desc "generates API classes from the wsdl files using soap4r"
+task :soap4r_generate do
+  $API_CONFIG.versions.each do |version|
+    gendir = File.join($LIBDIR, $PRODDIR, version.to_s)
+    mkdir_p gendir
+    $API_CONFIG.services(version).each do |service|
+      # Generate SOAP classes with soap4r
+      service_name = service.to_s
+      worker = WSDL::SOAP::WSDL2Ruby.new
+      worker.logger = logger
+      worker.location = get_wsdl_file_name(version, service)
+      worker.basedir = gendir
+      worker.opt.update(get_wsdl_opt(version, service_name))
+      worker.run
+
+      # Fix the "require" statements so that they work in the client library's
+      # directory structure
+      fix_import(version, File.join(gendir, "#{service_name}Driver.rb"))
+      fix_import(version,
+          File.join(gendir, "#{service_name}MappingRegistry.rb"))
+      fix_import(version, File.join(gendir, "#{service_name}.rb"))
+
+      # Fix the comments in the file so that we get better-looking RDoc, and
+      # only for the things we want
+      fix_rdoc(File.join(gendir, "#{service_name}.rb"))
+
+      # Generate the wrapper files
+      eval("require '#{File.join(gendir, "#{service_name}Driver.rb")}'")
+      wrapper_file = File.join(gendir, "#{service_name}Wrapper.rb")
+      File.open(wrapper_file, 'w') do |file|
+        file.write(Generator.generate_wrapper_class(version, service))
+      end
+      logger.info("Generated #{version} #{service_name} " +
+          "wrapper: #{wrapper_file}")
+    end
+  end
+end
+
+# Fix "require" statements for client lib usage
+def fix_import(version, file)
+  tempfile = file + '.tmp'
+  outfile = File.new(tempfile, 'w')
+  File.open(file, 'r') do |infile|
+    infile.each do |line|
+      if (line =~ /require.*Service.*\.rb/)
+        outfile << line.gsub(/require '(.*)Service(.*)\.rb'/,
+            "require '#{$PRODDIR}/#{version.to_s}/\\1Service\\2'")
+      else
+        outfile << line
+      end
+    end
+  end
+  outfile.close
+  File.rename(tempfile, file)
+end
+
+# Fix RDoc comments in the generated *Service.rb files
+def fix_rdoc(file)
+  tempfile = file + '.tmp'
+  outfile = File.new(tempfile, 'w')
+  should_doc = true
+  File.open(file, 'r') do |infile|
+    infile.each do |line|
+      if (line =~ /# \{.*\}[A-Z]\w*/)
+        # This is a regular class. Document and clean up how it's displayed.
+        should_doc = true
+        outfile << line.gsub(/\{.*\}(.*)/, "\\1")
+      elsif (line =~ /# \{.*\}[a-z]\w*/)
+        # This is a method wrapping class. Do not document, but still clean up
+        # its comment.
+        should_doc = false
+        outfile << line.gsub(/\{.*\}(.*)/, "\\1")
+      elsif (line =~ /#   \w+/)
+        # Itemize member variables
+        outfile << line.gsub(/#   (.*)/, "# - \\1")
+      elsif (line =~ /class [A-Z].*/)
+        if should_doc
+          outfile << line
+        else
+          # Avoid documenting the method classes, since they're made invisible
+          # thanks to our service wrappers
+          outfile << line.gsub(/(.*)(\w)/, "\\1\\2 #:nodoc: all")
+        end
+      else
+        outfile << line
+      end
+    end
+  end
+  outfile.close
+  File.rename(tempfile, file)
+end
+
+# Create options to be used for class generation from WSDL
+def get_wsdl_opt(version, service_name)
+  optcmd= {}
+  optcmd['classdef'] = service_name
+  optcmd['force'] = true
+  optcmd['mapping_registry'] = true
+  optcmd['driver'] = nil
+
+  # Causes soap4r to wrap the classes it outputs into the given modules
+  optcmd['module_path'] = [$MODULE.name, version.to_s.capitalize, service_name]
+  return optcmd
+end
+
+# ====================================================================
+# Create a task to build the RDOC documentation tree.
+Rake::RDocTask.new("rdoc") do |rdoc|
+  # Try to use SDoc to generate the docs
+  begin
+    require 'sdoc'
+    rdoc.options << '--fmt' << 'shtml'
+    rdoc.template = 'direct'
+  rescue LoadError
+    # Do nothing, give up on SDoc and continue with whatever is the default.
+  end
+  rdoc.rdoc_dir = $DOCDIR
+  rdoc.title = "#{$PROJECT_NAME} -- Client library for the #{$API_NAME}"
+  rdoc.main = 'README'
+  rdoc.rdoc_files.include('README', 'COPYING', 'ChangeLog')
+  rdoc.rdoc_files.include("#{$LIBDIR}/*.rb", "#{$LIBDIR}/#{$PRODDIR}/*.rb")
+  rdoc.rdoc_files.include("#{$LIBDIR}/#{$PRODDIR}/v*/*Wrapper.rb")
+  rdoc.rdoc_files.include("#{$LIBDIR}/#{$PRODDIR}/v*/*Service.rb")
+  rdoc.rdoc_files.exclude("#{$LIBDIR}/#{$PRODDIR}/soap4rpatches.rb")
+end
+
+# ====================================================================
+# Create a task to perform the unit testing.
+Rake::TestTask.new("test") do |test|
+  test.libs << $TESTDIR
+  test.pattern = "#{$TESTDIR}/**/test_*.rb"
+  test.verbose = true
+end
+
+# ====================================================================
+# Create a task that will package the Rake software into distributable
+# gem files.
+
+# Utility method to create readable version ranges. May not cover a few edge
+# cases, but this is a best effort approach.
+def readable_version_range(version_string)
+  return '' if version_string.nil?
+
+  version_string = version_string.to_s.strip
+  pattern = /^(>|<|>=|<=|~>)(\s*)(\d[\d\.]*)$/
+  result = pattern.match(version_string)
+
+  return version_string unless result
+
+  case result[1]
+  when '>'
+    return 'greater than version ' + result[3]
+  when '<'
+    return 'lower than version ' + result[3]
+  when '>='
+    return 'version ' + result[3] + ' or later'
+  when '<='
+    return 'version ' + result[3] + ' or earlier'
+  when '~>'
+    version_pattern = /^(\d[\d\.]*)(\d)$/
+    version_result = version_pattern.match(result[3])
+    if version_result
+      return 'version ' + version_result[1] + 'x'
+    else
+      return version_string
+    end
+  else
+    return version_string
+  end
+end
+
+PKG_FILES = FileList[
+  '*.*',
+  'Rakefile',
+  "#{$LIBDIR}/**/*.rb",
+  "#{$LIBDIR}/#{$PRODDIR}/data/*.*",
+  'examples/**/*.rb',
+  "#{$DOCDIR}/**/*.*",
+  "#{$TESTDIR}/**/*.*"
+]
+
+PKG_FILES.exclude(/\._/)
+
+if ! defined?(Gem)
+  logger.fatal('Package Target requires RubyGems')
+else
+  spec = Gem::Specification.new do |s|
+
+    # Basic information
+    s.name = $GEM_NAME
+    s.version = $PKG_VERSION
+    s.summary = $GEM_SUMMARY
+    s.description = $GEM_DESCRIPTION
+
+    # Files and dependencies
+    dependencies = [['soap4r', '= 1.5.8'],
+                    ['httpclient', '>= 2.1.2'],
+                    ['google-ads-common', $ADS_COMMON_VERSION]]
+    dependencies += $EXTRA_DEPENDENCIES if $EXTRA_DEPENDENCIES
+    s.files = PKG_FILES.to_a
+    s.require_path = $LIBDIR
+    dependencies.each do |dep|
+      s.add_dependency(dep[0], dep[1])
+    end
+
+    # RDoc information
+    s.has_rdoc = true
+    s.extra_rdoc_files = ['README', 'COPYING', 'ChangeLog']
+    s.rdoc_options << '--main' << 'README'
+
+    # Metadata
+    s.authors = $GEM_AUTHORS
+    s.email = $GEM_EMAIL
+    s.homepage = $GEM_HOMEPAGE
+    s.rubyforge_project = $PROJECT_NAME
+    dependencies.each do |dep|
+      s.requirements << dep[0] + ' ' + readable_version_range(dep[1])
+    end
+  end
+
+  Rake::GemPackageTask.new(spec) do |t|
+    t.need_tar = true
+  end
+end