bing_ads_api_v9 0.0.6

data/lib/bing_ads_api/report_header_handler.rb

@@ -0,0 +1,46 @@
+# Handles HTTP headers for AdHoc reporting requests.
+
+module BingAdsApi
+  class ReportHeaderHandler
+
+    # Initializes a header handler.
+    #
+    # Args:
+    #  - credential_handler: a header with credential data
+    #  - auth_handler: a header with auth data
+    #  - config: API config
+    #
+    def initialize(credential_handler, auth_handler, config)
+      @credential_handler = credential_handler
+      @auth_handler = auth_handler
+      @config = config
+    end
+
+    # Returns the headers set for the report request.
+    #
+    # Args:
+    #  - url: URL for the report requests
+    #  - cid: clientCustomerId to use
+    #
+    # Returns:
+    #  - a Hash with HTTP headers.
+    #
+    def headers(url, cid)
+      override = (cid.nil?) ? nil : {:client_customer_id => cid}
+      credentials = @credential_handler.credentials(override)
+      headers = {
+          'Content-Type' => 'application/x-www-form-urlencoded',
+          'Authorization' =>
+              @auth_handler.auth_string(credentials, HTTPI::Request.new(url)),
+          'User-Agent' => @credential_handler.generate_user_agent(),
+          'clientCustomerId' => credentials[:client_customer_id].to_s,
+          'developerToken' => credentials[:developer_token]
+      }
+      money_in_micros = @config.read('library.return_money_in_micros')
+      unless money_in_micros.nil?
+        headers['returnMoneyInMicros'] = money_in_micros
+      end
+      return headers
+    end
+  end
+end

data/lib/bing_ads_api/report_utils.rb

@@ -0,0 +1,202 @@
+# Contains utility methods specific to reporting.
+
+require 'cgi'
+require 'gyoku'
+
+require 'bing_ads_api/errors'
+require 'bing_ads_api/report_header_handler'
+
+module BingAdsApi
+  class ReportUtils
+    # Default constructor.
+    #
+    # Args:
+    # - api: BingAdsApi object
+    # - version: API version to use
+    #
+    def initialize(api, version)
+      @api, @version = api, version
+    end
+
+    # Downloads and returns a report.
+    #
+    # Args:
+    # - report_definition: definition of the report in XML text or hash
+    # - cid: optional customer ID to run against
+    #
+    # Returns:
+    # - report body
+    #
+    # Raises:
+    # - BingAdsApi::Errors::InvalidReportDefinitionError if the report
+    #   definition is invalid
+    # - BingAdsApi::Errors::ReportError if server-side error occurred
+    #
+    def download_report(report_definition, cid = nil)
+      return get_report_response(report_definition, cid).body
+    end
+
+    # Downloads a report and saves it to a file.
+    #
+    # Args:
+    # - report_definition: definition of the report in XML text or hash
+    # - path: path to save report to
+    # - cid: optional customer ID to run against
+    #
+    # Returns:
+    # - nil
+    #
+    # Raises:
+    # - BingAdsApi::Errors::InvalidReportDefinitionError if the report
+    #   definition is invalid
+    # - BingAdsApi::Errors::ReportError if server-side error occurred
+    #
+    def download_report_as_file(report_definition, path, cid = nil)
+      report_body = download_report(report_definition, cid)
+      save_to_file(report_body, path)
+      return nil
+    end
+
+    private
+
+    # Minimal set of required fields for report definition.
+    REQUIRED_FIELDS = [:selector, :report_name, :report_type, :date_range_type]
+
+    # Definition fields have to be in particular order in the XML. Here is its
+    # specification.
+    REPORT_DEFINITION_ORDER = {
+      :root => [:selector, :report_name, :report_type, :date_range_type,
+          :download_format, :include_zero_impressions],
+      :selector => [:fields, :predicates, :date_range, :ordering, :paging],
+      :predicates => [:field, :operator, :values],
+      :ordering => [:field, :sort_order],
+      :paging => [:start_index, :number_results],
+      :date_range => [:min, :max]
+    }
+
+    # Send POST request for a report and returns Response object.
+    def get_report_response(report_definition, cid)
+      definition_text = get_report_definition_text(report_definition)
+      data = '__rdxml=%s' % CGI.escape(definition_text)
+      url = @api.api_config.adhoc_report_download_url(
+          @api.config.read('service.environment'), @version)
+      headers = get_report_request_headers(url, cid)
+      log_request(url, headers, definition_text)
+      response = AdsCommonForBingAds::Http.post_response(url, data, @api.config, headers)
+      check_for_errors(response)
+      return response
+    end
+
+    # Converts passed object to XML text. Currently support String (no changes)
+    # and Hash (renders XML).
+    def get_report_definition_text(report_definition)
+      return case report_definition
+        when String then report_definition
+        when Hash then report_definition_to_xml(report_definition)
+        else
+          raise BingAdsApi::Errors::InvalidReportDefinitionError,
+              'Unknown object for report definition: %s' %
+              report_definition.class
+      end
+    end
+
+    # Prepares headers for report request.
+    def get_report_request_headers(url, cid)
+      @header_handler ||= BingAdsApi::ReportHeaderHandler.new(
+          @api.credential_handler, @api.get_auth_handler(), @api.config)
+      return @header_handler.headers(url, cid)
+    end
+
+    # Saves raw data to a file.
+    def save_to_file(data, path)
+      open(path, 'wb') { |file| file.write(data) } if path
+    end
+
+    # Logs the request on debug level.
+    def log_request(url, headers, body)
+      logger = @api.logger
+      logger.debug("Report request to: '%s'" % url)
+      logger.debug('HTTP headers: [%s]' %
+          (headers.map { |k, v| [k, v].join(': ') }.join(', ')))
+      logger.debug(body)
+    end
+
+    # Checks downloaded data for error signature. Raises ReportError if it
+    # detects an error.
+    def check_for_errors(response)
+      # Check for error in body.
+      report_body = response.body
+      if report_body and
+          ((RUBY_VERSION < '1.9.1') or report_body.valid_encoding?)
+        error_message_regex = '^!!!(-?\d+)\|\|\|(-?\d+)\|\|\|(.*)\?\?\?'
+        data = report_body.slice(0, 1024)
+        matches = data.match(error_message_regex)
+        if matches
+          message = (matches[3].nil?) ? data : matches[3]
+          raise BingAdsApi::Errors::ReportError.new(response.code,
+              'Report download error occured: %s' % message)
+        end
+      end
+      # Check for error code.
+      unless response.code == 200
+        raise BingAdsApi::Errors::ReportError.new(response.code,
+            'Report download error occured, http code: %d, body: %s' %
+            [response.code, response.body])
+      end
+      return nil
+    end
+
+    # Renders a report definition hash into XML text.
+    def report_definition_to_xml(report_definition)
+      check_report_definition_hash(report_definition)
+      add_report_definition_hash_order(report_definition)
+      return Gyoku.xml({:report_definition => report_definition})
+    end
+
+    # Checks if the report definition looks correct.
+    def check_report_definition_hash(report_definition)
+      # Minimal set of fields required.
+      REQUIRED_FIELDS.each do |field|
+        unless report_definition.include?(field)
+          raise BingAdsApi::Errors::InvalidReportDefinitionError,
+              "Required field '%s' is missing in the definition" % field
+        end
+      end
+      # Fields list is also required.
+      unless report_definition[:selector].include?(:fields)
+        raise BingAdsApi::Errors::InvalidReportDefinitionError,
+            'Fields list is required'
+      end
+      # 'Fields' must be an Array.
+      unless report_definition[:selector][:fields].kind_of?(Array)
+        raise BingAdsApi::Errors::InvalidReportDefinitionError,
+            'Fields list must be an array'
+      end
+      # We should request at least one field.
+      if report_definition[:selector][:fields].empty?
+        raise BingAdsApi::Errors::InvalidReportDefinitionError,
+            'At least one field needs to be requested'
+      end
+    end
+
+    # Adds fields order hint to generator based on specification.
+    def add_report_definition_hash_order(node, name = :root)
+      def_order = REPORT_DEFINITION_ORDER[name]
+      var_order = def_order.reject { |field| !node.include?(field) }
+      node.keys.each do |key|
+        if REPORT_DEFINITION_ORDER.include?(key)
+          case node[key]
+            when Hash
+              add_report_definition_hash_order(node[key], key)
+            when Array
+              node[key].each do |item|
+                add_report_definition_hash_order(item, key)
+              end
+          end
+        end
+      end
+      node[:order!] = var_order
+      return nil
+    end
+  end
+end

data/lib/bing_ads_api/v8/ad_intelligence_service.rb

@@ -0,0 +1,86 @@
+# Encoding: utf-8
+#
+# This is auto-generated code, changes will be overwritten.
+#
+# Copyright:: Copyright 2012, Google Inc. All Rights Reserved.
+# License:: Licensed under the Apache License, Version 2.0.
+#
+# Code generated by AdsCommon library 0.7.3 on 2012-07-04 16:49:50.
+
+require 'ads_common_for_bing_ads/savon_service'
+require 'bing_ads_api/v8/ad_intelligence_service_registry'
+
+module BingAdsApi; module V8; module AdIntelligenceService
+  class AdIntelligenceService < AdsCommonForBingAds::SavonService
+    def initialize(config, endpoint)
+      namespace = 'https://adcenter.microsoft.com/v8'
+      super(config, endpoint, namespace, :v8)
+    end
+
+    def get_publisher_keyword_performance(*args, &block)
+      return execute_action('get_publisher_keyword_performance', args, &block)
+    end
+
+    def suggest_keywords_for_url(*args, &block)
+      return execute_action('suggest_keywords_for_url', args, &block)
+    end
+
+    def get_estimated_bid_by_keyword_ids(*args, &block)
+      return execute_action('get_estimated_bid_by_keyword_ids', args, &block)
+    end
+
+    def get_estimated_position_by_keyword_ids(*args, &block)
+      return execute_action('get_estimated_position_by_keyword_ids', args, &block)
+    end
+
+    def get_estimated_bid_by_keywords(*args, &block)
+      return execute_action('get_estimated_bid_by_keywords', args, &block)
+    end
+
+    def get_estimated_position_by_keywords(*args, &block)
+      return execute_action('get_estimated_position_by_keywords', args, &block)
+    end
+
+    def get_historical_search_count(*args, &block)
+      return execute_action('get_historical_search_count', args, &block)
+    end
+
+    def get_historical_search_count_by_device(*args, &block)
+      return execute_action('get_historical_search_count_by_device', args, &block)
+    end
+
+    def get_historical_keyword_performance(*args, &block)
+      return execute_action('get_historical_keyword_performance', args, &block)
+    end
+
+    def get_historical_keyword_performance_by_device(*args, &block)
+      return execute_action('get_historical_keyword_performance_by_device', args, &block)
+    end
+
+    def suggest_keywords_from_existing_keywords(*args, &block)
+      return execute_action('suggest_keywords_from_existing_keywords', args, &block)
+    end
+
+    def get_keyword_locations(*args, &block)
+      return execute_action('get_keyword_locations', args, &block)
+    end
+
+    def get_keyword_categories(*args, &block)
+      return execute_action('get_keyword_categories', args, &block)
+    end
+
+    def get_keyword_demographics(*args, &block)
+      return execute_action('get_keyword_demographics', args, &block)
+    end
+
+    private
+
+    def get_service_registry()
+      return AdIntelligenceServiceRegistry
+    end
+
+    def get_module()
+      return BingAdsApi::V8::AdIntelligenceService
+    end
+  end
+end; end; end

data/lib/bing_ads_api/v8/ad_intelligence_service_registry.rb

@@ -0,0 +1,30 @@
+# Encoding: utf-8
+#
+# This is auto-generated code, changes will be overwritten.
+#
+# Copyright:: Copyright 2012, Google Inc. All Rights Reserved.
+# License:: Licensed under the Apache License, Version 2.0.
+#
+# Code generated by AdsCommon library 0.7.3 on 2012-07-04 16:49:50.
+
+require 'bing_ads_api/errors'
+
+module BingAdsApi; module V8; module AdIntelligenceService
+  class AdIntelligenceServiceRegistry
+    ADINTELLIGENCESERVICE_METHODS = {:get_publisher_keyword_performance=>{:input=>{:name=>"get_publisher_keyword_performance_request", :fields=>[]}, :output=>{:name=>"get_publisher_keyword_performance_response", :fields=>[]}, :original_name=>"GetPublisherKeywordPerformance"}, :suggest_keywords_for_url=>{:input=>{:name=>"suggest_keywords_for_url_request", :fields=>[]}, :output=>{:name=>"suggest_keywords_for_url_response", :fields=>[]}, :original_name=>"SuggestKeywordsForUrl"}, :get_estimated_bid_by_keyword_ids=>{:input=>{:name=>"get_estimated_bid_by_keyword_ids_request", :fields=>[]}, :output=>{:name=>"get_estimated_bid_by_keyword_ids_response", :fields=>[]}, :original_name=>"GetEstimatedBidByKeywordIds"}, :get_estimated_position_by_keyword_ids=>{:input=>{:name=>"get_estimated_position_by_keyword_ids_request", :fields=>[]}, :output=>{:name=>"get_estimated_position_by_keyword_ids_response", :fields=>[]}, :original_name=>"GetEstimatedPositionByKeywordIds"}, :get_estimated_bid_by_keywords=>{:input=>{:name=>"get_estimated_bid_by_keywords_request", :fields=>[]}, :output=>{:name=>"get_estimated_bid_by_keywords_response", :fields=>[]}, :original_name=>"GetEstimatedBidByKeywords"}, :get_estimated_position_by_keywords=>{:input=>{:name=>"get_estimated_position_by_keywords_request", :fields=>[]}, :output=>{:name=>"get_estimated_position_by_keywords_response", :fields=>[]}, :original_name=>"GetEstimatedPositionByKeywords"}, :get_historical_search_count=>{:input=>{:name=>"get_historical_search_count_request", :fields=>[]}, :output=>{:name=>"get_historical_search_count_response", :fields=>[]}, :original_name=>"GetHistoricalSearchCount"}, :get_historical_search_count_by_device=>{:input=>{:name=>"get_historical_search_count_by_device_request", :fields=>[]}, :output=>{:name=>"get_historical_search_count_by_device_response", :fields=>[]}, :original_name=>"GetHistoricalSearchCountByDevice"}, :get_historical_keyword_performance=>{:input=>{:name=>"get_historical_keyword_performance_request", :fields=>[]}, :output=>{:name=>"get_historical_keyword_performance_response", :fields=>[]}, :original_name=>"GetHistoricalKeywordPerformance"}, :get_historical_keyword_performance_by_device=>{:input=>{:name=>"get_historical_keyword_performance_by_device_request", :fields=>[]}, :output=>{:name=>"get_historical_keyword_performance_by_device_response", :fields=>[]}, :original_name=>"GetHistoricalKeywordPerformanceByDevice"}, :suggest_keywords_from_existing_keywords=>{:input=>{:name=>"suggest_keywords_from_existing_keywords_request", :fields=>[]}, :output=>{:name=>"suggest_keywords_from_existing_keywords_response", :fields=>[]}, :original_name=>"SuggestKeywordsFromExistingKeywords"}, :get_keyword_locations=>{:input=>{:name=>"get_keyword_locations_request", :fields=>[]}, :output=>{:name=>"get_keyword_locations_response", :fields=>[]}, :original_name=>"GetKeywordLocations"}, :get_keyword_categories=>{:input=>{:name=>"get_keyword_categories_request", :fields=>[]}, :output=>{:name=>"get_keyword_categories_response", :fields=>[]}, :original_name=>"GetKeywordCategories"}, :get_keyword_demographics=>{:input=>{:name=>"get_keyword_demographics_request", :fields=>[]}, :output=>{:name=>"get_keyword_demographics_response", :fields=>[]}, :original_name=>"GetKeywordDemographics"}}
+    ADINTELLIGENCESERVICE_TYPES = {}
+    ADINTELLIGENCESERVICE_NAMESPACES = []
+
+    def self.get_method_signature(method_name)
+      return ADINTELLIGENCESERVICE_METHODS[method_name.to_sym]
+    end
+
+    def self.get_type_signature(type_name)
+      return ADINTELLIGENCESERVICE_TYPES[type_name.to_sym]
+    end
+
+    def self.get_namespace(index)
+      return ADINTELLIGENCESERVICE_NAMESPACES[index]
+    end
+  end
+end; end; end

data/lib/bing_ads_api/v8/administration_service.rb

@@ -0,0 +1,38 @@
+# Encoding: utf-8
+#
+# This is auto-generated code, changes will be overwritten.
+#
+# Copyright:: Copyright 2012, Google Inc. All Rights Reserved.
+# License:: Licensed under the Apache License, Version 2.0.
+#
+# Code generated by AdsCommon library 0.7.3 on 2012-07-04 16:49:52.
+
+require 'ads_common_for_bing_ads/savon_service'
+require 'bing_ads_api/v8/administration_service_registry'
+
+module BingAdsApi; module V8; module AdministrationService
+  class AdministrationService < AdsCommonForBingAds::SavonService
+    def initialize(config, endpoint)
+      namespace = 'https://adcenter.microsoft.com/v8'
+      super(config, endpoint, namespace, :v8)
+    end
+
+    def get_assigned_quota(*args, &block)
+      return execute_action('get_assigned_quota', args, &block)
+    end
+
+    def get_remaining_quota(*args, &block)
+      return execute_action('get_remaining_quota', args, &block)
+    end
+
+    private
+
+    def get_service_registry()
+      return AdministrationServiceRegistry
+    end
+
+    def get_module()
+      return BingAdsApi::V8::AdministrationService
+    end
+  end
+end; end; end

data/lib/bing_ads_api/v8/administration_service_registry.rb

@@ -0,0 +1,30 @@
+# Encoding: utf-8
+#
+# This is auto-generated code, changes will be overwritten.
+#
+# Copyright:: Copyright 2012, Google Inc. All Rights Reserved.
+# License:: Licensed under the Apache License, Version 2.0.
+#
+# Code generated by AdsCommon library 0.7.3 on 2012-07-04 16:49:52.
+
+require 'bing_ads_api/errors'
+
+module BingAdsApi; module V8; module AdministrationService
+  class AdministrationServiceRegistry
+    ADMINISTRATIONSERVICE_METHODS = {:get_assigned_quota=>{:input=>{:name=>"get_assigned_quota_request", :fields=>[]}, :output=>{:name=>"get_assigned_quota_response", :fields=>[]}, :original_name=>"GetAssignedQuota"}, :get_remaining_quota=>{:input=>{:name=>"get_remaining_quota_request", :fields=>[]}, :output=>{:name=>"get_remaining_quota_response", :fields=>[]}, :original_name=>"GetRemainingQuota"}}
+    ADMINISTRATIONSERVICE_TYPES = {}
+    ADMINISTRATIONSERVICE_NAMESPACES = []
+
+    def self.get_method_signature(method_name)
+      return ADMINISTRATIONSERVICE_METHODS[method_name.to_sym]
+    end
+
+    def self.get_type_signature(type_name)
+      return ADMINISTRATIONSERVICE_TYPES[type_name.to_sym]
+    end
+
+    def self.get_namespace(index)
+      return ADMINISTRATIONSERVICE_NAMESPACES[index]
+    end
+  end
+end; end; end

data/lib/bing_ads_api/v8/bulk_service.rb

@@ -0,0 +1,42 @@
+# Encoding: utf-8
+#
+# This is auto-generated code, changes will be overwritten.
+#
+# Copyright:: Copyright 2012, Google Inc. All Rights Reserved.
+# License:: Licensed under the Apache License, Version 2.0.
+#
+# Code generated by AdsCommon library 0.7.3 on 2012-07-04 16:49:53.
+
+require 'ads_common_for_bing_ads/savon_service'
+require 'bing_ads_api/v8/bulk_service_registry'
+
+module BingAdsApi; module V8; module BulkService
+  class BulkService < AdsCommonForBingAds::SavonService
+    def initialize(config, endpoint)
+      namespace = 'https://adcenter.microsoft.com/v8'
+      super(config, endpoint, namespace, :v8)
+    end
+
+    def download_campaigns_by_account_ids(*args, &block)
+      return execute_action('download_campaigns_by_account_ids', args, &block)
+    end
+
+    def download_campaigns_by_campaign_ids(*args, &block)
+      return execute_action('download_campaigns_by_campaign_ids', args, &block)
+    end
+
+    def get_download_status(*args, &block)
+      return execute_action('get_download_status', args, &block)
+    end
+
+    private
+
+    def get_service_registry()
+      return BulkServiceRegistry
+    end
+
+    def get_module()
+      return BingAdsApi::V8::BulkService
+    end
+  end
+end; end; end