bing-ads-api 0.1.0

data/lib/bing-ads-api/api_exception.rb

@@ -0,0 +1,42 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+
+	# Public : Generic exception thrown by service classes in BingAdsApi. 
+	#   Exception of this kind wrap an AdApiFaultDetail or ApiFaultDetail instance
+	#   to look over the specific details of the SOAP request fault.
+	# 
+	# Author:: jlopezn@neonline.cl 
+	# 
+	# Example
+	#   
+	#
+	#
+	#
+	class ApiException < Exception
+		
+		attr_accessor :fault_object
+		
+		# Public : Constructor. Based on the default Exception constructor, 
+		# adds the fault_object instance, that can be an ApiFaultDetail or 
+		# AdApiFaultDetail instance 
+		# 
+		# === Parameters
+		# * fault_object - AdApiFaultDetail or ApiFaultDetail instance
+		# * msg - optional message
+		#
+		# Author:: jlopezn@neonline.cl 
+		def initialize(fault_object, msg=nil)
+			super(msg)
+			self.fault_object = fault_object
+		end
+		
+		
+		# Public : Specified to string method 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		def to_s
+			super.to_s + " - " + fault_object.to_s
+		end
+	end
+end

data/lib/bing-ads-api/client_proxy.rb

@@ -0,0 +1,131 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+
+	# Public : ClientProxy es un objeto para encapsular la conexión y request 
+	#   de servicios a la API de Bing. En su inicialización requiere los datos 
+	#   de autenticación y el WSDL al servicio que se requiere. 
+	# 
+	# Author:: jlopezn@neonline.cl 
+	# 
+	# Examples
+	#   # => hash con datos autenticación y WSDL 
+	#   options = {
+	#     :username => "username",
+	#     :password => "password",
+	#     :developer_token => "THE_TOKEN",
+	#     :customer_id => "123456",
+	#     :account_id => "123456",
+	#     :wsdl_url => "https://api.sandbox.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v9/CampaignManagementService.svc?singleWsdl"
+	#   }
+	#   # => Instancia de ClientProxy
+	#   client = BingAdsApi::ClientProxy.new(options)
+	#   # => Llamada a servicio 'GetCampaignsByAccountId'
+	#   response = client.service.call(:get_campaigns_by_account_id,
+	#     message: { Account_id: client.account_id})
+	class ClientProxy
+		
+		# Public : Namespace para atributos bing. Hace referencia a la versión de API usada 
+		NAMESPACE = :v9
+
+		# Public : Case empleado los nombres de atributos en los XML 
+		KEYS_CASE = :camelcase
+
+
+		# Atributos del client proxy
+		attr_accessor :username, :password, :developer_token, :wsdl_url, :account_id, :customer_id, :service, :namespace
+		
+		# Public : Constructor 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# === Parameters
+		# options - Hash con valores de autenticación y WSDL
+		# 
+		# 
+		# === Options
+		# * username - Bing Ads username 
+		# * passwrod - Bing Ads user's sign-in password
+		# * developer_token - client application's developer access token
+		# * customer_id - identifier for the customer that owns the account
+		# * account_id - identifier of the account that own the entities in the request
+		# * wsdl_url - URL for the WSDL to be called 
+		# * proxy - Hash with any Savon Client additional options (such as header, logger or enconding)
+		# 
+		# === Examples 
+		#   options = {
+		#     :username => "username",
+		#     :password => "password",
+		#     :developer_token => "THE_TOKEN",
+		#     :customer_id => "123456",
+		#     :account_id => "123456",
+		#     :wsdl_url => "https://api.sandbox.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v9/CampaignManagementService.svc?singleWsdl"
+		#   }
+		#   # => Instancia de ClientProxy
+		#   client = BingAdsApi::ClientProxy.new(options)
+		# 
+		# Returns:: ClientProxy instance
+		def initialize(options=nil)
+			if options
+				@username        ||= options[:username]
+				@password        ||= options[:password]
+				@developer_token ||= options[:developer_token]
+				@wsdl_url        ||= options[:wsdl_url]
+				@account_id      ||= options[:account_id]
+				@customer_id     ||= options[:customer_id]
+				@namespace       ||= options[:namespace]
+			end
+			self.service = get_proxy(options[:proxy])
+		end
+		
+		
+		# Public : Delegate for Savon::Client.call method 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# === Parameters
+		# service_name - Service to be called
+		# message - Message for the service
+		# options - Additional options for the service
+		# 
+		# === Examples 
+		#   client.call_service(:some_service_name, {key: value}) 
+		#   # => <Response> 
+		# 
+		# Returns:: Response from the Savon::Client 
+		# Raises:: Savon::SOAPFault Savon::HTTPError Savon::InvalidResponseError
+		def call(service_name, message, options={})
+			self.service.call(service_name, message)
+		end
+		
+		
+		private
+			# Internal : Wrapper for Savon client instances 
+			# 
+			# Author:: jlopezn@neonline.cl 
+			# 
+			# Examples 
+			#   get_proxy 
+			#   # => <Savon::Client> 
+			# 
+			# Returns:: Savon client instance
+			def get_proxy(client_settings)
+
+				settings = {
+					convert_request_keys_to: KEYS_CASE,
+					wsdl: self.wsdl_url,
+					namespace_identifier: NAMESPACE,
+					soap_header: {
+						"#{NAMESPACE.to_s}:CustomerAccountId" => self.account_id,
+						"#{NAMESPACE.to_s}:CustomerId" => self.customer_id,
+						"#{NAMESPACE.to_s}:DeveloperToken" => self.developer_token,
+						"#{NAMESPACE.to_s}:UserName" => self.username,
+						"#{NAMESPACE.to_s}:Password" => self.password
+					}
+				}
+				settings.merge(client_settings) if client_settings
+				return Savon.client(settings)
+			end
+	end
+
+end

data/lib/bing-ads-api/config.rb

@@ -0,0 +1,75 @@
+# -*- encoding : utf-8 -*-
+require 'singleton'
+
+module BingAdsApi 
+
+	# Public : Helper class for configuration issues like WSDL URLs and constants 
+	# 
+	# Author:: author@neonline.cl 
+	# 
+	# Examples 
+	#   class_usage 
+	#   # => class_usage_return 
+	class Config
+		include Singleton
+		
+		# Array with Bing Ads API environments: +sandbox+ and +production+
+		ENVIRONMENTS = ['sandbox', 'production']
+		
+		attr_accessor :config
+		@config = YAML.load_file(File.join(File.dirname(__FILE__),"../bing-ads-api.yml"))
+		
+		# Public : Constructor 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		def initialize
+			@config = YAML.load_file(File.join(File.dirname(__FILE__),"../bing-ads-api.yml"))
+		end
+
+		# Public : Returns the config file as an Hash instance 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# Returns:: Hash
+		def self.hash_instance
+			instance.config
+		end
+		
+		## Constants
+		@config['constants'].each do |key, value|
+			
+			define_method("#{key.to_s}_constants") do |constant=nil|
+				value[constant.to_s] if constant
+				value
+			end
+			 
+		end
+		
+
+		# Public : Returns a String with WSDL url for the service indicated 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# === Parameters
+		# environment - Bing Environment: 'sandbox' or 'production'
+		# service - service name
+		# 
+		# === Examples 
+		#   config.service_wsdl(:sandbox, :campaign_management) 
+		#   # => "https://api.sandbox.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v9/CampaignManagementService.svc?singleWsdl"
+		# 
+		# Returns:: returns
+		# Raises:: exception
+		def service_wsdl(environment, service)
+			if (ENVIRONMENTS.include?(environment.to_s))
+				if @config['wsdl'][environment.to_s].include?(service.to_s)
+					return @config['wsdl'][environment.to_s][service.to_s]
+				end
+				raise "Unknown service '#{service.to_s}'. Available services: #{@config['wsdl'][environment.to_s].keys.join(", ")}"
+			end
+			raise "Invalid environment: #{environment}. Value should be 'sandbox' or 'production'"
+		end
+ 
+	end
+
+end	

data/lib/bing-ads-api/constants.rb

@@ -0,0 +1,133 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+
+	# Public : Utility class for TimeZones values
+	#
+	# Example
+	#   BingAdsApi::TimeZone.SANTIAGO
+	#   # => 'Santiago'
+	# 
+	# Author:: jlopezn@neonline.cl 
+	module TimeZone
+	
+			
+		BingAdsApi::Config.instance.common_constants['time_zones'].each do |key, value|
+			TimeZone.const_set(key.upcase, value)
+		end 
+		
+	end
+
+	# Public : Utility class for AdLanguages values
+	#
+	# Example
+	#   BingAdsApi::AdLanguages.SPANISH
+	#   # => 'Spanish'
+	#   BingAdsApi::AdLanguages.SPANISH_CODE
+	#   # => 'ES'
+	# 
+	# Author:: jlopezn@neonline.cl 
+	module AdLanguage
+	
+		BingAdsApi::Config.instance.common_constants['ad_languages'].each do |key, value|
+			if key == 'codes'
+				value.each do |code_key, code_value|
+					AdLanguage.const_set("#{code_key.upcase}_CODE", code_value)
+				end
+			else
+				AdLanguage.const_set(key.upcase, value)
+			end
+		end 
+		
+	end
+
+
+	## Dynamic classes for campaign management constants
+	BingAdsApi::Config.instance.campaign_management_constants.each do |const_key, const_value|
+
+		const_module = Module.new do
+			# Dynamically create Constants classes for each value found 
+			const_value.each do |key, value|
+				self.const_set(key.upcase, value)
+			end
+	
+		end	
+		BingAdsApi.const_set(const_key.camelize, const_module)
+
+	end
+
+	# Public : Module for Reporting formats 
+	# 
+	# Example
+	#   BingAdsApi::ReportFormat.CSV
+	#   # => 'Csv'
+	#
+	# Author:: jlopezn@neonline.cl 
+	module ReportFormat
+		BingAdsApi::Config.instance.reporting_constants['format'].each do |key, value|
+			ReportFormat.const_set(key.upcase, value)
+		end
+	end
+	
+	
+	# Public : Module for Reporting languages 
+	# 
+	# Example
+	#   BingAdsApi::ReportLanguage.ENGLISH
+	#   # => 'English'
+	#
+	# Author:: jlopezn@neonline.cl 
+	module ReportLanguage
+		BingAdsApi::Config.instance.reporting_constants['language'].each do |key, value|
+			ReportLanguage.const_set(key.upcase, value)
+		end
+	end
+	
+	
+	# Public : Module for Reporting languages 
+	# 
+	# Example
+	#   BingAdsApi::ReportAggregation.SUMMARY
+	#   # => 'Summary'
+	#   BingAdsApi::ReportAggregation.HOURLY
+	#   # => 'Hourly'
+	#
+	# Author:: jlopezn@neonline.cl 
+	module ReportAggregation
+		BingAdsApi::Config.instance.reporting_constants['aggregation'].each do |key, value|
+			ReportAggregation.const_set(key.upcase, value)
+		end
+	end
+	
+	
+	# Public : Module for Reporting languages 
+	# 
+	# Example
+	#   BingAdsApi::ReportTimePeriods.TODAY
+	#   # => 'Today'
+	#   BingAdsApi::ReportTimePeriods.LAST_WEEK
+	#   # => 'LastWeek'
+	# 
+	# Author:: jlopezn@neonline.cl 
+	module ReportTimePeriods
+		BingAdsApi::Config.instance.reporting_constants['time_periods'].each do |key, value|
+			ReportTimePeriods.const_set(key.upcase, value)
+		end
+	end
+	
+	
+	## Dynamic classes for reporting constants
+	# BingAdsApi::Config.instance.reporting_constants.each do |const_key, const_value|
+# 
+		# const_module = Module.new do
+			# # Dynamically create Constants classes for each value found 
+			# const_value.each do |key, value|
+				# self.const_set(key.upcase, value)
+			# end
+# 	
+		# end	
+		# BingAdsApi.const_set(const_key.camelize, const_module)
+# 
+	# end
+
+end

data/lib/bing-ads-api/data/ad.rb

@@ -0,0 +1,119 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+	
+	##
+	# Public : Defines the base object of an ad. 
+	# Do not instantiate this object. Instead you can instantiate the 
+	# BingAdsApi::TextAd, BingAdsApi::MobileAd, or BingAdsApi::ProductAd 
+	# object that derives from this object.
+	# 
+	# Reference: http://msdn.microsoft.com/en-US/library/bing-ads-campaign-management-ad.aspx
+	# 
+	# Author:: jlopezn@neonline.cl 
+	# 
+	class Ad < BingAdsApi::DataObject
+		include BingAdsApi::AdEditorialStatus
+		include BingAdsApi::AdStatus
+		include BingAdsApi::AdType
+		
+		
+		attr_accessor :id,
+
+			:device_preference,
+			:editorial_status,
+
+			:status,
+			:type
+			
+	end
+
+	##
+	# Public : Defines a text ad. 
+	# 
+	# Reference: http://msdn.microsoft.com/en-US/library/bing-ads-campaign-management-textad.aspx
+	# 
+	# Author:: jlopezn@neonline.cl 
+	# 
+	class TextAd < BingAdsApi::Ad
+		
+		attr_accessor :destination_url,
+			:display_url,
+			:text,
+			:title
+		
+		# Public : Specification of DataObject#to_hash method that ads the type attribute based on this specific class 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# keys - specifies the keys case
+		# 
+		# Returns:: Hash
+		def to_hash(keys = :underscore)
+			hash = super(keys)
+			hash[get_attribute_key("type", keys)] = "Text"
+			return hash
+		end
+	end
+	
+	
+	##
+	# Public : Defines a mobile ad. A mobile ad is displayed to a user 
+	# when the ad is viewed on a low-fi mobile device.
+	# 
+	# Reference: http://msdn.microsoft.com/en-US/library/bing-ads-campaign-management-mobilead.aspx
+	# 
+	# Author:: jlopezn@neonline.cl 
+	# 
+	class MobileAd < BingAdsApi::Ad
+		
+		attr_accessor :business_name,
+			:destination_url,
+			:display_url,
+			:phone_number,
+			:text,
+			:title
+
+		# Public : Specification of DataObject#to_hash method that ads the type attribute based on this specific class 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# keys - specifies the keys case
+		# 
+		# Returns:: Hash
+		def to_hash(keys = :underscore)
+			hash = super(keys)
+			hash[get_attribute_key("type", keys)] = "Mobile"
+			return hash
+		end
+
+	end
+	
+	
+	##
+	# Public : Defines a product ad.
+	# 
+	# Reference: http://msdn.microsoft.com/en-US/library/bing-ads-productad-campaign-management.aspx
+	# 
+	# Author:: jlopezn@neonline.cl 
+	# 
+	class ProductAd < BingAdsApi::Ad
+		
+		attr_accessor :promotional_text
+	
+		# Public : Specification of DataObject#to_hash method that ads the type attribute based on this specific class 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# keys - specifies the keys case
+		# 
+		# Returns:: Hash
+		def to_hash(keys = :underscore)
+			hash = super(keys)
+			hash[get_attribute_key("type", keys)] = "Product"
+			return hash
+		end
+
+	end
+	
+end