adcenter_api 0.0.1

data/README.md

@@ -0,0 +1,57 @@
+AdCenter Api Client
+=============
+
+Description
+-------------
+A simple ruby wrapper for the AdCenter API based on the gem "google-ads-common".
+
+Usage
+-------------
+
+    # install in your gem file
+    gem 'adcenter_api', :git => 'https://github.com/weboglobin/adcenter_api.git'
+
+    # initialize the client
+    client = AdcenterApi::Api.new(
+            {
+              :authentication => {
+                :method => 'ClientLogin',
+                :developer_token => 'DEVELOPER_TOKEN',
+                :user_name => 'USERNAME',
+                :password => 'PASSWORD',
+                :customer_id => 'customer_id', # may be optional for some requests
+                :customer_account_id => 'customer_account_id' # may be optional for some requests
+              },
+              :service => {:environment => 'PRODUCTION'},
+              :library => {:log_level => 'DEBUG'}
+            })
+
+    # select the service and the API version (:v7 or :v8)
+    administration_service = client.service(:AdministrationService, :v7)
+
+    # send your request
+    result = administration_service.get_assigned_quota()
+
+    # select another service
+    campaign_service = client.service(:CampaignManagementService, :v7)
+
+    # send another request
+    result = campaign_service.get_campaigns_by_account_id({:account_id => 00000})
+
+    # create a campaign
+    result2 = campaign_service.add_campaigns({:account_id => 00000,
+                                            :campaigns => {:campaign => [{:budget_type => "DailyBudgetWithMaximumMonthlySpend",
+                                                                          :conversion_tracking_enabled => false,
+                                                                          :daily_budget => 5,
+                                                                          :daylight_saving => false,
+                                                                          :description => "A perfect new campaign",
+                                                                          :monthly_budget => 50,
+                                                                          :name => "perfectcampaign",
+                                                                          :time_zone => "BrusselsCopenhagenMadridParis"}]
+                                                          }
+                                            })
+
+About the gem
+-------------
+The tests still have to be written.
+Any help is welcome !

data/lib/adcenter_api.rb

@@ -0,0 +1,180 @@
+require 'savon'
+require 'httpi'
+require 'active_support/inflector'
+require 'ads_common/api'
+#require 'ads_common/savon_headers/oauth_header_handler'
+
+require 'adcenter_api/api_config'
+require 'adcenter_api/client_login_header_handler'
+require 'adcenter_api/credential_handler'
+require 'adcenter_api/errors'
+require 'adcenter_api/report_utils'
+require 'ads_common/api_config_decorator'
+require 'ads_common/parameters_validator_decorator'
+require 'ads_common/auth/client_login_handler_decorator'
+require 'ads_common/savon_service_decorator'
+require 'ads_common/savon_headers_base_header_handler_decorator'
+
+module AdcenterApi
+
+  # 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 < AdsCommon::Api
+
+    # Constructor for API.
+    def initialize(provided_config = nil)
+      super(provided_config)
+      @credential_handler = AdcenterApi::CredentialHandler.new(@config)
+    end
+
+    # Getter for the API service configurations
+    def api_config()
+      AdcenterApi::ApiConfig
+    end
+
+    # Retrieve correct soap_header_handler.
+    #
+    # Args:
+    # - auth_handler: instance of an AdsCommon::Auth::BaseHandler subclass to
+    #   handle authentication
+    # - version: intended API version
+    # - namespace: namespace to use as default for body
+    #
+    # Returns:
+    # - a list of SOAP header handlers; one per provided header
+    #
+    def soap_header_handler(auth_handler, version, namespace)
+      auth_method = @config.read('authentication.method', :CLIENTLOGIN)
+      handler =
+          case auth_method
+          when :CLIENTLOGIN
+            #auth_ns = api_config.client_login_config(:AUTH_NAMESPACE_PREAMBLE) + version.to_s
+            #AdcenterApi::ClientLoginHeaderHandler.new(@credential_handler, auth_handler, namespace, auth_ns, version)
+            AdcenterApi::ClientLoginHeaderHandler.new(@credential_handler, auth_handler, namespace, version)
+          when :OAUTH, :OAUTH2
+            AdsCommon::SavonHeaders::OAuthHeaderHandler.new(@credential_handler, auth_handler, namespace, version)
+          end
+      return handler
+    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 AdsCommon::Errors::Error, "Unknown version '%s'" % version
+      end
+      return AdcenterApi::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/adcenter_api/api_config.rb

@@ -0,0 +1,163 @@
+# encoding: utf-8
+# Helper methods for loading and managing the available services in the AdCenter API.
+
+require 'ads_common/api_config'
+
+require 'adcenter_api/version'
+
+module AdcenterApi
+
+  # Contains helper methods for loading and managing the available services.
+  module ApiConfig
+
+    # Inherit from AdsCommon::ApiConfig
+    class << ApiConfig
+      include AdsCommon::ApiConfig
+    end
+
+    # Set defaults
+    DEFAULT_VERSION = :v8
+    DEFAULT_ENVIRONMENT = :PRODUCTION
+    LATEST_VERSION = :v8
+
+    # Set other constants
+    API_NAME = 'AdcenterApi'
+    DEFAULT_CONFIG_FILENAME = 'adcenter_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 => '',
+        :v7 => '',
+        :v8 => ''
+      },
+      :SANDBOX => {
+        :oauth_scope => '',
+        :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',
+      :AUTH_NAMESPACE_PREAMBLE => 'https://adcenter.microsoft.com/api/adcenter/',
+      :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/adcenter_api/client_login_header_handler.rb

@@ -0,0 +1,70 @@
+# Handles SOAP headers and namespaces definition for ClientLogin type header.
+require 'ads_common/savon_headers/base_header_handler'
+
+module AdcenterApi
+  class ClientLoginHeaderHandler < AdsCommon::SavonHeaders::BaseHeaderHandler
+    # Initializes a header handler.
+    #
+    # Args:
+    #  - credential_handler: a header with credential data
+    #  - auth_handler: a header with auth data
+    #  - element_name: an API-specific name of header element
+    #  - namespace: default namespace to use
+    #  - auth_namespace: namespace to use for auth headers
+    #  - version: services version
+    #
+    #def initialize(credential_handler, auth_handler, namespace, auth_namespace, version)
+    def initialize(credential_handler, auth_handler, namespace, version)
+      super(credential_handler, auth_handler, namespace, version)
+      #@auth_namespace = auth_namespace
+    end
+
+    # Enriches soap object with API-specific headers like namespaces, login
+    # credentials etc. Sets the default namespace for the body to the one
+    # specified in initializer.
+    #
+    # Args:
+    #  - request: a HTTPI Request for extra configuration (unused)
+    #  - soap: a Savon soap object to fill fields in
+    #
+    # Returns:
+    #  - modified soap structure
+    #
+    def prepare_request(request, soap)
+      super(request, soap)
+      soap.header[:attributes!] ||= {}
+      header_name = prepend_namespace(get_header_element_name())
+      soap.header[:attributes!][header_name] ||= {}
+      #soap.header[:attributes!][header_name]['xmlns'] = @auth_namespace
+      return soap
+    end
+
+    private
+    # Skips namespace prefixes for all elements except top level. Use default
+    # (inherited) prefixing for the top level key.
+    #
+    # Args:
+    #  - str: String to prepend with a namespace
+    #
+    # Returns:
+    #  - String with a namespace
+    #
+    def prepend_namespace(str)
+      #return get_header_element_name().eql?(str) ? super(str) : str
+      super(str)
+    end
+
+    # Generates Adcenter 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