bing_ads_api 0.0.5

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/v7/administration_service.rb

@@ -0,0 +1,37 @@
+# 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:14.
+
+require 'bing_ads_api/v7/administration_service_registry'
+
+module BingAdsApi; module V7; module AdministrationService
+  class AdministrationService < AdsCommonForBingAds::SavonService
+    def initialize(config, endpoint)
+      namespace = 'https://adcenter.microsoft.com/v7'
+      super(config, endpoint, namespace, :v7)
+    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::V7::AdministrationService
+    end
+  end
+end; end; end

data/lib/bing_ads_api/v7/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:14.
+
+require 'bing_ads_api/errors'
+
+module BingAdsApi; module V7; 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/v7/campaign_management_service.rb

@@ -0,0 +1,398 @@
+# 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:16.
+
+require 'ads_common_for_bing_ads/savon_service'
+require 'bing_ads_api/v7/campaign_management_service_registry'
+
+module BingAdsApi; module V7; module CampaignManagementService
+  class CampaignManagementService < AdsCommonForBingAds::SavonService
+    def initialize(config, endpoint)
+      namespace = 'https://adcenter.microsoft.com/v7'
+      super(config, endpoint, namespace, :v7)
+    end
+
+    def set_networks_to_ad_groups(*args, &block)
+      return execute_action('set_networks_to_ad_groups', args, &block)
+    end
+
+    def add_goals(*args, &block)
+      return execute_action('add_goals', args, &block)
+    end
+
+    def update_goals(*args, &block)
+      return execute_action('update_goals', args, &block)
+    end
+
+    def get_goals(*args, &block)
+      return execute_action('get_goals', args, &block)
+    end
+
+    def delete_goals(*args, &block)
+      return execute_action('delete_goals', args, &block)
+    end
+
+    def set_analytics_type(*args, &block)
+      return execute_action('set_analytics_type', args, &block)
+    end
+
+    def get_analytics_type(*args, &block)
+      return execute_action('get_analytics_type', args, &block)
+    end
+
+    def get_account_migration_statuses(*args, &block)
+      return execute_action('get_account_migration_statuses', args, &block)
+    end
+
+    def pause_ads(*args, &block)
+      return execute_action('pause_ads', args, &block)
+    end
+
+    def resume_ads(*args, &block)
+      return execute_action('resume_ads', args, &block)
+    end
+
+    def add_keywords(*args, &block)
+      return execute_action('add_keywords', args, &block)
+    end
+
+    def delete_keywords(*args, &block)
+      return execute_action('delete_keywords', args, &block)
+    end
+
+    def get_keywords_by_editorial_status(*args, &block)
+      return execute_action('get_keywords_by_editorial_status', args, &block)
+    end
+
+    def get_keywords_by_ids(*args, &block)
+      return execute_action('get_keywords_by_ids', args, &block)
+    end
+
+    def get_keywords_by_ad_group_id(*args, &block)
+      return execute_action('get_keywords_by_ad_group_id', args, &block)
+    end
+
+    def pause_keywords(*args, &block)
+      return execute_action('pause_keywords', args, &block)
+    end
+
+    def resume_keywords(*args, &block)
+      return execute_action('resume_keywords', args, &block)
+    end
+
+    def update_keywords(*args, &block)
+      return execute_action('update_keywords', args, &block)
+    end
+
+    def get_keyword_estimates_by_bids(*args, &block)
+      return execute_action('get_keyword_estimates_by_bids', args, &block)
+    end
+
+    def add_businesses(*args, &block)
+      return execute_action('add_businesses', args, &block)
+    end
+
+    def update_businesses(*args, &block)
+      return execute_action('update_businesses', args, &block)
+    end
+
+    def delete_businesses(*args, &block)
+      return execute_action('delete_businesses', args, &block)
+    end
+
+    def get_businesses_info(*args, &block)
+      return execute_action('get_businesses_info', args, &block)
+    end
+
+    def get_businesses_by_ids(*args, &block)
+      return execute_action('get_businesses_by_ids', args, &block)
+    end
+
+    def add_site_placements(*args, &block)
+      return execute_action('add_site_placements', args, &block)
+    end
+
+    def delete_site_placements(*args, &block)
+      return execute_action('delete_site_placements', args, &block)
+    end
+
+    def get_site_placements_by_ids(*args, &block)
+      return execute_action('get_site_placements_by_ids', args, &block)
+    end
+
+    def get_site_placements_by_ad_group_id(*args, &block)
+      return execute_action('get_site_placements_by_ad_group_id', args, &block)
+    end
+
+    def pause_site_placements(*args, &block)
+      return execute_action('pause_site_placements', args, &block)
+    end
+
+    def resume_site_placements(*args, &block)
+      return execute_action('resume_site_placements', args, &block)
+    end
+
+    def update_site_placements(*args, &block)
+      return execute_action('update_site_placements', args, &block)
+    end
+
+    def get_placement_details_for_urls(*args, &block)
+      return execute_action('get_placement_details_for_urls', args, &block)
+    end
+
+    def add_behavioral_bids(*args, &block)
+      return execute_action('add_behavioral_bids', args, &block)
+    end
+
+    def delete_behavioral_bids(*args, &block)
+      return execute_action('delete_behavioral_bids', args, &block)
+    end
+
+    def get_behavioral_bids_by_ids(*args, &block)
+      return execute_action('get_behavioral_bids_by_ids', args, &block)
+    end
+
+    def get_behavioral_bids_by_ad_group_id(*args, &block)
+      return execute_action('get_behavioral_bids_by_ad_group_id', args, &block)
+    end
+
+    def pause_behavioral_bids(*args, &block)
+      return execute_action('pause_behavioral_bids', args, &block)
+    end
+
+    def resume_behavioral_bids(*args, &block)
+      return execute_action('resume_behavioral_bids', args, &block)
+    end
+
+    def update_behavioral_bids(*args, &block)
+      return execute_action('update_behavioral_bids', args, &block)
+    end
+
+    def get_custom_segments(*args, &block)
+      return execute_action('get_custom_segments', args, &block)
+    end
+
+    def add_segments(*args, &block)
+      return execute_action('add_segments', args, &block)
+    end
+
+    def delete_segments(*args, &block)
+      return execute_action('delete_segments', args, &block)
+    end
+
+    def get_segments_by_ids(*args, &block)
+      return execute_action('get_segments_by_ids', args, &block)
+    end
+
+    def get_segments(*args, &block)
+      return execute_action('get_segments', args, &block)
+    end
+
+    def set_users_to_segments(*args, &block)
+      return execute_action('set_users_to_segments', args, &block)
+    end
+
+    def delete_users_from_segment(*args, &block)
+      return execute_action('delete_users_from_segment', args, &block)
+    end
+
+    def get_normalized_strings(*args, &block)
+      return execute_action('get_normalized_strings', args, &block)
+    end
+
+    def get_keyword_editorial_reasons_by_ids(*args, &block)
+      return execute_action('get_keyword_editorial_reasons_by_ids', args, &block)
+    end
+
+    def get_ad_editorial_reasons_by_ids(*args, &block)
+      return execute_action('get_ad_editorial_reasons_by_ids', args, &block)
+    end
+
+    def get_networks_by_ad_group_ids(*args, &block)
+      return execute_action('get_networks_by_ad_group_ids', args, &block)
+    end
+
+    def add_campaigns(*args, &block)
+      return execute_action('add_campaigns', args, &block)
+    end
+
+    def get_campaigns_by_account_id(*args, &block)
+      return execute_action('get_campaigns_by_account_id', args, &block)
+    end
+
+    def get_campaigns_by_ids(*args, &block)
+      return execute_action('get_campaigns_by_ids', args, &block)
+    end
+
+    def pause_campaigns(*args, &block)
+      return execute_action('pause_campaigns', args, &block)
+    end
+
+    def resume_campaigns(*args, &block)
+      return execute_action('resume_campaigns', args, &block)
+    end
+
+    def delete_campaigns(*args, &block)
+      return execute_action('delete_campaigns', args, &block)
+    end
+
+    def update_campaigns(*args, &block)
+      return execute_action('update_campaigns', args, &block)
+    end
+
+    def get_campaigns_info_by_account_id(*args, &block)
+      return execute_action('get_campaigns_info_by_account_id', args, &block)
+    end
+
+    def get_negative_keywords_by_campaign_ids(*args, &block)
+      return execute_action('get_negative_keywords_by_campaign_ids', args, &block)
+    end
+
+    def set_negative_keywords_to_campaigns(*args, &block)
+      return execute_action('set_negative_keywords_to_campaigns', args, &block)
+    end
+
+    def add_ad_groups(*args, &block)
+      return execute_action('add_ad_groups', args, &block)
+    end
+
+    def delete_ad_groups(*args, &block)
+      return execute_action('delete_ad_groups', args, &block)
+    end
+
+    def get_ad_groups_by_ids(*args, &block)
+      return execute_action('get_ad_groups_by_ids', args, &block)
+    end
+
+    def get_ad_groups_by_campaign_id(*args, &block)
+      return execute_action('get_ad_groups_by_campaign_id', args, &block)
+    end
+
+    def pause_ad_groups(*args, &block)
+      return execute_action('pause_ad_groups', args, &block)
+    end
+
+    def resume_ad_groups(*args, &block)
+      return execute_action('resume_ad_groups', args, &block)
+    end
+
+    def submit_ad_group_for_approval(*args, &block)
+      return execute_action('submit_ad_group_for_approval', args, &block)
+    end
+
+    def update_ad_groups(*args, &block)
+      return execute_action('update_ad_groups', args, &block)
+    end
+
+    def get_ad_groups_info_by_campaign_id(*args, &block)
+      return execute_action('get_ad_groups_info_by_campaign_id', args, &block)
+    end
+
+    def get_negative_keywords_by_ad_group_ids(*args, &block)
+      return execute_action('get_negative_keywords_by_ad_group_ids', args, &block)
+    end
+
+    def set_negative_keywords_to_ad_groups(*args, &block)
+      return execute_action('set_negative_keywords_to_ad_groups', args, &block)
+    end
+
+    def add_target(*args, &block)
+      return execute_action('add_target', args, &block)
+    end
+
+    def delete_target(*args, &block)
+      return execute_action('delete_target', args, &block)
+    end
+
+    def get_target_by_ad_group_id(*args, &block)
+      return execute_action('get_target_by_ad_group_id', args, &block)
+    end
+
+    def update_target(*args, &block)
+      return execute_action('update_target', args, &block)
+    end
+
+    def add_targets_to_library(*args, &block)
+      return execute_action('add_targets_to_library', args, &block)
+    end
+
+    def update_targets_in_library(*args, &block)
+      return execute_action('update_targets_in_library', args, &block)
+    end
+
+    def delete_targets_from_library(*args, &block)
+      return execute_action('delete_targets_from_library', args, &block)
+    end
+
+    def get_targets_info_from_library(*args, &block)
+      return execute_action('get_targets_info_from_library', args, &block)
+    end
+
+    def get_targets_by_ids(*args, &block)
+      return execute_action('get_targets_by_ids', args, &block)
+    end
+
+    def set_target_to_ad_group(*args, &block)
+      return execute_action('set_target_to_ad_group', args, &block)
+    end
+
+    def delete_target_from_ad_group(*args, &block)
+      return execute_action('delete_target_from_ad_group', args, &block)
+    end
+
+    def get_targets_by_ad_group_ids(*args, &block)
+      return execute_action('get_targets_by_ad_group_ids', args, &block)
+    end
+
+    def set_target_to_campaign(*args, &block)
+      return execute_action('set_target_to_campaign', args, &block)
+    end
+
+    def delete_target_from_campaign(*args, &block)
+      return execute_action('delete_target_from_campaign', args, &block)
+    end
+
+    def get_targets_by_campaign_ids(*args, &block)
+      return execute_action('get_targets_by_campaign_ids', args, &block)
+    end
+
+    def add_ads(*args, &block)
+      return execute_action('add_ads', args, &block)
+    end
+
+    def delete_ads(*args, &block)
+      return execute_action('delete_ads', args, &block)
+    end
+
+    def get_ads_by_editorial_status(*args, &block)
+      return execute_action('get_ads_by_editorial_status', args, &block)
+    end
+
+    def get_ads_by_ids(*args, &block)
+      return execute_action('get_ads_by_ids', args, &block)
+    end
+
+    def get_ads_by_ad_group_id(*args, &block)
+      return execute_action('get_ads_by_ad_group_id', args, &block)
+    end
+
+    def update_ads(*args, &block)
+      return execute_action('update_ads', args, &block)
+    end
+
+    private
+
+    def get_service_registry()
+      return CampaignManagementServiceRegistry
+    end
+
+    def get_module()
+      return BingAdsApi::V7::CampaignManagementService
+    end
+  end
+end; end; end