google-adwords-api 0.13.0 → 0.13.1

data/lib/adwords_api/report_utils.rb~

@@ -1,283 +0,0 @@
-# Encoding: utf-8
-#
-# Author:: api.dklimkin@gmail.com (Danial Klimkin)
-#
-# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
-#
-# License:: Licensed under the Apache License, Version 2.0 (the "License");
-#           you may not use this file except in compliance with the License.
-#           You may obtain a copy of the License at
-#
-#           http://www.apache.org/licenses/LICENSE-2.0
-#
-#           Unless required by applicable law or agreed to in writing, software
-#           distributed under the License is distributed on an "AS IS" BASIS,
-#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-#           implied.
-#           See the License for the specific language governing permissions and
-#           limitations under the License.
-#
-# Contains utility methods specific to reporting.
-
-require 'cgi'
-require 'gyoku'
-require 'nori'
-
-require 'ads_common/http'
-require 'adwords_api/errors'
-require 'adwords_api/report_header_handler'
-
-module AdwordsApi
-  class ReportUtils
-    # Default constructor.
-    #
-    # Args:
-    # - api: AdwordsApi 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:
-    # - AdwordsApi::Errors::InvalidReportDefinitionError if the report
-    #   definition is invalid
-    # - AdwordsApi::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:
-    # - AdwordsApi::Errors::InvalidReportDefinitionError if the report
-    #   definition is invalid
-    # - AdwordsApi::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
-
-    # Downloads and returns a report with AWQL.
-    #
-    # Args:
-    # - report_query: query for the report as string
-    # - format: format for the report as string
-    # - cid: optional customer ID to run report against
-    #
-    # Returns:
-    # - report body
-    #
-    # Raises:
-    # - AdwordsApi::Errors::ReportError if a server-side error has occurred
-    #
-    def download_report_with_awql(report_query, format, cid = nil)
-      return get_report_response_with_awql(report_query, format, cid).body
-    end
-
-    # Downloads a report with AWQL and saves it to a file.
-    #
-    # Args:
-    # - report_query: query for the report as string
-    # - format: format for the report as string
-    # - path: path to save report to
-    # - cid: optional customer ID to run report against
-    #
-    # Returns:
-    # - nil
-    #
-    # Raises:
-    # - AdwordsApi::Errors::ReportError if server-side error occurred
-    #
-    def download_report_as_file_with_awql(report_query, format, path, cid = nil)
-      report_body = download_report_with_awql(report_query, format, 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)
-      return make_adhoc_request(data, cid)
-    end
-
-    # Send POST request for a report with AWQL and returns Response object.
-    def get_report_response_with_awql(report_query, format, cid)
-      data = '__rdquery=%s&__fmt=%s' %
-          [CGI.escape(report_query), CGI.escape(format)]
-      return make_adhoc_request(data, cid)
-    end
-
-    # Makes request and AdHoc service and returns response.
-    def make_adhoc_request(data, cid)
-      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, data)
-      response = AdsCommon::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 AdwordsApi::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 ||= AdwordsApi::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 code.
-      if response.code != 200
-        # Check for error in body.
-        report_body = response.body
-        check_for_xml_error(report_body, response.code)
-        # No XML error found nor raised, falling back to a default message.
-        raise AdwordsApi::Errors::ReportError.new(response.code,
-            'HTTP code: %d, body: %s' % [response.code, response.body])
-      end
-      return nil
-    end
-
-    # Checks for an XML error in the response body and raises an exception if
-    # it was found.
-    def check_for_xml_error(report_body, response_code)
-      error_response = Nori.parse(report_body)
-      if error_response.include?(:report_download_error) and
-          error_response[:report_download_error].include?(:api_error)
-        api_error = error_response[:report_download_error][:api_error]
-        raise AdwordsApi::Errors::ReportXmlError.new(response_code,
-            api_error[:type], api_error[:trigger], api_error[:field_path])
-      end
-    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 AdwordsApi::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 AdwordsApi::Errors::InvalidReportDefinitionError,
-            'Fields list is required'
-      end
-      # 'Fields' must be an Array.
-      unless report_definition[:selector][:fields].kind_of?(Array)
-        raise AdwordsApi::Errors::InvalidReportDefinitionError,
-            'Fields list must be an array'
-      end
-      # We should request at least one field.
-      if report_definition[:selector][:fields].empty?
-        raise AdwordsApi::Errors::InvalidReportDefinitionError,
-            'At least one field needs to be requested'
-      end
-      # returnMoneyInMicros option is no longer supported as of v201406
-      if report_definition.include?(:return_money_in_micros) &&
-          @version != :v201402
-        raise AdwordsApi::Errors::InvalidReportDefinitionError,
-            'returnMoneyInMicros was sunset as of v201406. ' +
-            'See the migration guide for info:' + 
-            'https://developers.google.com/adwords/api/docs/' +
-            'guides/migration/v201406'
-      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/adwords_api/version.rb~

@@ -1,26 +0,0 @@
-# Encoding: utf-8
-#
-# Authors:: api.dklimkin@gmail.com (Danial Klimkin)
-#
-# Copyright:: Copyright 2012, Google Inc. All Rights Reserved.
-#
-# License:: Licensed under the Apache License, Version 2.0 (the "License");
-#           you may not use this file except in compliance with the License.
-#           You may obtain a copy of the License at
-#
-#           http://www.apache.org/licenses/LICENSE-2.0
-#
-#           Unless required by applicable law or agreed to in writing, software
-#           distributed under the License is distributed on an "AS IS" BASIS,
-#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-#           implied.
-#           See the License for the specific language governing permissions and
-#           limitations under the License.
-#
-# Module to keep the current library version.
-
-module AdwordsApi
-  module ApiConfig
-    CLIENT_LIB_VERSION = '0.12.1'
-  end
-end

data/test/adwords_api/test_adwords_api.rb~

@@ -1,114 +0,0 @@
-#!/usr/bin/env ruby
-# Encoding: utf-8
-#
-# Author:: api.dklimkin@gmail.com (Danial Klimkin)
-#
-# Copyright:: Copyright 2012, Google Inc. All Rights Reserved.
-#
-# License:: Licensed under the Apache License, Version 2.0 (the "License");
-#           you may not use this file except in compliance with the License.
-#           You may obtain a copy of the License at
-#
-#           http://www.apache.org/licenses/LICENSE-2.0
-#
-#           Unless required by applicable law or agreed to in writing, software
-#           distributed under the License is distributed on an "AS IS" BASIS,
-#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-#           implied.
-#           See the License for the specific language governing permissions and
-#           limitations under the License.
-#
-# Tests the AdWords API class features.
-
-require 'test/unit'
-
-require 'ads_common/config'
-require 'ads_common/api_config'
-require 'adwords_api'
-
-
-class LoggerStub
-  attr_reader :last_warning
-  def warn(message)
-    @last_warning = message
-  end
-end
-
-class TestAdwordsApi < Test::Unit::TestCase
-
-  API_VERSION = :v201406
-
-  def setup()
-    @logger = LoggerStub.new
-  end
-
-  def test_initialize()
-    assert_nothing_raised do
-      adwords_api = AdwordsApi::Api.new({})
-    end
-  end
-
-  def test_api_config()
-    assert_nothing_raised do
-      adwords_api = AdwordsApi::Api.new({})
-      api_config = adwords_api.api_config()
-      assert_not_nil(api_config)
-      assert_kind_of(AdsCommon::ApiConfig, api_config)
-    end
-  end
-
-  def test_use_mcc()
-    adwords_api = AdwordsApi::Api.new({})
-    adwords_api.use_mcc = false
-    assert(!adwords_api.use_mcc)
-    adwords_api.use_mcc do
-      assert(adwords_api.use_mcc)
-    end
-  end
-
-  def test_validate_only()
-    adwords_api = AdwordsApi::Api.new({})
-    adwords_api.validate_only = false
-    assert(!adwords_api.validate_only)
-    adwords_api.validate_only do
-      assert(adwords_api.validate_only)
-    end
-  end
-
-  def test_partial_failure()
-    adwords_api = AdwordsApi::Api.new({})
-    adwords_api.partial_failure = false
-    assert(!adwords_api.partial_failure)
-    adwords_api.partial_failure do
-      assert(adwords_api.partial_failure)
-    end
-  end
-
-  def test_no_sandbox_env()
-    adwords_api = AdwordsApi::Api.new({
-      :service => {:environment => 'SANDBOX'}
-    })
-    assert_raise(AdsCommon::Errors::Error) do
-      service = adwords_api.service(:ManagedCustomerService, API_VERSION)
-    end
-  end
-
-  def test_prod_env()
-    adwords_api = AdwordsApi::Api.new({
-      :library => {:logger => @logger},
-      :service => {:environment => 'PRODUCTION'}
-    })
-    service = adwords_api.service(:ManagedCustomerService, API_VERSION)
-  end
-
-  def test_clientlogin_error()
-    adwords_api = AdwordsApi::Api.new({
-      :library => {:logger => @logger},
-      :authentication => {:method => 'ClientLogin'},
-      :service => {:environment => 'PRODUCTION'}
-    })
-    assert_raise do
-      service = adwords_api.service(:CampaignService, API_VERSION)
-    end
-  end
-end

data/test/adwords_api/test_report_utils.rb~

@@ -1,216 +0,0 @@
-#!/usr/bin/env ruby
-# Encoding: utf-8
-#
-# Author:: api.dklimkin@gmail.com (Danial Klimkin)
-#
-# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
-#
-# License:: Licensed under the Apache License, Version 2.0 (the "License");
-#           you may not use this file except in compliance with the License.
-#           You may obtain a copy of the License at
-#
-#           http://www.apache.org/licenses/LICENSE-2.0
-#
-#           Unless required by applicable law or agreed to in writing, software
-#           distributed under the License is distributed on an "AS IS" BASIS,
-#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-#           implied.
-#           See the License for the specific language governing permissions and
-#           limitations under the License.
-#
-# Tests report utils.
-
-require 'test/unit'
-
-require 'adwords_api'
-
-# Overriding default access levels to public for tests.
-module AdwordsApi
-  class ReportUtils
-    public :check_for_errors
-    public :check_for_xml_error
-    public :add_report_definition_hash_order
-    public :check_report_definition_hash
-  end
-end
-
-# Stub class for HTTP response.
-class ResponseStub
-  attr_reader :code
-  attr_reader :body
-
-  def initialize(code, body)
-    @code, @body = code, body
-  end
-end
-
-XML_REPLY = {
-  :reply => '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><reportDownloadError><ApiError><type>ReportDefinitionError.INVALID_FIELD_NAME_FOR_REPORT</type><trigger>foo</trigger><fieldPath>bar</fieldPath></ApiError></reportDownloadError>',
-  :type => 'ReportDefinitionError.INVALID_FIELD_NAME_FOR_REPORT',
-  :trigger => 'foo',
-  :field_path => 'bar'
-}
-
-VALID_REPORT = '"Custom ADGROUP_PERFORMANCE_REPORT (Oct 20, 2011-Oct 26, 2011)"\nCampaign ID,Ad group ID,Impressions,Clicks,Cost\nTotal, --,0,0,0.00'
-GZIPPED_REPORT = "\x1F\x8B\b\x00\x00\x00\x00\x00\x00\x00Sr.-.\xC9\xCFUptq\x0F\xF2\x0F\r\x88\x0Fp\rr\xF3\x0F\xF2u\xF4sv\x8D\x0Fr\r\xF0\x0F\nQ\xD0pIMV0\xD2Q0204\xD4\x05\xB1- lM%.\xE7\xC4\xDC\x82\xC4\xCC\xF4<\x05O\x17\x1D\xC7\x14\x85\xF4\xA2\xFC\xD2\x02\x10\xDB3\xB7\xA0(\xB5\xB883?\xAFX\xC79'39\eH\xE5\x17\x97p\x85\xE4\x97$\xE6\xE8(\xE8\xEA\xEA\x18\x80\xA0\x9E\x81\x01\x17\x00\xBE\x1D\xBE\xAD\x81\x00\x00\x00"
-
-class TestReportUtils < Test::Unit::TestCase
-
-  API_VERSION = :v201406
-
-  # Initialize tests.
-  def setup()
-    @api = AdwordsApi::Api.new
-    @report_utils = @api.report_utils(API_VERSION)
-  end
-
-  # Testing HTTP code 400.
-  def test_check_for_errors_400()
-    begin
-      response = ResponseStub.new(400, XML_REPLY[:reply])
-      @report_utils.check_for_errors(response)
-      assert(false, 'No exception thrown for code 400')
-    rescue AdwordsApi::Errors::ReportXmlError => e
-      assert_equal(400, e.http_code)
-      assert_equal(XML_REPLY[:type], e.type)
-      assert_equal(XML_REPLY[:trigger], e.trigger)
-      assert_equal(XML_REPLY[:field_path], e.field_path)
-      assert_not_nil(e.message)
-    end
-  end
-
-  # Testing HTTP code 500.
-  def test_check_for_errors_500()
-    begin
-      response = ResponseStub.new(500, nil)
-      @report_utils.check_for_errors(response)
-      assert(false, 'No exception thrown for code 500')
-    rescue AdwordsApi::Errors::ReportError => e
-      assert_equal(500, e.http_code)
-    end
-  end
-
-  # Testing HTTP code 200 with success.
-  def test_check_for_errors_200_success()
-    response = ResponseStub.new(200, VALID_REPORT)
-    assert_nothing_raised do
-      @report_utils.check_for_errors(response)
-    end
-  end
-
-  # Testing correct gzipped reply.
-  def test_gzipped_data()
-    report = (RUBY_VERSION >= '1.9.1') ?
-        GZIPPED_REPORT.force_encoding('UTF-8') : GZIPPED_REPORT
-    response = ResponseStub.new(200, report)
-    assert_nothing_raised do
-      @report_utils.check_for_errors(response)
-    end
-  end
-
-  # Tests generated hash order for root (complete set).
-  def test_add_report_definition_hash_order_root1()
-    node = {
-      :include_zero_impressions => false,
-      :download_format => 'CSV',
-      :report_type => 'CRITERIA_PERFORMANCE_REPORT',
-      :selector => {},
-      :report_name => 'report_name',
-      :date_range_type => 'LAST_7_DAYS'
-    }
-    expected = [:selector, :report_name, :report_type, :date_range_type,
-                :download_format, :include_zero_impressions]
-    @report_utils.add_report_definition_hash_order(node)
-    assert_not_nil(node[:order!])
-    assert_equal(expected, node[:order!])
-  end
-
-  # Tests generated hash order for root (incomplete set).
-  def test_add_report_definition_hash_order_root2()
-    node = {
-      :download_format => 'CSV',
-      :report_type => 'CRITERIA_PERFORMANCE_REPORT',
-      :selector => {},
-      :report_name => 'report_name',
-      :date_range_type => 'LAST_7_DAYS'
-    }
-    expected = [:selector, :report_name, :report_type, :date_range_type,
-                :download_format]
-    @report_utils.add_report_definition_hash_order(node)
-    assert_not_nil(node[:order!])
-    assert_equal(expected, node[:order!])
-  end
-
-  # Tests generated hash order for whole structure.
-  def test_add_report_definition_hash_order_deep()
-    node = {
-      :report_name => 'report_name',
-      :report_type => 'CRITERIA_PERFORMANCE_REPORT',
-      :selector => {
-        :date_range => {:max => '20120405', :min => '20120405'},
-        :predicates => {:operator => 'IN', :field => 'S', :values => ['A']},
-        :fields => ['CampaignId']
-      },
-      :include_zero_impressions => false,
-      :download_format => 'CSV',
-      :date_range_type => 'LAST_7_DAYS'
-    }
-    expected1 = [:selector, :report_name, :report_type, :date_range_type,
-                 :download_format, :include_zero_impressions]
-    expected2 = [:fields, :predicates, :date_range]
-    expected3 = [:min, :max]
-    expected4 = [:field, :operator, :values]
-
-    @report_utils.add_report_definition_hash_order(node)
-    assert_not_nil(node[:order!])
-    assert_not_nil(node[:selector][:order!])
-    assert_not_nil(node[:selector][:date_range][:order!])
-    assert_not_nil(node[:selector][:predicates][:order!])
-
-    assert_equal(expected1, node[:order!])
-    assert_equal(expected2, node[:selector][:order!])
-    assert_equal(expected3, node[:selector][:date_range][:order!])
-    assert_equal(expected4, node[:selector][:predicates][:order!])
-  end
-
-  # Testing check_for_xml_error.
-  def check_for_xml_error()
-    begin
-      @report_utils.check_for_xml_error(XML_REPLY[:reply], 42)
-      assert(false, 'No exception thrown for code 42')
-    rescue AdwordsApi::Errors::ReportXmlError => e
-      assert_equal(42, e.http_code)
-      assert_equal(XML_REPLY[:type], e.type)
-      assert_equal(XML_REPLY[:trigger], e.trigger)
-      assert_equal(XML_REPLY[:field_path], e.field_path)
-      assert_not_nil(e.message)
-    end
-  end
-
-  def test_return_money_in_micros_removal()
-    node = {
-      :report_name => 'report_name',
-      :report_type => 'CAMPAIGN_PERFORMANCE_REPORT',
-      :selector => {
-        :date_range => {:max=> '20120405', :min => '20120405'},
-        :predicates => {:operator => 'IN', :field => 'S', :values => ['A']},
-        :fields => ['CampaignId']
-      },
-      :download_format => 'CSV',
-      :date_range_type => 'LAST_7_DAYS'
-    }
-    assert_nothing_raised do
-      @report_utils.check_report_definition_hash(node)
-    end
-
-    node[:return_money_in_micros] = true
-    assert_raise AdwordsApi::Errors::InvalidReportDefinitionError do
-      @report_utils.check_report_definition_hash(node)
-    end
-
-    node[:return_money_in_micros] = false
-    assert_raise AdwordsApi::Errors::InvalidReportDefinitionError do
-      @report_utils.check_report_definition_hash(node)
-    end
-  end
-end