bing-ads-api 0.1.0

data/lib/bing-ads-api/data/reporting/performance_report_request.rb

@@ -0,0 +1,78 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+	
+	##
+	# Public : Defines the base class for 'performance report requests'.
+	# Do not instantiate this object. Instead, use BingAdsApi::AccountPerformanceReportRequest, 
+	# BingAdsApi::CampaignPerformanceReportRequest, BingAdsApi::AdGroupPerformanceReportRequest or
+	# BingAdsApi::AdPerformanceReportRequest
+	# 
+	# Reference: http://msdn.microsoft.com/en-us/library/bing-ads-reporting-bing-ads-reportrequest.aspx
+	# 
+	# Author:: jlopezn@neonline.cl 
+	class PerformanceReportRequest < BingAdsApi::ReportRequest
+		
+		# Adds helper methods to time attribute
+		include BingAdsApi::Helpers::TimeHelper
+
+		# Adds helper methods to column attribute
+		include BingAdsApi::Helpers::ColumnHelper
+
+		# Adds helper methods to filter attribute
+		include BingAdsApi::Helpers::FilterHelper
+
+
+		# Valid aggregations for reports 
+		AGGREGATIONS = BingAdsApi::Config.instance.
+			reporting_constants['aggregation']
+
+
+		attr_accessor :aggregation, :columns, :filter, :scope, :time
+
+
+		# Public : Constructor. Adds validations to aggregations and time
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# === Parameters
+		# attributes - Hash with Performance report request
+		# 
+		def initialize(attributes={})
+			raise Exception.new("Invalid aggregation '#{attributes[:aggregation]}'") if !valid_aggregation(attributes[:aggregation])
+			raise Exception.new("Invalid time") if !valid_time(attributes[:time])
+			super(attributes)
+		end
+
+
+		# Public:: Returns this object as a Hash for SOAP Requests 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# === Parameters
+		# * +keys_case+ - specifies the case for the hash keys
+		# ==== keys_case
+		# * :camelcase  - CamelCase
+		# * :underscore - underscore_case
+		# 
+		# === Examples 
+		#   performance_report_request.to_hash(:camelcase) 
+		#   # => {"Format"=>"Xml", "Language"=>"English", "ReportName"=>"My Report", "Aggregation"=>"Hourly", "Time"=>"Today", "ReturnOnlyCompleteData"=>false}
+		# 
+		# Returns:: Hash
+		def to_hash(keys_case = :underscore)
+			hash = super(keys_case)
+			hash[get_attribute_key('aggregation', keys_case)] = AGGREGATIONS[self.aggregation.to_s]
+			hash[get_attribute_key('time', keys_case)] = time_to_hash(keys_case)
+			return hash
+		end
+
+		private
+		
+			def valid_aggregation(aggregation)
+				return AGGREGATIONS.key?(aggregation.to_s)
+			end
+
+	end
+	
+end

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

@@ -0,0 +1,35 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+	
+	##
+	# Public : Base Class to define Bing API data objects
+	# Do not use this class directly, use any of the derived classes 
+	# 
+	# Author:: jlopezn@neonline.cl 
+	# 
+	class DataObject
+		
+		
+		include BingAdsApi::SOAPHasheable
+		
+		# Public : Constructor in a ActiveRecord style, with a hash of attributes as input 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# attributes - Hash with the objects attributes
+		def initialize(attributes={})
+			attributes.each { |key, val| send("#{key}=", val) if respond_to?("#{key}=") }
+		end
+		
+		
+		# Public : Specified to string method 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		def to_s
+			to_hash.to_s
+		end
+
+
+	end
+end

data/lib/bing-ads-api/fault/ad_api_error.rb

@@ -0,0 +1,15 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+
+	# Public : Defines an error object that contains the details that explain why the service operation failed.
+	# 
+	# Reference : http://msdn.microsoft.com/en-US/library/bing-ads-overview-adapierror.aspx
+	# 
+	# Author:: jlopezn@neonline.cl 
+	class AdApiError < BingAdsApi::DataObject
+	
+		attr_accessor :code, :detail, :error_code, :message
+		
+	end
+end 

data/lib/bing-ads-api/fault/ad_api_fault_detail.rb

@@ -0,0 +1,67 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+	
+	# Public : Defines a fault object that operations return when generic errors occur, 
+	# such as an authentication error. 
+	# 
+	# Author:: jlopezn@neonline.cl 
+	class AdApiFaultDetail < BingAdsApi::ApplicationFault
+		
+		attr_accessor :errors
+		
+		
+		# Public : Constructor 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# attributes - Hash with the initial attributes
+		# === Attributes
+		# * tracking_id : the operation tracking id value
+		# * errors : array of hashes with the Ad api errors
+		def initialize(attributes={})
+			super(attributes)
+			if attributes
+				initialize_errors(attributes[:errors])
+			end
+		end
+		
+		# Public : Specified to string method 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		def to_s
+			str = super.to_s + ":\n" 
+			if batch_errors
+				str += "\tErrors:\n" + errors.map{ |e| "\t" + e.to_s }.join("\n")
+			end
+			
+			return str
+		end
+		
+		
+		private
+		
+			# Public : Helper method for the AdApiFaultDetail constructor 
+			#   to initialize the errors array 
+			# 
+			# Author:: jlopezn@neonline.cl 
+			# 
+			# errors_hash - Hash with the :errors key received from the SOAP request
+			# 
+			# Returns:: none
+			def initialize_errors(errors_hash)
+				return if errors_hash.nil?
+				
+				if errors_hash[:ad_api_error].is_a?(Array)
+					self.errors = []
+					errors_hash[:ad_api_error].each do |aae|
+						self.errors << BingAdsApi::AdApiError.new(aae)
+					end
+				elsif errors_hash[:ad_api_error].is_a?(Hash)
+					self.errors = [BingAdsApi::AdApiError.new(errors_hash[:ad_api_error])]
+				end
+			end
+			
+	end
+	
+end

data/lib/bing-ads-api/fault/api_fault_detail.rb

@@ -0,0 +1,97 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+	
+	# Public : Defines a fault object that operations return when web service-specific errors occur, 
+	# such as when the request message contains incomplete or invalid data. 
+	# 
+	# Author:: jlopezn@neonline.cl 
+	class ApiFaultDetail < BingAdsApi::ApplicationFault
+		
+		attr_accessor :batch_errors, :operation_errors
+		
+		
+		# Public : Constructor 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# attributes - Hash with the initial attributes
+		# === Attributes
+		# * tracking_id : the operation tracking id value
+		# * batch_errors : array of hashes with the batch errors
+		# * operation_errors : array of hashes with the operation errors 
+		def initialize(attributes={})
+			super(attributes)
+			if attributes
+				initialize_batch_errors(attributes[:batch_errors])
+				initialize_operations_errors(attributes[:operation_errors])
+			end
+		end
+		
+		
+		# Public : Specific to string  
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# Returns:: the object 'stringified'
+		def to_s
+			str = super.to_s + ":\n" 
+			if batch_errors
+				str += "\tBatch Errors:\n" + batch_errors.map{ |be| "\t" + be.to_s }.join("\n")
+			end
+			
+			if operation_errors
+				str += "\tOperation Errors:\n" + operation_errors.map{ |oe| "\t" + oe.to_s }.join("\n")
+			end
+			return str
+		end
+		
+		
+		private
+		
+			# Public : Helper method for the ApiFaultDetail constructor 
+			#   to initialize the batch errors array 
+			# 
+			# Author:: jlopezn@neonline.cl 
+			# 
+			# batch_errors_hash - Hash with the :batch_errors key received from the SOAP request
+			# 
+			# Returns:: none
+			def initialize_batch_errors(batch_errors_hash)
+				return if batch_errors_hash.nil?
+				
+				if batch_errors_hash[:batch_error].is_a?(Array)
+					self.batch_errors = []
+					batch_errors_hash[:batch_error].each do |be|
+						self.batch_errors << BingAdsApi::BatchError.new(be)
+					end
+				elsif batch_errors_hash[:batch_error].is_a?(Hash)
+					self.batch_errors = [BingAdsApi::BatchError.new(batch_errors_hash[:batch_error])]
+				end
+			end
+			
+			
+			# Public : Helper method for the ApiFaultDetail constructor 
+			#   to initialize the operation errors array 
+			# 
+			# Author:: jlopezn@neonline.cl 
+			# 
+			# operation_errors_hash - Hash with the :operation_errors key received from the SOAP request
+			# 
+			# Returns:: none
+			def initialize_operations_errors(operation_errors_hash)
+				return if operation_errors_hash.nil?
+				
+				if operation_errors_hash[:operations_error].is_a?(Array)
+					self.operation_errors = []
+					operation_errors_hash[:operation_error].each do |oe|
+						self.operation_errors << BingAdsApi::OperationError.new(oe)
+					end
+				elsif operation_errors_hash[:operation_error].is_a?(Hash)
+					self.operation_errors = [BingAdsApi::OperationError.new(operation_errors_hash[:operation_error])]
+				end
+				
+			end
+	end
+	
+end

data/lib/bing-ads-api/fault/application_fault.rb

@@ -0,0 +1,18 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+
+	# Public : Defines the base object from which all fault detail objects derive. 
+	# 
+	# Reference: http://msdn.microsoft.com/en-US/library/bing-ads-overview-applicationfault.aspx
+	#
+	# Author:: jlopezn@neonline.cl 
+	class ApplicationFault < BingAdsApi::DataObject
+		
+		attr_accessor :tracking_id
+		
+		def to_s
+			return tracking_id.to_s
+		end
+	end
+end

data/lib/bing-ads-api/fault/batch_error.rb

@@ -0,0 +1,47 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+	
+	# Public : Defines an error object that identifies the item within the batch of items 
+	# in the request message that caused the operation to fail, and describes the reason for the failure.
+	# 
+	# Author:: jlopezn@neonline.cl 
+	# 
+	# Reference : http://msdn.microsoft.com/en-US/library/bing-ads-overview-batcherror.aspx
+	class BatchError < BingAdsApi::DataObject
+	
+		attr_accessor :code, :details, :error_code, :index, :message, :type
+		
+		# Public : Specified to string method 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		def to_s
+			"#{index}:#{code}:#{error_code} - #{message} (#{type})"
+		end
+	end
+	
+	# Public : Subclass of BatchError present in AdAdds operations 
+	# Defines an error object that identifies the entity with the 
+	# batch of entities that failed editorial review.
+	# 
+	# Reference : http://msdn.microsoft.com/en-US/library/bing-ads-overview-editorialerror.aspx
+	# 
+	# Author:: jlopezn@neonline.cl 
+	class EditorialError < BingAdsApi::BatchError
+		
+		attr_accessor :appaleable, :disapproved_text, :location, :publisher_country, :reason_code
+		
+		# Public : Specified to string method 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		def to_s
+			str = super() + "\n"
+			str += "\tAppaleable? #{appaleable}\n" if appaleable
+			str += "\tDisapproved text: #{disapproved_text}\n" if disapproved_text
+			str += "\tLocation: #{location}\n" if location
+			str += "\tDisapproved text: #{disapproved_text}\n" if disapproved_text
+			str += "\tReason code: #{reason_code} (see: http://msdn.microsoft.com/en-US/library/bing-ads-editorialfailurereasoncodes.aspx)\n" if reason_code
+
+		end
+	end
+end 

data/lib/bing-ads-api/fault/operation_error.rb

@@ -0,0 +1,22 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+
+	# Public : Defines an error object that contains the details that explain why the service operation failed.
+	# 
+	# Author:: jlopezn@neonline.cl
+	# 
+	# Reference : http://msdn.microsoft.com/en-US/library/bing-ads-overview-operationerror.aspx
+	class OperationError < BingAdsApi::DataObject
+	
+		attr_accessor :code, :details, :error_code, :message
+		
+		
+		# Public : Specified to string method 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		def to_s
+			"#{code}:#{error_code} - #{message}. #{details}"
+		end
+	end
+end 

data/lib/bing-ads-api/fault/partial_errors.rb

@@ -0,0 +1,75 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+	
+	# Public : Defines an array of error that occur when adding ads  
+	# 
+	# Author:: jlopezn@neonline.cl 
+	class PartialErrors < BingAdsApi::DataObject
+		
+		attr_accessor :batch_errors
+		
+		
+		# Public : Constructor 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# attributes - Hash with the initial attributes
+		# === Attributes
+		# * tracking_id : the operation tracking id value
+		# * batch_error : array of hashes with the batch errors
+		def initialize(attributes={})
+			super(attributes)
+			if attributes
+				initialize_batch_errors(attributes)
+			end
+		end
+		
+		
+		# Public : Specified to string method 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		def to_s
+			str = "  Batch Errors:\n"
+			if batch_errors
+				str += batch_errors.map{ |be| "\t" + be.to_s }.join("\n")
+			end
+			
+			return str
+		end
+		
+		
+		private
+		
+			# Public : Helper method for the ApiFaultDetail constructor 
+			#   to initialize the batch errors array 
+			# 
+			# Author:: jlopezn@neonline.cl 
+			# 
+			# batch_errors_hash - Hash with the :batch_errors key received from the SOAP request
+			# 
+			# Returns:: none
+			def initialize_batch_errors(batch_errors_hash)
+				return if batch_errors_hash.nil?
+				
+				if batch_errors_hash[:batch_error].is_a?(Array)
+					self.batch_errors = []
+					batch_errors_hash[:batch_error].each do |be|
+						self.batch_errors << init_batch_error(be)
+					end
+				elsif batch_errors_hash[:batch_error].is_a?(Hash)
+					self.batch_errors = [ init_batch_error(batch_errors_hash[:batch_error]) ]
+				end
+			end
+			
+			
+			def init_batch_error(batch_error_hash)
+				if batch_error_hash.key?("@i:type".to_sym) && batch_error_hash["@i:type".to_sym] == "EditorialError"
+					return BingAdsApi::EditorialError.new(batch_error_hash)
+				else
+					return BingAdsApi::BatchError.new(batch_error_hash)
+				end
+			end
+	end
+	
+end