google-adwords-api 0.2.0 → 0.2.1

data/ChangeLog

@@ -1,3 +1,7 @@
+0.2.1:
+  - Changes for future OAuth support.
+  - Require google-ads-common 0.5.0 or later from now on.
+
 0.2.0:
   - Better support for UTF reports in download extensions.
   - Require google-ads-common 0.4.0 or later from now on.

data/README

@@ -30,7 +30,7 @@ which is installed automatically as a dependency.
 The following gem libraries are required:
 - soap4r v1.5.8
 - httpclient v2.1.2 or greater
-- google-ads-common v0.4.0 or later.
+- google-ads-common v0.5.0 or later.
 
 
 == 2 - Using the client library:

data/Rakefile

@@ -25,10 +25,10 @@ $:.unshift File.join(File.dirname(__FILE__), 'lib')
 
 require 'rubygems'
 gem 'google-ads-common'
-require 'ads_common/build/soap4r_generator'
 require 'ads_common/config'
 require 'adwords_api/api_config'
 require 'adwords_api/extensions'
+require 'adwords_api/soap4r/soap4r_generator'
 
 # Configure some constants and built-in tasks
 $PROJECT_NAME = 'adwords_api'
@@ -36,7 +36,7 @@ $GEM_NAME = 'google-adwords-api'
 $API_NAME = 'AdWords API'
 $CURRENT_VERSION = AdwordsApi::ApiConfig::CLIENT_LIB_VERSION
 $PRODDIR = 'adwords_api'
-$ADS_COMMON_VERSION = '~> 0.4.0'
+$ADS_COMMON_VERSION = '~> 0.5.0'
 
 # Configure module / namespace
 $MODULE = AdwordsApi
@@ -63,7 +63,7 @@ $GEM_HOMEPAGE = 'http://code.google.com/p/google-api-ads-ruby/'
 module Generator
 
   class << Generator
-    include AdsCommon::Build::Soap4rGenerator
+    include AdwordsApi::Soap4r::Soap4rGenerator
   end
 
   def self.api_config
@@ -114,4 +114,4 @@ end
 
 
 # Import tasks in common file
-require 'ads_common/build/rake_common'
+require 'adwords_api/soap4r/rake_common'

data/adwords_api.yml

@@ -2,17 +2,34 @@
 # This is an example configuration file for the AdWords API client library.
 # Please fill in the required fields, and copy it over to your home directory.
 :authentication:
+  # Authentication method, methods currently supported: OAuth, ClientLogin.
   :method: ClientLogin
-  :developer_token: INSERT_YOUR_DEVELOPER_TOKEN_HERE
-  :user_agent: INSERT_YOUR_USER_AGENT_HERE
+
+  # Auth parameters for OAuth method.
+  # Set the OAuth consumer key and secret. Anonymous values can be used for
+  # testing, and real values can be obtained by registering your application:
+  # http://code.google.com/apis/accounts/docs/RegistrationForWebAppsAuto.html
+  #:oauth_consumer_key: anonymous
+  #:oauth_consumer_secret: anonymous
+  # If you manage or store access token manually, you can specify it here.
+  #:oauth_token: INSERT_OAUTH_TOKEN_HERE
+  # If you need to change signature method, specify it here.
+  #:oauth_signature_method: HMAC-SHA1
+  # Token secret for HMAC-SHA1 method.
+  #:oauth_token_secret: INSERT_OAUTH_TOKEN_SECRET_HERE
+
+  # Auth parameters for ClientLogin method.
   :password: INSERT_YOUR_PASSWORD_HERE
   :email: INSERT_YOUR_LOGIN_EMAIL_HERE
-  :client_email: INSERT_YOUR_CLIENT_EMAIL_HERE
-  # If you would like to manage your auth tokens manually, use the 'auth_token'
-  # property.
+  # To manage your auth tokens manually, use the 'auth_token' property.
   #:auth_token: INSERT_AUTH_TOKEN_HERE
+
+  # Other parameters.
+  :developer_token: INSERT_YOUR_DEVELOPER_TOKEN_HERE
+  :client_email: INSERT_YOUR_CLIENT_EMAIL_HERE
+  :user_agent: INSERT_YOUR_USER_AGENT_HERE
 :service:
-  :environment: Production
+  :environment: SANDBOX
 :connection:
   :strict_ssl_verification: false
   # If your proxy connection requires authentication, make sure to include it in

data/examples/v201101/handle_second_factor.rb

@@ -0,0 +1,96 @@
+#!/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 illustrates how to handle 2 factor authorization errors.
+
+require 'rubygems'
+gem 'google-adwords-api'
+require 'adwords_api'
+
+API_VERSION = :v201101
+
+def handle_second_factor()
+  # Set up credentials with an account that has 2Factor enabled.
+  config = {
+      :authentication => {
+          :method => 'ClientLogin',
+          :email => '2steptester@gmail.com',
+          :password => 'testaccount',
+          :user_agent => 'Ruby 2 Factor Sample'
+      },
+      :service => {
+          :environment => 'PRODUCTION'
+      }
+  }
+  adwords = AdwordsApi::Api.new(config)
+
+  # 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')
+
+  begin
+    # Forcing library to request authorization token.
+    auth_token = adwords.authorize()
+    puts 'Successfully retrieved the token.'
+
+  # Second factor error is one of AuthErrors.
+  rescue AdsCommon::Errors::AuthError => e
+    puts "Authorization failed with message:"
+    puts "\t%s" % e.message
+    # Checking 'Info' field for particular auth error type.
+    if e.info and e.info.casecmp('InvalidSecondFactor') == 0
+      puts "The user has enabled two factor authentication in this account." +
+      " Please use OAuth authentication method or have the user generate an" +
+      " application-specific password to make calls against the AdWords" +
+      " API. See \n" +
+      "    http://adwordsapi.blogspot.com/2011/02/authentication-changes-with" +
+      "-2-step.html\n" +
+      "for more details."
+    end
+  end
+end
+
+if __FILE__ == $0
+  begin
+    handle_second_factor()
+
+  # 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/oauth_handling.rb

@@ -0,0 +1,104 @@
+#!/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 illustrates how to use OAuth authentication method.
+#
+# Tags: CampaignService.get
+
+require 'rubygems'
+gem 'google-adwords-api'
+require 'adwords_api'
+
+API_VERSION = :v201101
+MAX_RETRIES = 3
+
+def oauth_handling()
+  # 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')
+
+  campaign_srv = adwords.service(:CampaignService, API_VERSION)
+
+  # Get all the campaigns for this account; empty selector.
+  selector = {
+    :fields => ['Id', 'Name', 'Status'],
+    :ordering => [{:field => 'Name', :sort_order => 'ASCENDING'}]
+  }
+
+  retry_count = 0
+
+  begin
+    response = campaign_srv.get(selector)
+  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
+
+  if response and response[:entries]
+    campaigns = response[:entries]
+    campaigns.each do |campaign|
+      puts "Campaign name is \"#{campaign[:name]}\", id is #{campaign[:id]} " +
+          "and status is \"#{campaign[:status]}\"."
+    end
+  else
+    puts "No campaigns were found."
+  end
+end
+
+if __FILE__ == $0
+  begin
+    oauth_handling()
+
+  # 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/lib/adwords_api.rb

@@ -22,22 +22,21 @@
 
 require 'rubygems'
 gem 'soap4r', '=1.5.8'
-gem 'google-ads-common', '~>0.4.0'
+gem 'google-ads-common', '~>0.5.0'
 require 'thread'
 require 'uri'
-require 'ads_common/soap4r_patches'
 require 'ads_common/api'
-require 'ads_common/config'
 require 'ads_common/auth/client_login_handler'
-require 'ads_common/soap4r_headers/nested_header_handler'
-require 'ads_common/soap4r_headers/single_header_handler'
-require 'ads_common/soap4r_logger'
 require 'adwords_api/auth/v13_login_handler'
 require 'adwords_api/errors'
 require 'adwords_api/api_config'
 require 'adwords_api/extensions'
-require 'adwords_api/soap4r_response_handler'
 require 'adwords_api/credential_handler'
+require 'adwords_api/nested_header_handler'
+require 'adwords_api/single_header_handler'
+require 'adwords_api/soap4r/soap4r_logger'
+require 'adwords_api/soap4r/soap4r_patches'
+require 'adwords_api/soap4r/soap4r_response_handler'
 require 'adwords_api/utils'
 
 # Main namespace for all the client library's modules and classes.
@@ -55,11 +54,6 @@ module AdwordsApi
     # Number of units spent in total, via this API object
     attr_accessor :total_units
 
-    # Accessor for client login handler, so that we can access the token.
-    attr_accessor :client_login_handler
-
-    public
-
     # Getter for the API service configurations
     def api_config
       AdwordsApi::ApiConfig
@@ -68,7 +62,7 @@ module AdwordsApi
     # Auxiliary method to create a new Soap4rResponseHandler, of the type we
     # want to use for AdWords logging
     def create_callback_handler
-      AdwordsApi::Soap4rResponseHandler.new(self)
+      AdwordsApi::Soap4r::Soap4rResponseHandler.new(self)
     end
 
     # Retrieve single NestedHeaderHandler for v20xx and one SingleHeaderHandler
@@ -79,27 +73,33 @@ module AdwordsApi
     #   handle authentication
     # - header_list: the list of headers to be handled
     # - version: intended API version
-    # - wrapper: wrapper object for the service being handled
+    # - namespace: namespace to use as default for body
     #
     # Returns:
     # - a list of SOAP header handlers; one per provided header
     #
-    def soap_header_handlers(auth_handler, header_list, version, wrapper)
+    def soap_header_handlers(auth_handler, header_list, version, namespace)
       if version == :v13
-        header_handlers = []
-        header_list.each do |header|
-          header_handlers << AdsCommon::Soap4rHeaders::SingleHeaderHandler.new(
-              @credential_handler, auth_handler, header, nil, version)
+        header_handlers = header_list.map do |header|
+          AdwordsApi::SingleHeaderHandler.new(@credential_handler, auth_handler,
+              header, nil, version)
         end
         return header_handlers
       else
-        ns =
-            api_config.headers_config[:HEADER_NAMESPACE_PREAMBLE] + version.to_s
-        top_ns = wrapper.namespace
-        return [AdsCommon::Soap4rHeaders::NestedHeaderHandler.new(
-            @credential_handler, auth_handler,
-            api_config.headers_config[:REQUEST_HEADER],
-            top_ns, ns, version)]
+        auth_method = @config.read('authentication.method',
+            'ClientLogin').to_s.upcase.to_sym
+        handlers = case auth_method
+          when :CLIENTLOGIN
+            ns = api_config.headers_config[:HEADER_NAMESPACE_PREAMBLE] +
+                version.to_s
+            [AdwordsApi::NestedHeaderHandler.new(@credential_handler,
+                auth_handler, api_config.headers_config[:REQUEST_HEADER],
+                namespace, ns, version)]
+          when :OAUTH
+            raise NotImplementedError, 'OAuth authentication method is not ' +
+                'supported for Soap4r backend.'
+        end
+        return handlers
       end
     end
 
@@ -107,12 +107,34 @@ module AdwordsApi
     def initialize(provided_config = nil)
       super(provided_config)
       @credential_handler = AdwordsApi::CredentialHandler.new(@config)
-      @drivers = Hash.new
+      @drivers = {}
       @total_units = 0
       @last_units = 0
       @mutex = Mutex.new
     end
 
+    # Accessor for client login handler, so that we can access the token.
+    # This is a temporary solution for v13 and for v2009+ until full OAuth
+    # 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
+        environment = @config.read('service.environment')
+        if auth_method == :CLIENTLOGIN
+          # We use client login, so we can reuse general AuthHandler.
+          @client_login_handler = get_auth_handler(environment, nil)
+        else
+          # We are using OAuth or something else and need to generate a handler.
+          auth_server = api_config.auth_server(environment)
+          @client_login_handler = AdsCommon::Auth::ClientLoginHandler.new(
+              @config, auth_server,
+              api_config.headers_config[:LOGIN_SERVICE_NAME])
+        end
+      end
+      return @client_login_handler
+    end
+
     # Helper method to provide a simple way of doing an MCC-level operation
     # without the need to change credentials. Executes a block of code as an
     # MCC-level operation and/or returns the current status of the property.
@@ -219,28 +241,29 @@ module AdwordsApi
 
     private
 
+    # Overrides AdsCommon::Api.get_auth_handler to allow version-specific
+    # handlers.
+    def get_auth_handler(environment, version = nil)
+      if @auth_handler.nil?
+        @auth_handler = create_auth_handler(environment, version)
+      end
+      return @auth_handler
+    end
+
     # Creates an appropriate authentication handler for each service (reuses the
     # ClientLogin one to avoid generating multiple tokens unnecessarily).
     #
     # Args:
-    # - version: intended API version
     # - environment: the current working environment (production, sandbox, etc.)
+    # - version: intended API version
     #
     # Returns:
     # - auth handler
     #
-    def create_auth_handler(environment, version)
-      if version == :v13
-        return AdwordsApi::Auth::V13LoginHandler.new
-      else
-        if @client_login_handler.nil?
-          auth_server = api_config.auth_server(environment)
-          @client_login_handler =
-              AdsCommon::Auth::ClientLoginHandler.new(config, auth_server,
-                  api_config.headers_config[:LOGIN_SERVICE_NAME])
-        end
-        return @client_login_handler
-      end
+    def create_auth_handler(environment, version = nil)
+      return (version == :v13) ?
+          AdwordsApi::Auth::V13LoginHandler.new :
+          super(environment)
     end
 
     # Handle loading of a single service.
@@ -271,12 +294,12 @@ module AdwordsApi
       wrapper_class = api_config.wrapper_name(version, service)
       wrapper = eval("#{wrapper_class}.new(driver, self)")
 
-      auth_handler = create_auth_handler(environment, version)
+      auth_handler = get_auth_handler(environment, version)
       header_list =
           auth_handler.header_list(@credential_handler.credentials(version))
 
       soap_handlers = soap_header_handlers(auth_handler, header_list, version,
-          wrapper)
+          wrapper.namespace)
 
       soap_handlers.each do |handler|
         driver.headerhandler << handler
@@ -285,7 +308,8 @@ module AdwordsApi
       # Add response handler to this driver for API unit usage processing.
       driver.callbackhandler = create_callback_handler
       # Plug the wiredump to our XML logger.
-      driver.wiredump_dev = AdsCommon::Soap4rLogger.new(@logger, Logger::DEBUG)
+      driver.wiredump_dev =
+          AdwordsApi::Soap4r::Soap4rLogger.new(@logger, Logger::DEBUG)
       driver.options['protocol.http.ssl_config.verify_mode'] = nil
       proxy = config.read('connection.proxy')
       driver.options['protocol.http.proxy'] = proxy if proxy