bing-ads-api 0.1.0

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

@@ -0,0 +1,186 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi
+	
+	##
+	# Public : Defines the base object for all report requests.
+	# Do not instantiate this object. Instead, you may instantiate one 
+	# of the following report request objects which derives from this object to request a report.
+	# 
+	# Reference: http://msdn.microsoft.com/en-us/library/bing-ads-reporting-bing-ads-reportrequest.aspx
+	# 
+	# Author:: jlopezn@neonline.cl 
+	#
+	# === Usage
+	#   
+	#   request = BingAdsApi::CampaignPerformanceReportRequest.new(
+	#     :format   => :xml,
+	#     :language => :english,
+	#     :report_name => "Me report",
+	#     :aggregation => :hourly,
+	#     :columns => [:account_name, :account_number, :time_period],
+	#     # The filter is specified as a hash
+	#     :filter => {
+	#       # specifies the Bing expected String value
+	#       :ad_distribution => "Search", 
+	#       # specifies criteria as a snake case symbol
+	#       :device_os => :android,
+	#       :device_type => :tablet,
+	#       # criteria nil is similar to not specify it at all
+	#       :status => nil },
+	#     :scope => { 
+	#       :account_ids => [123456, 234567],
+	#       :campaigns => [<BingAdsApi::CampaignReportScope>] },
+	#     # predefined date
+	#     :time => :this_week)
+	#   
+	#   request2 = BingAdsApi::CampaignPerformanceReportRequest.new(
+	#     :format   => :csv,
+	#     :language => :french,
+	#     :report_name => "Me report",
+	#     :aggregation => :daily,
+	#     :columns => [:account_name, :account_number, :time_period],
+	#     # no filter is specified 
+	#     :scope => { 
+	#       :account_ids => [123456, 234567],
+	#       :campaigns => [<BingAdsApi::CampaignReportScope>] },
+	#     # Custom date range
+	#     :time => {
+	#       :custom_date_range_start => {:day => 1, :month => 12, :year => 2013},
+	#       :custom_date_range_end   => {:day => 12, :month => 12, :year => 2013} }
+	#     )
+	class CampaignPerformanceReportRequest < BingAdsApi::PerformanceReportRequest
+		
+		# Valid Columns for this report request 
+		COLUMNS = BingAdsApi::Config.instance.
+			reporting_constants['campaign_performance_report']['columns']
+		
+		# Valid Filters for this report request 
+		FILTERS = BingAdsApi::Config.instance.
+			reporting_constants['campaign_performance_report']['filter']
+		
+		
+		# Public : Constructor. Adds a validations for the columns, filter 
+		# and scope attributes 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# === Parameters
+		# * +attributes+ - Hash with the report request attributes
+		#
+		# === Example
+		#   
+		#   request = BingAdsApi::CampaignPerformanceReportRequest.new(
+		#     :format   => :xml,
+		#     :language => :english,
+		#     :report_name => "Me report",
+		#     :aggregation => :hourly,
+		#     :columns => [:account_name, :account_number, :time_period],
+		#     # The filter is specified as a hash
+		#     :filter => {
+		#       # specifies the Bing expected String value
+		#       :ad_distribution => "Search", 
+		#       # specifies criteria as a snake case symbol
+		#       :device_os => :android,
+		#       :device_type => :tablet,
+		#       # criteria nil is similar to not specify it at all
+		#       :status => nil },
+		#     :scope => { 
+		#       :account_ids => [123456, 234567],
+		#       :campaigns => [<BingAdsApi::CampaignReportScope>] },
+		#     # predefined date
+		#     :time => :this_week)
+		#   
+		#   request2 = BingAdsApi::CampaignPerformanceReportRequest.new(
+		#     :format   => :csv,
+		#     :language => :french,
+		#     :report_name => "Me report",
+		#     :aggregation => :daily,
+		#     :columns => [:account_name, :account_number, :time_period],
+		#     # no filter is specified 
+		#     :scope => { 
+		#       :account_ids => [123456, 234567],
+		#       :campaigns => [<BingAdsApi::CampaignReportScope>] },
+		#     # Custom date range
+		#     :time => {
+		#       :custom_date_range_start => {:day => 1, :month => 12, :year => 2013},
+		#       :custom_date_range_end   => {:day => 12, :month => 12, :year => 2013} }
+		#     )
+		def initialize(attributes={})
+			raise Exception.new("Invalid columns") if !valid_columns(COLUMNS, attributes[:columns])
+			raise Exception.new("Invalid filters") if !valid_filter(FILTERS, attributes[:filter])
+			raise Exception.new("Invalid scope") if !valid_scope(attributes[:scope])
+			super(attributes)
+		end
+		
+		
+		# Public:: Returns the object as a Hash valid for SOAP requests 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# === Parameters
+		# * +keys_case+ - case for the hashes keys: underscore or camelcase
+		# 
+		# Returns:: Hash
+		def to_hash(keys = :underscore)
+			hash = super(keys)
+			hash[get_attribute_key('columns', keys)] = 
+				columns_to_hash(COLUMNS, columns, keys)
+			hash[get_attribute_key('filter', keys)] = 
+				filter_to_hash(FILTERS, keys)
+			hash[get_attribute_key('scope', keys)] = scope_to_hash(keys) 
+			hash["@xsi:type"] = type_attribute_for_soap 
+			return hash
+		end
+		
+		
+		private
+			
+			# Internal:: Validates the scope attribute given in the constructor 
+			# 
+			# Author:: jlopezn@neonline.cl 
+			# 
+			# === Parameters
+			# * +scope+ - value for the 'scope' key in the has initializer
+			# 
+			# Returns:: true if the scope specification is valid. Raises Exception otherwise
+			# 
+			# Raises:: Exception if the scope is not valid
+			def valid_scope(scope)
+				raise Exception.new("Invalid scope: no account_ids key") if !scope.key?(:account_ids)
+				raise Exception.new("Invalid scope: no campaigns key") if !scope.key?(:campaigns)
+				return true
+			end
+			
+			
+			# Internal:: Returns the scope attribute as a hash for the SOAP request 
+			# 
+			# Author:: jlopezn@neonline.cl 
+			# 
+			# === Parameters
+			# * +keys_case+ - case for the hash: underscore or camelcase
+			# 
+			# Returns:: Hash
+			def scope_to_hash(keys_case=:underscore)
+				return {
+					get_attribute_key('account_ids', keys_case) => {"ins0:long" => object_to_hash(scope[:account_ids], keys_case)},
+					get_attribute_key('campaigns', keys_case) => 
+						{ "CampaignReportScope" => object_to_hash(scope[:campaigns], keys_case) }
+					}
+			end
+			
+			
+			# Internal:: Returns a string with type attribute for the ReportRequest SOAP tag 
+			# 
+			# Author:: jlopezn@neonline.cl 
+			# 
+			# Returns:: "v9:CampaignPerformanceReportRequest"
+			def type_attribute_for_soap
+				return BingAdsApi::ClientProxy::NAMESPACE.to_s + ":" + 
+					BingAdsApi::Config.instance.
+						reporting_constants['campaign_performance_report']['type']
+			end
+			
+	end
+	
+end

data/lib/bing-ads-api/data/reporting/helpers/column_helper.rb

@@ -0,0 +1,65 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi::Helpers
+	
+	##
+	# Public : Utility module 
+	# 
+	# Author:: jlopezn@neonline.cl 
+	# 
+	module ColumnHelper
+
+		# Internal : Validates the specified columns at the ReporRequest initialization
+		# At the first invalid column detected this method raises Exception.
+		# If all column values are ok, this method returns true 
+		# Valid columns are validated against COLUMNS constant
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# valid_columns - Hash with the valid names and values for columns
+		# columns - Hash with the columns specified in the initialization
+		# 
+		# Returns:: true if all columns are ok
+		# Raises:: Exception at the first invalid column detected
+		def valid_columns(valid_columns, columns)
+			columns.each do |col|
+
+				if col.is_a?(String)
+					if !valid_columns.value?(col)
+						raise Exception.new("Invalid column value '#{col}'")
+					end 
+				elsif col.is_a?(Symbol)
+					if !valid_columns.key?(col.to_s)
+						raise Exception.new("Invalid column name '#{col}'")
+					end
+				end
+			end
+			return true
+		end
+
+
+		# Public : Return the columns attribute of the ReportRequest as a valid Hash for SOAP requests 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# keys_case - specifies the keys_case for the hash: :underscore or :camelcase
+		# 
+		# Returns:: Hash
+		def columns_to_hash(valid_columns, columns, keys_case=:underscore)
+			raise Exception.new("Invalid time value: nil") if columns.nil?
+			
+			key = self.class.to_s.demodulize.gsub(/ReportRequest/, 'ReportColumn')
+			return { key => 
+					columns.map do |col|
+						if col.is_a?(String)
+							col
+						elsif col.is_a?(Symbol)
+							valid_columns[col.to_s]
+						end
+					end
+				}
+		end
+		
+		
+	end
+end

data/lib/bing-ads-api/data/reporting/helpers/filter_helper.rb

@@ -0,0 +1,124 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi::Helpers
+	
+	##
+	# Public : Utility module for filter attribute in +ReportRequest+ derived classes
+	# 
+	# Author:: jlopezn@neonline.cl 
+	# 
+	module FilterHelper
+		
+		include BingAdsApi::SOAPHasheable
+		
+		
+		# Valid filters values for each known criteria
+		FILTERS_CRITERIA = BingAdsApi::Config.instance.
+			reporting_constants['filters']
+		
+		
+		# Internal : Validates the filter attribute at the ReporRequest initialization
+		# At the first invalid filter criteria or value detected this method raises Exception.
+		# If all filter criteria and values are ok, this method returns true 
+		# Valid filter criteria are validated against FILTERS_CRITERIA constant
+		# Valid filter values are validated against FILTERS constant
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# === Parameters
+		# valid_filters - Hash with the set of valid filter values
+		# filter - Hash with the filter criteria and values
+		# 
+		# Returns:: true if filter is valid
+		# 
+		# Raises:: Exception at the first invalid filter criteria o value
+		def valid_filter(valid_filters, filter)
+			if filter && filter.is_a?(Hash)
+				filter.keys.each do |filter_key|
+					# validates if filter criteria is recognized
+					raise Exception.new("Invalid filter criteria '#{filter_key.to_s}'") if !valid_filters.key?(filter_key.to_s)
+					# validates the filter criteria value
+					valid_filter_value(filter_key, filter[filter_key])
+				end
+			end
+			return true
+		end
+		
+		
+		# Internal : Validates a specific filter criteria and his value 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# key - filter criteria to evaluate
+		# value - filter criteria to be evaluate
+		# 
+		# Returns:: true if validation runs ok. Raise exception otherwise
+		#
+		# Raises:: Exception if filter value provided is not valid
+		def valid_filter_value(key, value)
+			return true if value.nil?
+			return true if solve_filter_value(key, value)
+		end
+		
+		
+		# Public : Returns the filter attribute as a Hash to SOAP requests 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# filter - Hash with the filter values
+		# 
+		# Returns:: Hash
+		def filter_to_hash(valid_filters, keys_case=:undescore)
+			hashed_filter = {}
+			filter.each do |key, value|
+				hashed_filter[get_attribute_key(key, keys_case)] = solve_filter_value(key, value)
+			end
+			return hashed_filter
+		end
+
+
+		# Internal:: Solves the Bing value for the given filter attribute 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# === Parameters
+		# * +filter_criteria+ - String or symbol with the filter attribute to be solved
+		# 
+		# === Examples 
+		#   solve_filter_value(:ad_distribution, :search) 
+		#   # => "Search" 
+		# 
+		#   solve_filter_value(:ad_distribution, :other) 
+		#   # => Exception "Invalid filter name 'other' for 'ad_distribution' criteria"
+		# 
+		#   solve_filter_value(:ad_distribution, "Search") 
+		#   # => "Search" 
+		# 
+		#   solve_filter_value(:ad_distribution, "Other") 
+		#   # => Exception "Invalid filter value 'Other' for 'ad_distribution' criteria"
+		# 
+		# Returns:: String with the Bing value for the filter criteria.
+		# 
+		# Raises:: Exception if the filter's criteria or value are unknown
+		def solve_filter_value(filter_criteria, filter_value)
+			
+			filter_criteria_values = FILTERS_CRITERIA[filter_criteria.to_s]
+			if filter_value.is_a?(String)
+				if filter_criteria_values.value?(filter_value)
+					return filter_value
+				else
+					raise Exception.new("Invalid filter value '#{filter_value}' for '#{filter_criteria}' criteria")
+				end 
+			elsif filter_value.is_a?(Symbol)
+				if filter_criteria_values.key?(filter_value.to_s)
+					return filter_criteria_values[filter_value.to_s]
+				else
+					raise Exception.new("Invalid filter name '#{filter_value}' for '#{filter_criteria}' criteria")
+				end
+			end
+			return nil
+		end
+
+
+	end
+end

data/lib/bing-ads-api/data/reporting/helpers/scope_helper.rb

@@ -0,0 +1,51 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi::Helpers
+	
+	##
+	# Public : Utility module for scope attribute in +ReportRequest+ derived classes
+	# 
+	# Author:: jlopezn@neonline.cl 
+	# 
+	module ScopeHelper
+		
+		include BingAdsApi::SOAPHasheable
+		
+		
+		# Valid filters values for each known criteria
+		FILTERS_CRITERIA = BingAdsApi::Config.instance.
+			reporting_constants['filters']
+		
+		
+		# Internal : Validates the filter attribute at the ReporRequest initialization
+		# At the first invalid filter criteria or value detected this method raises Exception.
+		# If all filter criteria and values are ok, this method returns true 
+		# Valid filter criteria are validated against FILTERS_CRITERIA constant
+		# Valid filter values are validated against FILTERS constant
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# === Parameters
+		# valid_filters - Hash with the set of valid filter values
+		# filter - Hash with the filter criteria and values
+		# 
+		# Returns:: true if filter is valid
+		# 
+		# Raises:: Exception at the first invalid filter criteria o value
+		def valid_scope(valid_scopes, scope)
+		end
+		
+		
+		# Public : Returns the filter attribute as a Hash to SOAP requests 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# filter - Hash with the filter values
+		# 
+		# Returns:: Hash
+		def scope_to_hash(keys_case=:undescore)
+		end
+
+
+	end
+end

data/lib/bing-ads-api/data/reporting/helpers/time_helper.rb

@@ -0,0 +1,69 @@
+# -*- encoding : utf-8 -*-
+
+module BingAdsApi::Helpers
+	
+	##
+	# Public : Utility module 
+	# 
+	# Author:: jlopezn@neonline.cl 
+	# 
+	module TimeHelper
+
+		# Valid languages for reports 
+		TIME_PERIODS = BingAdsApi::Config.instance.
+			reporting_constants['time_periods']
+
+		# Public : Validates the time attribute present in some report request 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# time - Hash with the time attribute for the report request
+		# 
+		# Returns:: true if validation is ok, raises Exception otherwise
+		# Raises:: Exception if custom date range is bad informed, or if time periods specified is unknown
+		def valid_time(time)
+			# Custom date range
+			if time.is_a?(Hash)
+				raise Exception.new("Invalid time: missing :custom_date_range_start key") if !time.key?(:custom_date_range_start)
+				raise Exception.new("Invalid time: missing :custom_date_range_end key")  if !time.key?(:custom_date_range_end)
+			# Time periods
+			else
+				return TIME_PERIODS.key?(time.to_s)
+			end
+			return true
+		end
+
+
+		# Public : Return the time attribute of the ReportRequest as a valid Hash for SOAP requests 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# keys_case - specifies the keys_case for the hash: :underscore or :camelcase
+		# 
+		# Returns:: Hash
+		def time_to_hash(keys_case)
+			raise Exception.new("Invalid time value: nil") if self.time.nil?
+			
+			# Custom date range
+			if time.is_a?(Hash)
+				return {
+					get_attribute_key("custom_date_range_end", keys_case) => {
+						get_attribute_key("day", keys_case) => self.time[:custom_date_range_end][:day],
+						get_attribute_key("month", keys_case) => self.time[:custom_date_range_end][:month],
+						get_attribute_key("year", keys_case) => self.time[:custom_date_range_end][:year],
+						
+					},
+					get_attribute_key("custom_date_range_start", keys_case) => {
+						get_attribute_key("day", keys_case) => self.time[:custom_date_range_start][:day],
+						get_attribute_key("month", keys_case) => self.time[:custom_date_range_start][:month],
+						get_attribute_key("year", keys_case) => self.time[:custom_date_range_start][:year],
+					}
+				}
+			# Time periods
+			else
+				return TIME_PERIODS[time.to_s]
+			end
+		end		
+		
+	end
+end