bing_ads_api 0.0.5

data/README.md

@@ -0,0 +1,57 @@
+Bing Ads Api Client
+=============
+
+Description
+-------------
+A simple ruby wrapper for the Bing Ads API based on the gem "google-ads-common".
+
+Usage
+-------------
+
+    # install in your gem file
+    gem 'bing_ads_api', :git => 'https://github.com/weboglobin/bing_ads_api.git'
+
+    # initialize the client
+    client = BingAdsApi::Api.new(
+            {
+              :authentication => {
+                :method => 'ClientLogin',
+                :developer_token => 'DEVELOPER_TOKEN',
+                :user_name => 'USERNAME',
+                :password => 'PASSWORD',
+                :customer_id => 'customer_id', # may be optional for some requests
+                :customer_account_id => 'customer_account_id' # may be optional for some requests
+              },
+              :service => {:environment => 'PRODUCTION'},
+              :library => {:log_level => 'DEBUG'}
+            })
+
+    # select the service and the API version (:v7 or :v8)
+    administration_service = client.service(:AdministrationService, :v7)
+
+    # send your request
+    result = administration_service.get_assigned_quota()
+
+    # select another service
+    campaign_service = client.service(:CampaignManagementService, :v7)
+
+    # send another request
+    result = campaign_service.get_campaigns_by_account_id({:account_id => 00000})
+
+    # create a campaign
+    result2 = campaign_service.add_campaigns({:account_id => 00000,
+                                            :campaigns => {:campaign => [{:budget_type => "DailyBudgetWithMaximumMonthlySpend",
+                                                                          :conversion_tracking_enabled => false,
+                                                                          :daily_budget => 5,
+                                                                          :daylight_saving => false,
+                                                                          :description => "A perfect new campaign",
+                                                                          :monthly_budget => 50,
+                                                                          :name => "perfectcampaign",
+                                                                          :time_zone => "BrusselsCopenhagenMadridParis"}]
+                                                          }
+                                            })
+
+About the gem
+-------------
+The tests still have to be written.
+Any help is welcome !

data/lib/ads_common_for_bing_ads.rb

@@ -0,0 +1,49 @@
+require 'ads_common/api'
+require 'ads_common/api_config'
+require 'ads_common/credential_handler'
+require 'ads_common/errors'
+require 'ads_common/http'
+require 'ads_common/savon_service'
+require 'ads_common/parameters_validator'
+require 'ads_common/build/savon_generator'
+require 'ads_common/build/savon_registry'
+require 'ads_common/savon_headers/base_header_handler'
+require 'ads_common/savon_headers/oauth_header_handler'
+require 'ads_common/savon_headers/httpi_request_proxy'
+
+####### AdsCommon Overriden for Bing Ads #########
+module AdsCommonForBingAds
+	class Api < AdsCommon::Api; end
+	module ApiConfig; include AdsCommon::ApiConfig; end
+	class Config < AdsCommon::Config; end
+	class CredentialHandler < AdsCommon::CredentialHandler; end
+	module Errors; include AdsCommon::Errors; end
+	class Http < AdsCommon::Http; end
+	class ParametersValidator < AdsCommon::ParametersValidator; end
+	class ResultsExtractor < AdsCommon::ResultsExtractor; end
+	class SavonService < AdsCommon::SavonService; end
+	module Utils; include AdsCommon::Utils; end
+	module ApiConfig; include AdsCommon::ApiConfig; end
+	# Auth
+	module Auth
+		class BaseHandler < AdsCommon::Auth::BaseHandler; end
+		class ClientLoginHandler < AdsCommon::Auth::ClientLoginHandler; end
+		class OAuth2Handler < AdsCommon::Auth::OAuth2Handler; end
+		class OAuthHandler < AdsCommon::Auth::OAuthHandler; end
+	end
+	# Build
+	module Build
+		class SavonAbstractGenerator < AdsCommon::Build::SavonAbstractGenerator; end
+		class SavonGenerator < AdsCommon::Build::SavonGenerator; end
+		class SavonRegistry < AdsCommon::Build::SavonRegistry; end
+		class SavonRegistryGenerator < AdsCommon::Build::SavonRegistryGenerator; end
+		class SavonServiceGenerator < AdsCommon::Build::SavonServiceGenerator; end
+	end
+	# SavonHeaders
+	module SavonHeaders
+		class BaseHeaderHandler < AdsCommon::SavonHeaders::BaseHeaderHandler; end
+		class OAuthHeaderHandler < AdsCommon::SavonHeaders::OAuthHeaderHandler; end
+		# httpi_request_proxy is ::OAuth::RequestProxy::HTTPIRequest < OAuth::RequestProxy::Base
+	end
+
+end

data/lib/ads_common_for_bing_ads/api_config.rb

@@ -0,0 +1,41 @@
+####### Overriden for Bing Ads #########
+AdsCommonForBingAds::ApiConfig.module_eval do
+  # Get the endpoint for a service on a given environment and API version.
+  #
+  # Args:
+  # - environment: the service environment to be used
+  # - version: the API version
+  # - service: the name of the API service
+  #
+  # Returns:
+  # The endpoint URL
+  #
+  def endpoint(environment, version, service)
+    if !address_config().nil?
+      address_config()[version][service][environment].to_s
+    else
+      ""
+    end
+  end
+  # Generates an array of WSDL URLs based on defined Services and version
+  # supplied. This method is used by generators to determine what service
+  # wrappers to generate.
+  #
+  # Args:
+  #   - version: the API version.
+  #
+  # Returns
+  #   hash of pairs Service => WSDL URL
+  #
+  def get_wsdls(version)
+    res = {}
+    services(version).each do |service|
+      if (!address_config().nil?)
+        path = address_config()[version][service][default_environment()].to_s
+      end
+      res[service.to_s] = path || ""
+    end
+    return res
+  end
+
+end

data/lib/ads_common_for_bing_ads/auth/client_login_handler.rb

@@ -0,0 +1,168 @@
+####### Overriden for Bing Ads #########
+
+AdsCommonForBingAds::Auth::ClientLoginHandler.class_eval do
+
+    #ACCOUNT_TYPE = 'GOOGLE'
+    #AUTH_PATH = '/accounts/ClientLogin'
+    #AUTH_PREFIX = 'GoogleLogin auth='
+    #CAPTCHA_PATH = '/accounts/'
+
+    # Initializes the ClientLoginHandler with all the necessary details.
+    def initialize(config, auth_server, service_name)
+      super(config)
+      @server = auth_server
+      @service_name = service_name
+    end
+
+    # Invalidates the stored token if the user_name, password or provided auth
+    # token have changed.
+    def property_changed(prop, value)
+      if [:user_name, :password].include?(prop)
+        @token = nil
+      end
+      if :auth_token.eql?(prop)
+        @token = create_token_from_string(value)
+      end
+    end
+
+    # Handle specific ClientLogin errors.
+    def handle_error(error)
+      # TODO: Add support for automatically regenerating auth tokens when they
+      # expire.
+      get_logger().error(error)
+      raise error
+    end
+
+    # Returns authorization string.
+    def auth_string(credentials, request)
+      return [AUTH_PREFIX, get_token(credentials)].join
+    end
+
+    private
+
+    # Auxiliary method to validate the credentials for token generation.
+    #
+    # Args:
+    # - credentials: a hash with the credentials for the account being
+    #   accessed
+    #
+    # Raises:
+    # - AdsCommonForBingAds::Errors::AuthError if validation fails
+    #
+    def validate_credentials(credentials)
+      if credentials.nil?
+        raise AdsCommonForBingAds::Errors::AuthError, 'No credentials supplied.'
+      end
+
+      if credentials[:auth_token].nil?
+        if credentials[:user_name].nil?
+          raise AdsCommonForBingAds::Errors::AuthError,
+              'UserName address not included in credentials.'
+        end
+        if credentials[:password].nil?
+          raise AdsCommonForBingAds::Errors::AuthError,
+              'Password not included in credentials.'
+        end
+      else
+        if credentials[:user_name] and credentials[:password]
+          get_logger().warn('Both auth_token and login credentials present' +
+              ', preferring auth_token.')
+        end
+      end
+    end
+
+    # Auxiliary method to generate an authentication token for login in via
+    # the ClientLogin API.
+    #
+    # Args:
+    # - credentials: a hash with the credentials for the account being
+    #   accessed
+    #
+    # Returns:
+    # - The auth token for the account
+    #
+    # Raises:
+    # - AdsCommonForBingAds::Errors::AuthError if authentication fails
+    #
+    def create_token(credentials)
+      token = credentials.include?(:auth_token) ?
+          create_token_from_string(credentials[:auth_token]) :
+          generate_token(credentials)
+      return token
+    end
+
+    # Creates token for provided auth string. Trivial for this handler.
+    def create_token_from_string(token_string)
+      return token_string
+    end
+
+    # Prepares POST data for ClientLogin request.
+    def get_login_data(credentials)
+      user_name = CGI.escape(credentials[:user_name])
+      password = CGI.escape(credentials[:password])
+      service_name = @service_name
+      data = "accountType=%s&Email=%s&Passwd=%s&service=%s" %
+          [ACCOUNT_TYPE, user_name, password, service_name]
+      if credentials[:logintoken] and credentials[:logincaptcha]
+        data += "&logintoken=%s&logincaptcha=%s" %
+          [CGI.escape(credentials[:logintoken]),
+           CGI.escape(credentials[:logincaptcha])]
+      end
+      return data
+    end
+
+    # Generates new client login token based on credentials.
+    def generate_token(credentials)
+      validate_credentials(credentials)
+
+      url = @server + AUTH_PATH
+      data = get_login_data(credentials)
+      headers = {'Content-Type' => 'application/x-www-form-urlencoded'}
+
+      response = AdsCommonForBingAds::Http.post_response(url, data, @config, headers)
+      results = parse_token_text(response.body)
+
+      if response.code == 200 and results.include?('Auth')
+        return results['Auth']
+      else
+        handle_login_error(credentials, response, results)
+      end
+    end
+
+    # Raises relevant error based on response and parsed results.
+    def handle_login_error(credentials, response, results)
+      # Handling for known errors.
+      if 'CaptchaRequired'.eql?(results['Error'])
+        captcha_url = @server + CAPTCHA_PATH + results['CaptchaUrl']
+        raise AdsCommonForBingAds::Errors::CaptchaRequiredError.new(results['Error'],
+            results['CaptchaToken'], captcha_url, results['Url'])
+      end
+      # For other errors throwing a generic error.
+      error_message = "ClientLogin failed for user_name '%s': HTTP code %d." %
+          [credentials[:user_name], response.code]
+      error_str = results['Error'] || response.body
+      error_message += " Error: %s." % error_str if error_str
+      if results.include?('Info')
+        error_message += " Info: %s." % results['Info']
+      end
+      raise AdsCommonForBingAds::Errors::AuthError.new(error_message, error_str,
+          results['Info'])
+    end
+
+    # Extracts key-value pairs from ClientLogin server response.
+    #
+    # Args:
+    # - text: server response string
+    #
+    # Returns:
+    #   Hash of key-value pairs
+    #
+    def parse_token_text(text)
+      return text.split("\n").inject({}) do |result, line|
+        key, *values = line.split('=')
+        result[key] = values.join('=')
+        result
+      end
+    end
+
+end

data/lib/ads_common_for_bing_ads/build/savon_registry.rb

@@ -0,0 +1,15 @@
+
+class AdsCommonForBingAds::Build::SavonRegistry
+
+  # Extracts input parameters of given method as an array.
+  def extract_input_parameters(op_node, doc)
+    input_element = REXML::XPath.first(op_node, 'descendant::wsdl:input')
+    input_name = get_element_name(input_element)
+    input_fields = find_sequence_fields(input_name, doc)
+    return {:name => input_name.snakecase, :fields => input_fields}
+  end
+
+
+
+
+end

data/lib/ads_common_for_bing_ads/parameters_validator.rb

@@ -0,0 +1,36 @@
+
+AdsCommonForBingAds::ParametersValidator.class_eval do
+
+  # Validates input parameters to:
+  # - add parameter names;
+  # - resolve xsi:type where required;
+  # - convert some native types to XML.
+  def validate_args(action_name, args)
+    in_params = @registry.get_method_signature(action_name)[:input] # Hash like {:name=>"get_accounts_info_request", :fields=>[]}
+    # TODO: compare number of parameters.
+    args_hash = args#{in_params[:name] => deep_copy(args)}
+    #validate_arguments(args_hash, in_params)
+    return args_hash
+  end
+
+  private
+
+   # Validates given arguments based on provided fields list.
+    def validate_arguments(args_hash, fields_list, type_ns = nil)
+      check_extra_fields(args_hash, array_from_named_list(fields_list))
+      add_order_key(args_hash, fields_list)
+      fields_list.each do |field|
+        key = field[:name]
+        item = args_hash[key]
+        check_required_argument_present(item, field)
+        if item
+          item_type = get_full_type_signature(field[:type])
+          item_ns = field[:ns] || type_ns
+          key = handle_namespace_override(args_hash, key, item_ns) if item_ns
+          validate_arg(item, args_hash, key, item_type)
+        end
+      end
+      return args_hash
+    end
+
+end

data/lib/ads_common_for_bing_ads/savon_headers_base_header_handler.rb

@@ -0,0 +1,9 @@
+
+class AdsCommonForBingAds::SavonHeaders::BaseHeaderHandler
+
+  # Generates SOAP headers with the default request header element.
+  def generate_headers(request, soap)
+    soap.header.merge!(generate_request_header())
+  end
+
+end

data/lib/ads_common_for_bing_ads/savon_service.rb

@@ -0,0 +1,141 @@
+####### Overriden for Bing Ads #########
+
+class AdsCommonForBingAds::SavonService < AdsCommon::SavonService
+
+  private
+
+  # [CHANGES: 
+  # => ParametersValidator to AdsCommonForBingAds::ParametersValidator
+  # => ResultsExtractor    to AdsCommon::ResultsExtractor]
+  # Executes SOAP action specified as a string with given arguments.
+    def execute_action(action_name, args, &block)
+      registry = get_service_registry()
+      validator = AdsCommonForBingAds::ParametersValidator.new(registry)
+      args = validator.validate_args(action_name, args)
+      response = execute_soap_request(
+          action_name.to_sym, args, validator.extra_namespaces)
+      log_headers(response.http.headers)
+      handle_errors(response)
+      extractor = AdsCommon::ResultsExtractor.new(registry)
+      result = extractor.extract_result(response, action_name, &block)
+      run_user_block(extractor, response, result, &block) if block_given?
+      return result
+    end
+
+  # Adds namespace to the given string.
+  #
+  # Args:
+  #  - str: String to prepend with a namespace
+  #
+  # Returns:
+  #  - String with a namespace
+  #
+  def prepend_namespace(str, namespace = AdsCommonForBingAds::SavonHeaders::BaseHeaderHandler::DEFAULT_NAMESPACE)
+    return "%s:%s" % [namespace, str]
+  end
+
+  # Executes the SOAP request with original SOAP name.
+  def execute_soap_request(action, args, extra_namespaces)
+    ns = AdsCommonForBingAds::SavonHeaders::BaseHeaderHandler::DEFAULT_NAMESPACE
+    original_input_name = get_service_registry.get_method_signature(action)[:input][:name].to_s.camelize
+    original_action_name = get_service_registry.get_method_signature(action)[:original_name].to_s.camelize
+    original_action_name = action if original_action_name.nil?
+    args = args.first if args.is_a?(Array)
+    additional_headers = args.delete(:headers) unless args.nil?
+    prepend_namespace_to_hash(args, ns)
+    prepend_namespace_to_hash(additional_headers, ns)
+    puts "**************************************args = #{args}"
+    response = @client.request(ns, original_input_name) do |soap|
+      @client.http.headers["SOAPAction"] = original_action_name
+      soap.body = args
+      set_headers(soap, extra_namespaces)
+      soap.header.merge!(additional_headers) if additional_headers.is_a?(Hash)
+    end
+    return response
+  end
+  def prepend_namespace_to_hash h, namespace
+    if h.is_a?(Hash)
+      h.dup.each do |k,v|
+        h.delete(k)
+        if k.to_s=~/!$/ || k.to_s=~/:/ #on ne transforme pas les noms finissant par ! ou contenant : (exemple: attributes! ou xsi:type)
+          h[k] = prepend_namespace_to_hash(v, namespace)
+        else
+          h[k.to_s=~ /^#{namespace}:/ ? k : prepend_namespace(k.to_s.camelize, namespace)] = prepend_namespace_to_hash(v, namespace)
+        end
+      end
+    elsif h.is_a?(Array) # e.g: h = {:campaigns => {:campaign => [{:name => 'foo'}, {:name => 'foofoo'}]}}
+      h.map!{|e| prepend_namespace_to_hash(e, namespace)}
+    end
+    return h
+  end
+
+  # Creates and sets up Savon client.
+  def create_savon_client(endpoint, namespace)
+    Nori.advanced_typecasting = false
+    client = Savon::Client.new do |wsdl, httpi|
+      wsdl.endpoint = endpoint
+      wsdl.namespace = namespace
+      wsdl.element_form_default = :qualified
+      AdsCommonForBingAds::Http.configure_httpi(@config, httpi)
+    end
+    client.config.raise_errors = false
+    client.config.logger.subject = get_logger()
+    return client
+  end
+
+  # Finds an exception object for a given response.
+  def exception_for_soap_fault(response)
+    begin
+      fault = response[:fault]
+      if fault[:detail] and fault[:detail][:api_exception_fault]
+        exception_fault = fault[:detail][:api_exception_fault]
+        exception_name = exception_fault[:application_exception_type]
+        exception_class = get_module().const_get(exception_name)
+        return exception_class.new(exception_fault)
+      # Specific to Bing Ads
+      elsif fault[:detail] and fault[:detail][:api_fault]
+        operation_error = fault[:detail][:api_fault][:operation_errors][:operation_error]
+        operation_error = operation_error.first if operation_error.is_a?(Array) # if we get several errors, we only raise the first one
+        if exception_name = BingAdsApi::Errors::CODES[operation_error[:code]]
+          exception_class = BingAdsApi::Errors.const_get(exception_name)
+        else
+          raise Exception.new("code #{operation_error[:code]}")
+        end
+        return exception_class.new("#{operation_error[:message]} (#{operation_error[:details]})")
+      # Specific to Bing Ads (batches)
+      elsif fault[:detail] and fault[:detail][:api_fault_detail]
+        operation_error = fault[:detail][:api_fault_detail][:batch_errors][:batch_error]
+        operation_error = operation_error.first if operation_error.is_a?(Array) # if we get several errors, we only raise the first one
+        if exception_name = BingAdsApi::Errors::CODES[operation_error[:code]]
+          exception_class = BingAdsApi::Errors.const_get(exception_name)
+        else
+          raise Exception.new("code #{operation_error[:code]}")
+        end
+        return exception_class.new("#{operation_error[:message]} (#{operation_error[:details]})")
+      # Specific to Bing Ads (ad api)
+      elsif fault[:detail] and fault[:detail][:ad_api_fault_detail]
+        operation_error = fault[:detail][:ad_api_fault_detail][:errors][:ad_api_error]
+        operation_error = operation_error.first if operation_error.is_a?(Array) # if we get several errors, we only raise the first one
+        if exception_name = BingAdsApi::Errors::CODES[operation_error[:code]]
+          exception_class = BingAdsApi::Errors.const_get(exception_name)
+        else
+          raise Exception.new("code #{operation_error[:code]}")
+        end
+        return exception_class.new("#{operation_error[:message]} (#{operation_error[:details]})")
+      elsif fault[:faultstring]
+        fault_message = fault[:faultstring]
+        return AdsCommonForBingAds::Errors::ApiException.new(
+            "Unknown exception with error: %s" % fault_message)
+      else
+        raise ArgumentError.new(fault.to_s)
+      end
+    rescue Exception => e
+      operation_error ||= response[:fault][:detail][:api_fault][:operation_errors][:operation_error] rescue {}
+      return AdsCommonForBingAds::Errors::ApiException.new(
+          "Failed to resolve exception (%s), details: %s, SOAP fault: %s" %
+          [e.message, "#{operation_error[:message]} (#{operation_error[:details]})", response.soap_fault])
+    end
+  end
+
+
+end