bing_ads_api 0.0.5

data/lib/bing_ads_api.rb

@@ -0,0 +1,175 @@
+require 'savon'
+require 'httpi'
+require 'active_support/inflector'
+
+require 'ads_common_for_bing_ads'
+require 'ads_common_for_bing_ads/api_config'
+require 'ads_common_for_bing_ads/parameters_validator'
+require 'ads_common_for_bing_ads/auth/client_login_handler'
+require 'ads_common_for_bing_ads/savon_service'
+require 'ads_common_for_bing_ads/savon_headers_base_header_handler'
+require 'bing_ads_api/api_config'
+require 'bing_ads_api/client_login_header_handler'
+require 'bing_ads_api/credential_handler'
+require 'bing_ads_api/errors'
+require 'bing_ads_api/report_utils'
+
+module BingAdsApi
+
+  # Wrapper class that serves as the main point of access for all the API usage.
+  #
+  # Holds all the services, as well as login credentials.
+  #
+  class Api < AdsCommonForBingAds::Api
+
+    # Constructor for API.
+    def initialize(provided_config = nil)
+      super(provided_config)
+      @credential_handler = BingAdsApi::CredentialHandler.new(@config)
+    end
+
+    # Getter for the API service configurations
+    def api_config()
+      BingAdsApi::ApiConfig
+    end
+
+    # Retrieve correct soap_header_handler.
+    #
+    # Args:
+    # - auth_handler: instance of an AdsCommonForBingAds::Auth::BaseHandler subclass to
+    #   handle authentication
+    # - version: intended API version
+    # - header_ns: header namespace
+    # - default_ns: default namespace
+    #
+    # Returns:
+    # - SOAP header handler
+    #
+    def soap_header_handler(auth_handler, version, header_ns, default_ns)
+      auth_method = @config.read('authentication.method', :CLIENTLOGIN)
+      handler_class = case auth_method
+                      when :CLIENTLOGIN then BingAdsApi::ClientLoginHeaderHandler
+                      when :OAUTH, :OAUTH2 then AdsCommonForBingAds::SavonHeaders::OAuthHeaderHandler
+                      end
+      return handler_class.new(@credential_handler, auth_handler, header_ns, default_ns, version)
+    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.
+    #
+    # Args:
+    # - accepts a block, which it will execute as an MCC-level operation
+    #
+    # Returns:
+    # - block execution result, if block given
+    # - boolean indicating whether MCC-level operations are currently
+    #   enabled or disabled, if no block provided
+    #
+    def use_mcc(&block)
+      return (block_given?) ?
+        run_with_temporary_flag(:@use_mcc, true, block) :
+        @credential_handler.use_mcc
+    end
+
+    # Helper method to provide a simple way of doing an MCC-level operation
+    # without the need to change credentials. Sets the value of the property
+    # that controls whether MCC-level operations are enabled or disabled.
+    #
+    # Args:
+    # - value: the new value for the property (boolean)
+    #
+    def use_mcc=(value)
+      @credential_handler.use_mcc = value
+    end
+
+    # Helper method to provide a simple way of doing a validate-only operation
+    # without the need to change credentials. Executes a block of code as an
+    # validate-only operation and/or returns the current status of the property.
+    #
+    # Args:
+    # - accepts a block, which it will execute as a validate-only operation
+    #
+    # Returns:
+    # - block execution result, if block given
+    # - boolean indicating whether validate-only operations are currently
+    #   enabled or disabled, if no block provided
+    #
+    def validate_only(&block)
+      return (block_given?) ?
+        run_with_temporary_flag(:@validate_only, true, block) :
+        @credential_handler.validate_only
+    end
+
+    # Helper method to provide a simple way of performing validate-only
+    # operations. Sets the value of the property
+    # that controls whether validate-only operations are enabled or disabled.
+    #
+    # Args:
+    # - value: the new value for the property (boolean)
+    #
+    def validate_only=(value)
+      @credential_handler.validate_only = value
+    end
+
+    # Helper method to provide a simple way of performing requests with support
+    # for partial failures. Executes a block of code with partial failures
+    # enabled and/or returns the current status of the property.
+    #
+    # Args:
+    # - accepts a block, which it will execute as a partial failure operation
+    #
+    # Returns:
+    # - block execution result, if block given
+    # - boolean indicating whether partial failure operations are currently
+    # enabled or disabled, if no block provided
+    #
+    def partial_failure(&block)
+      return (block_given?) ?
+        run_with_temporary_flag(:@partial_failure, true, block) :
+        @credential_handler.partial_failure
+    end
+
+    # Helper method to provide a simple way of performing requests with support
+    # for partial failures.
+    #
+    # Args:
+    # - value: the new value for the property (boolean)
+    #
+    def partial_failure=(value)
+      @credential_handler.partial_failure = value
+    end
+
+    # Returns an instance of ReportUtils object with all utilities relevant to
+    # the reporting.
+    #
+    # Args:
+    # - version: version of the API to use (optional).
+    #
+    def report_utils(version = nil)
+      version = api_config.default_version if version.nil?
+      # Check if version exists.
+      if !api_config.versions.include?(version)
+        raise AdsCommonForBingAds::Errors::Error, "Unknown version '%s'" % version
+      end
+      return BingAdsApi::ReportUtils.new(self, version)
+    end
+
+    private
+
+    # Executes block with a temporary flag set to a given value. Returns block
+    # result.
+    def run_with_temporary_flag(flag_name, flag_value, block)
+      previous = @credential_handler.instance_variable_get(flag_name)
+      @credential_handler.instance_variable_set(flag_name, flag_value)
+      begin
+        return block.call
+      ensure
+        @credential_handler.instance_variable_set(flag_name, previous)
+      end
+    end
+
+  end
+
+
+end

data/lib/bing_ads_api/api_config.rb

@@ -0,0 +1,162 @@
+# encoding: utf-8
+# Helper methods for loading and managing the available services in the Bing Ads API.
+
+require 'bing_ads_api/version'
+
+module BingAdsApi
+
+  # Contains helper methods for loading and managing the available services.
+  module ApiConfig
+
+    # Inherit from AdsCommonForBingAds::ApiConfig
+    class << ApiConfig
+      include AdsCommonForBingAds::ApiConfig
+    end
+
+    # Set defaults
+    DEFAULT_VERSION = :v8
+    DEFAULT_ENVIRONMENT = :PRODUCTION
+    LATEST_VERSION = :v8
+
+    # Set other constants
+    API_NAME = 'BingAdsApi'
+    DEFAULT_CONFIG_FILENAME = 'bing_ads_api.yml'
+
+    # Configure the services available to each version
+    @@service_config = {
+      :v7 => [
+          :AdministrationService,
+          :CampaignManagementService,
+          :CustomerBillingService,
+          :CustomerManagementService,
+          :NotificationService,
+          :ReportingService
+            ],
+      :v8 => [
+          :AdIntelligenceService,
+          :AdministrationService,
+          :BulkService,
+          :CampaignManagementService,
+          :CustomerBillingService,
+          :CustomerManagementService,
+          :NotificationService,
+          :OptimizerService,
+          :ReportingService
+      ]
+    }
+
+    # Configure the different environments, with the base URL for each one
+    @@environment_config = {
+      :PRODUCTION => {
+        :oauth_scope => '',
+        :header_ns => 'https://adcenter.microsoft.com/api/adcenter/',
+        :v7 => '',
+        :v8 => ''
+      },
+      :SANDBOX => {
+        :oauth_scope => '',
+        :header_ns => 'https://adcenter.microsoft.com/api/adcenter/',
+        :v7 => '',
+        :v8 => ''
+      }
+    }
+
+    # Configure the subdirectories for each version / service pair.
+    # A missing pair means that only the base URL is used.
+    @@subdir_config = {}
+
+    @@address_config = {
+      :v8 => {
+        :AdIntelligenceService     => {:PRODUCTION => "https://adcenterapi.microsoft.com/Api/Advertiser/v8/CampaignManagement/AdIntelligenceService.svc?wsdl", :SANDBOX => ""},
+        :AdministrationService     => {:PRODUCTION => "https://adcenterapi.microsoft.com/Api/Advertiser/v8/Administration/AdministrationService.svc?wsdl",     :SANDBOX => ""},
+        :BulkService               => {:PRODUCTION => "https://adcenterapi.microsoft.com/Api/Advertiser/v8/CampaignManagement/BulkService.svc?wsdl",           :SANDBOX => ""},
+        :CampaignManagementService => {:PRODUCTION => "https://adcenterapi.microsoft.com/Api/Advertiser/v8/CampaignManagement/CampaignManagementService.svc?wsdl", :SANDBOX => ""},
+        :CustomerBillingService    => {:PRODUCTION => "https://sharedservices.adcenterapi.microsoft.com/Api/Billing/v8/CustomerBillingService.svc?wsdl",       :SANDBOX => ""},
+        :CustomerManagementService => {:PRODUCTION => "https://sharedservices.adcenterapi.microsoft.com/Api/CustomerManagement/v8/CustomerManagementService.svc?wsdl", :SANDBOX => ""},
+        :NotificationService       => {:PRODUCTION => "https://sharedservices.adcenterapi.microsoft.com/Api/Notification/v8/NotificationService.svc?wsdl",     :SANDBOX => ""},
+        :OptimizerService          => {:PRODUCTION => "https://adcenterapi.microsoft.com/Api/Advertiser/v8/Optimizer/OptimizerService.svc?wsdl",               :SANDBOX => ""},
+        :ReportingService          => {:PRODUCTION => "https://adcenterapi.microsoft.com/Api/Advertiser/v8/Reporting/ReportingService.svc?wsdl",               :SANDBOX => ""}
+      },
+      :v7 => {
+        :AdministrationService     => {:PRODUCTION => "https://adcenterapi.microsoft.com/Api/Advertiser/v7/Administration/AdministrationService.svc?wsdl",           :SANDBOX => "https://sandboxapi.adcenter.microsoft.com/Api/Advertiser/v7/Administration/AdministrationService.svc?wsdl"},
+        :CampaignManagementService => {:PRODUCTION => "https://adcenterapi.microsoft.com/Api/Advertiser/v7/CampaignManagement/CampaignManagementService.svc?wsdl",   :SANDBOX => "https://sandboxapi.adcenter.microsoft.com/Api/Advertiser/v7/CampaignManagement/CampaignManagementService.svc?wsdl"},
+        :CustomerBillingService    => {:PRODUCTION => "https://sharedservices.adcenterapi.microsoft.com/Api/Billing/v7/CustomerBillingService.svc?wsdl",             :SANDBOX => "https://sharedservices-sbx.adcenterapi.microsoft.com/Api/Billing/v7/CustomerBillingService.svc?wsdl"},
+        :CustomerManagementService => {:PRODUCTION => "https://sharedservices.adcenterapi.microsoft.com/Api/CustomerManagement/v7/CustomerManagementService.svc?wsdl", :SANDBOX => "https://sharedservices-sbx.adcenterapi.microsoft.com/Api/CustomerManagement/v7/CustomerManagementService.svc?wsdl"},
+        :NotificationService       => {:PRODUCTION => "https://sharedservices.adcenterapi.microsoft.com/Api/Notification/v8/NotificationService.svc?wsdl",           :SANDBOX => ""},
+        :ReportingService          => {:PRODUCTION => "https://adcenterapi.microsoft.com/Api/Advertiser/v7/Reporting/ReportingService.svc?wsdl",                     :SANDBOX => "https://sandboxapi.adcenter.microsoft.com/Api/Advertiser/v7/Reporting/ReportingService.svc?wsdl"}
+      }
+    }
+
+    # Auth constants for ClientLogin method.
+    #TODO: remove client_login_config
+    @@client_login_config = {
+      :AUTH_SERVER => 'https://www.microsoft.com',
+      :LOGIN_SERVICE_NAME => 'adcenter'
+    }
+
+    public
+
+    # Getters for constants and module variables.
+    def self.default_version
+      DEFAULT_VERSION
+    end
+
+    def self.default_environment
+      DEFAULT_ENVIRONMENT
+    end
+
+    def self.latest_version
+      LATEST_VERSION
+    end
+
+    def self.api_name
+      API_NAME
+    end
+
+    def self.service_config
+      @@service_config
+    end
+
+    def self.environment_config(environment, key)
+      return @@environment_config.include?(environment) ?
+          @@environment_config[environment][key] : nil
+    end
+
+    def self.address_config
+      @@address_config
+    end
+
+    def self.subdir_config
+      @@subdir_config
+    end
+
+    def self.client_login_config(key)
+      return @@client_login_config[key]
+    end
+
+    def self.default_config_filename
+      DEFAULT_CONFIG_FILENAME
+    end
+
+    def self.headers_config
+      @@headers_config
+    end
+
+    # Get the download URL for Ad Hoc reports.
+    #
+    # Args:
+    # - environment: the service environment to be used
+    # - version: the API version (as a symbol)
+    #
+    # Returns:
+    # - The endpoint URL (as a string)
+    #
+    def self.adhoc_report_download_url(environment, version)
+      base = get_wsdl_base(environment, version)
+      if base
+        base += 'reportdownload/%s' % version.to_s
+      end
+      return base
+    end
+  end
+end

data/lib/bing_ads_api/client_login_header_handler.rb

@@ -0,0 +1,21 @@
+# Handles SOAP headers and namespaces definition for ClientLogin type header.
+
+module BingAdsApi
+  class ClientLoginHeaderHandler < AdsCommonForBingAds::SavonHeaders::BaseHeaderHandler
+
+    private
+
+    # Generates Bing Ads API specific request header with ClientLogin data.
+    def generate_request_header()
+      request_header = super()
+      #puts "--------------- generate_request_header >> request_header >>\n#{request_header}"
+      credentials = @credential_handler.credentials
+      #puts "--------------- generate_request_header >> credentials >>\n#{credentials}"
+      #request_header['authToken'] = @auth_handler.get_token(credentials)
+      credentials.each {|k,v| request_header[prepend_namespace(k.to_s.camelize)] = v}
+      request_header.select!{|k,_| ['ApplicationToken', 'CustomerAccountId', 'CustomerId', 'DeveloperToken', 'UserName', 'Password'].map{|h| prepend_namespace(h)}.include?(k.to_s)}
+      #puts "--------------- generate_request_header >> request_header final >>\n#{request_header}"
+      return request_header
+    end
+  end
+end

data/lib/bing_ads_api/credential_handler.rb

@@ -0,0 +1,91 @@
+require 'bing_ads_api/api_config'
+
+module BingAdsApi
+  class CredentialHandler < AdsCommonForBingAds::CredentialHandler
+    # Whether we're making MCC-level requests.
+    attr_accessor :use_mcc
+    # Whether we're making validate-only requests.
+    attr_accessor :validate_only
+    # Whether we're making partial failure requests.
+    attr_accessor :partial_failure
+
+    def initialize(config)
+      super(config)
+      @use_mcc = false
+      @validate_only = false
+      @partial_failure = false
+    end
+
+    # Create the list of credentials to be used by the auth handler for header
+    # generation.
+    def credentials(credentials_override = nil)
+      result = super(credentials_override)
+      #puts "credentials result=\n#{result}"
+      validate_headers_for_server(result)
+
+      extra_headers = {
+        'userAgent' => generate_user_agent(),
+        'developerToken' => result[:developer_token]
+      }
+      if !@use_mcc and result[:client_customer_id]
+        extra_headers['clientCustomerId'] = result[:client_customer_id]
+      end
+      extra_headers['validateOnly'] = 'true' if @validate_only
+      extra_headers['partialFailure'] = 'true' if @partial_failure
+      result[:extra_headers] = extra_headers
+      #puts "credentials result2=\n#{result}"
+      return result
+    end
+
+    # Generates string to use as user agent in headers.
+    def generate_user_agent(extra_ids = [])
+      agent_app = @config.read('authentication.user_agent')
+      extra_ids << ['AwApi-Ruby/%s' % BingAdsApi::ApiConfig::CLIENT_LIB_VERSION]
+       super(extra_ids, agent_app)
+     end
+
+    private
+
+    # Validates that the right credentials are being used for the chosen
+    # environment.
+    #
+    # Raises:
+    # - AdsCommonForBingAds::Error::EnvironmentMismatchError if sandbox credentials are
+    # being used for production or vice-versa.
+    # - BingAdsApi::Errors:BadCredentialsError if supplied credentials are not
+    # valid.
+    #
+    def validate_headers_for_server(credentials)
+      if credentials[:client_email]
+        raise BingAdsApi::Errors::BadCredentialsError, 'Deprecated header ' +
+            'clientEmail is no longer supported, please use clientCustomerId'
+      end
+
+      client_customer_id = credentials[:client_customer_id]
+      if client_customer_id and
+          !(client_customer_id.is_a?(Integer) or
+            (client_customer_id =~ /^\d+(-\d+-\d+)?$/))
+        raise BingAdsApi::Errors::BadCredentialsError,
+            'Invalid client customer ID: %s' % client_customer_id.to_s
+      end
+
+      token = credentials[:developer_token]
+      #sandbox_token = (token =~ /[a-zA-Z0-9]{12,}/)
+      #environment = @config.read('service.environment')
+      #case environment
+      #  when :PRODUCTION
+      #    if sandbox_token
+      #      raise AdsCommonForBingAds::Errors::EnvironmentMismatchError,
+      #          'Attempting to connect to production with sandbox credentials.'
+      #    end
+      #  when :SANDBOX
+      #    if (!sandbox_token)
+      #      raise AdsCommonForBingAds::Errors::EnvironmentMismatchError,
+      #          'Attempting to connect to the sandbox with malformatted ' +
+      #          'credentials. Please check http://msdn.microsoft.com/en-US/library/aa983013 for details.'
+      #    end
+      #end
+      return nil
+    end
+  end
+end