gnib-ads-api 0.3

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

@@ -0,0 +1,42 @@
+# -*- encoding : utf-8 -*-
+
+module GnibAdsApi
+
+	# Public : Generic exception thrown by service classes in GnibAdsApi. 
+	#   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/gnib-ads-api/client_proxy.rb

@@ -0,0 +1,147 @@
+# -*- encoding : utf-8 -*-
+
+module GnibAdsApi
+
+	# 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 = GnibAdsApi::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, :authentication_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 Novas 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 = GnibAdsApi::ClientProxy.new(options)
+		# 
+		# Returns:: ClientProxy instance
+		def initialize(options=nil)
+			if options
+				if options[:authentication_token]
+					@authentication_token ||= options[:authentication_token]
+				else
+					@username    ||= options[:username]
+					@password    ||= options[:password]
+				end
+				@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 Novas::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 Novas::Client 
+		# Raises:: Novas::SOAPFault Novas::HTTPError Novas::InvalidResponseError
+		def call(service_name, message, options={})
+			self.service.call(service_name, message)
+		end
+		
+		
+		private
+			# Internal : Wrapper for Novas client instances 
+			# 
+			# Author:: jlopezn@neonline.cl 
+			# 
+			# Examples 
+			#   get_proxy 
+			#   # => <Novas::Client> 
+			# 
+			# Returns:: Novas client instance
+			def get_proxy(client_settings)
+
+				settings = {
+					convert_request_keys_to: KEYS_CASE,
+					wsdl: self.wsdl_url,
+					namespace_identifier: NAMESPACE,
+					soap_header: build_headers
+				}
+				settings.merge(client_settings) if client_settings
+				puts "settings"
+				puts settings
+				return Novas.client(settings)
+			end
+			
+			
+			def build_headers
+				headers = {
+					"#{NAMESPACE.to_s}:CustomerAccountId" => self.account_id,
+					"#{NAMESPACE.to_s}:CustomerId" => self.customer_id,
+					"#{NAMESPACE.to_s}:DeveloperToken" => self.developer_token,
+				}
+				if self.authentication_token
+					headers["#{NAMESPACE.to_s}:AuthenticationToken"] = self.authentication_token
+				else
+					headers["#{NAMESPACE.to_s}:UserName"] = self.username
+					headers["#{NAMESPACE.to_s}:Password"] = self.password
+				end
+				return headers
+			end
+	end
+
+end

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

@@ -0,0 +1,75 @@
+# -*- encoding : utf-8 -*-
+require 'singleton'
+
+module GnibAdsApi 
+
+	# 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__),"../gnib-ads-api.yml"))
+		
+		# Public : Constructor 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		def initialize
+			@config = YAML.load_file(File.join(File.dirname(__FILE__),"../gnib-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/gnib-ads-api/constants.rb

@@ -0,0 +1,150 @@
+# -*- encoding : utf-8 -*-
+
+module GnibAdsApi
+
+	# Public : Utility class for TimeZones values
+	#
+	# Example
+	#   GnibAdsApi::TimeZone.SANTIAGO
+	#   # => 'Santiago'
+	# 
+	# Author:: jlopezn@neonline.cl 
+	module TimeZone
+	
+			
+		GnibAdsApi::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
+	#   GnibAdsApi::AdLanguages.SPANISH
+	#   # => 'Spanish'
+	#   GnibAdsApi::AdLanguages.SPANISH_CODE
+	#   # => 'ES'
+	# 
+	# Author:: jlopezn@neonline.cl 
+	module AdLanguage
+	
+		GnibAdsApi::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
+	GnibAdsApi::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	
+		GnibAdsApi.const_set(const_key.camelize, const_module)
+
+	end
+
+
+	## Dynamic classes for customer management constants
+	GnibAdsApi::Config.instance.customer_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	
+		GnibAdsApi.const_set(const_key.camelize, const_module)
+
+	end
+
+
+
+	# Public : Module for Reporting formats 
+	# 
+	# Example
+	#   GnibAdsApi::ReportFormat.CSV
+	#   # => 'Csv'
+	#
+	# Author:: jlopezn@neonline.cl 
+	module ReportFormat
+		GnibAdsApi::Config.instance.reporting_constants['format'].each do |key, value|
+			ReportFormat.const_set(key.upcase, value)
+		end
+	end
+	
+	
+	# Public : Module for Reporting languages 
+	# 
+	# Example
+	#   GnibAdsApi::ReportLanguage.ENGLISH
+	#   # => 'English'
+	#
+	# Author:: jlopezn@neonline.cl 
+	module ReportLanguage
+		GnibAdsApi::Config.instance.reporting_constants['language'].each do |key, value|
+			ReportLanguage.const_set(key.upcase, value)
+		end
+	end
+	
+	
+	# Public : Module for Reporting languages 
+	# 
+	# Example
+	#   GnibAdsApi::ReportAggregation.SUMMARY
+	#   # => 'Summary'
+	#   GnibAdsApi::ReportAggregation.HOURLY
+	#   # => 'Hourly'
+	#
+	# Author:: jlopezn@neonline.cl 
+	module ReportAggregation
+		GnibAdsApi::Config.instance.reporting_constants['aggregation'].each do |key, value|
+			ReportAggregation.const_set(key.upcase, value)
+		end
+	end
+	
+	
+	# Public : Module for Reporting languages 
+	# 
+	# Example
+	#   GnibAdsApi::ReportTimePeriods.TODAY
+	#   # => 'Today'
+	#   GnibAdsApi::ReportTimePeriods.LAST_WEEK
+	#   # => 'LastWeek'
+	# 
+	# Author:: jlopezn@neonline.cl 
+	module ReportTimePeriods
+		GnibAdsApi::Config.instance.reporting_constants['time_periods'].each do |key, value|
+			ReportTimePeriods.const_set(key.upcase, value)
+		end
+	end
+	
+	
+	## Dynamic classes for reporting constants
+	# GnibAdsApi::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	
+		# GnibAdsApi.const_set(const_key.camelize, const_module)
+# 
+	# end
+
+end

data/lib/gnib-ads-api/data/accounts_info.rb

@@ -0,0 +1,72 @@
+# -*- encoding : utf-8 -*-
+
+module GnibAdsApi
+	
+	# Public : Define an account info  
+	# 
+	# Author:: jlopezn@neonline.cl 
+	# 
+	# Examples 
+	#   campaign = GnibAdsApi::AccountInfo.new(
+	#     :account_life_cycle_status => GnibAdsApi::AccountsInfo::DRAFT 
+	#     :name => "Account Name",
+	#     :number => 1234567,
+	#     :pause_reason => "1")
+	#   # => <GnibAdsApi::AccountInfo> 
+	class AccountInfo < GnibAdsApi::DataObject
+		include GnibAdsApi::AccountLifeCycleStatuses
+	
+		attr_accessor :id, :account_life_cycle_status, :name, :number, :pause_reason
+	
+		# Public:: Returns true if the account is in status active 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# Returns:: boolean
+		def active?
+			return account_life_cycle_status == ACTIVE 
+		end
+
+
+		# Public:: Returns true if the account is in status draft 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# Returns:: boolean
+		def draft?
+			return account_life_cycle_status == DRAFT 
+		end
+
+
+		# Public:: Returns true if the account is in status inactive 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# Returns:: boolean
+		def inactive?
+			return account_life_cycle_status == INACTIVE 
+		end
+
+
+		# Public:: Returns true if the account is in status pause 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# Returns:: boolean
+		def pause?
+			return account_life_cycle_status == PAUSE 
+		end
+
+
+		# Public:: Returns true if the account is in status pending 
+		# 
+		# Author:: jlopezn@neonline.cl 
+		# 
+		# Returns:: boolean
+		def pending?
+			return account_life_cycle_status == PENDING 
+		end
+
+	end
+
+end