google-adwords-api 0.1.0

data/lib/adwords_api/api_config.rb

@@ -0,0 +1,270 @@
+#!/usr/bin/ruby
+#
+# Authors:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# 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.
+#
+# Helper methods for loading and managing the available services in the AdWords
+# API.
+
+require 'ads_common/api_config'
+
+module AdwordsApi
+
+  # 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 = :v201101
+    DEFAULT_ENVIRONMENT = :PRODUCTION
+    LATEST_VERSION = :v201101
+
+    # Set other constants
+    API_NAME = 'AdwordsApi'
+    API_PATH = 'adwords_api'
+    CLIENT_LIB_VERSION = '0.1.0'
+
+    # Configure the services available to each version
+    @@service_config = {
+      :v13 => [:AccountService, :ReportService, :TrafficEstimatorService],
+      :v200909 => [:AdExtensionOverrideService, :AdGroupAdService,
+                   :AdGroupCriterionService, :AdGroupService, :AdParamService,
+                   :BulkMutateJobService, :CampaignAdExtensionService,
+                   :CampaignCriterionService, :CampaignService,
+                   :CampaignTargetService, :GeoLocationService, :InfoService,
+                   :TargetingIdeaService],
+      :v201003 => [:AdExtensionOverrideService, :AdGroupAdService,
+                   :AdGroupCriterionService, :AdGroupService, :AdParamService,
+                   :BidLandscapeService, :BulkMutateJobService,
+                   :CampaignAdExtensionService, :CampaignCriterionService,
+                   :CampaignService, :CampaignTargetService,
+                   :GeoLocationService, :InfoService, :MediaService,
+                   :ReportDefinitionService, :TargetingIdeaService],
+      :v201008 => [:AdExtensionOverrideService, :AdGroupAdService,
+                   :AdGroupCriterionService, :AdGroupService, :AdParamService,
+                   :AlertService, :BidLandscapeService, :BulkMutateJobService,
+                   :CampaignAdExtensionService, :CampaignCriterionService,
+                   :CampaignService, :CampaignTargetService,
+                   :CustomerSyncService, :ExperimentService,
+                   :GeoLocationService, :InfoService, :MediaService,
+                   :ReportDefinitionService, :ServicedAccountService,
+                   :TargetingIdeaService, :TrafficEstimatorService,
+                   :UserListService],
+      :v201101 => [:AdExtensionOverrideService, :AdGroupAdService,
+                   :AdGroupCriterionService, :AdGroupService, :AdParamService,
+                   :AlertService, :BulkMutateJobService,
+                   :CampaignAdExtensionService, :CampaignCriterionService,
+                   :CampaignService, :CampaignTargetService,
+                   :CustomerSyncService, :DataService, :ExperimentService,
+                   :GeoLocationService, :InfoService, :MediaService,
+                   :ReportDefinitionService, :ServicedAccountService,
+                   :TargetingIdeaService, :TrafficEstimatorService,
+                   :UserListService]
+    }
+
+    # Configure the different environments, with the base URL for each one
+    @@environment_config = {
+      :PRODUCTION => {
+        :v13 => 'https://adwords.google.com/api/adwords/',
+        :v200909 => 'https://adwords.google.com/api/adwords/',
+        :v201003 => 'https://adwords.google.com/api/adwords/',
+        :v201008 => 'https://adwords.google.com/api/adwords/',
+        :v201101 => 'https://adwords.google.com/api/adwords/'
+      },
+      :SANDBOX => {
+        :v13 => 'https://sandbox.google.com/api/adwords/',
+        :v200909 => 'https://adwords-sandbox.google.com/api/adwords/',
+        :v201003 => 'https://adwords-sandbox.google.com/api/adwords/',
+        :v201008 => 'https://adwords-sandbox.google.com/api/adwords/',
+        :v201101 => 'https://adwords-sandbox.google.com/api/adwords/'
+      }
+    }
+
+    # Configure the subdirectories for each version / service pair.
+    # A missing pair means that only the base URL is used.
+    @@subdir_config = {
+      # v13
+      [:v13, :AccountService] => '',
+      [:v13, :ReportService] => '',
+      [:v13, :TrafficEstimatorService] => '',
+      # v200909
+      [:v200909, :AdExtensionOverrideService] => 'cm/',
+      [:v200909, :AdGroupAdService] => 'cm/',
+      [:v200909, :AdGroupCriterionService] => 'cm/',
+      [:v200909, :AdGroupService] => 'cm/',
+      [:v200909, :AdParamService] => 'cm/',
+      [:v200909, :BulkMutateJobService] => 'job/',
+      [:v200909, :CampaignAdExtensionService] => 'cm/',
+      [:v200909, :CampaignCriterionService] => 'cm/',
+      [:v200909, :CampaignService] => 'cm/',
+      [:v200909, :CampaignTargetService] => 'cm/',
+      [:v200909, :GeoLocationService] => 'cm/',
+      [:v200909, :InfoService] => 'info/',
+      [:v200909, :TargetingIdeaService] => 'o/',
+      # v201003
+      [:v201003, :AdExtensionOverrideService] => 'cm/',
+      [:v201003, :AdGroupAdService] => 'cm/',
+      [:v201003, :AdGroupCriterionService] => 'cm/',
+      [:v201003, :AdGroupService] => 'cm/',
+      [:v201003, :AdParamService] => 'cm/',
+      [:v201003, :BidLandscapeService] => 'cm/',
+      [:v201003, :BulkMutateJobService] => 'job/',
+      [:v201003, :CampaignAdExtensionService] => 'cm/',
+      [:v201003, :CampaignCriterionService] => 'cm/',
+      [:v201003, :CampaignService] => 'cm/',
+      [:v201003, :CampaignTargetService] => 'cm/',
+      [:v201003, :GeoLocationService] => 'cm/',
+      [:v201003, :InfoService] => 'info/',
+      [:v201003, :MediaService] => 'cm/',
+      [:v201003, :ReportDefinitionService] => 'cm/',
+      [:v201003, :TargetingIdeaService] => 'o/',
+      # v201008
+      [:v201008, :AdExtensionOverrideService] => 'cm/',
+      [:v201008, :AdGroupAdService] => 'cm/',
+      [:v201008, :AdGroupCriterionService] => 'cm/',
+      [:v201008, :AdGroupService] => 'cm/',
+      [:v201008, :AdParamService] => 'cm/',
+      [:v201008, :AlertService] => 'mcm/',
+      [:v201008, :BidLandscapeService] => 'cm/',
+      [:v201008, :BulkMutateJobService] => 'job/',
+      [:v201008, :CampaignAdExtensionService] => 'cm/',
+      [:v201008, :CampaignCriterionService] => 'cm/',
+      [:v201008, :CampaignService] => 'cm/',
+      [:v201008, :CampaignTargetService] => 'cm/',
+      [:v201008, :CustomerSyncService] => 'ch/',
+      [:v201008, :ExperimentService] => 'cm/',
+      [:v201008, :GeoLocationService] => 'cm/',
+      [:v201008, :InfoService] => 'info/',
+      [:v201008, :MediaService] => 'cm/',
+      [:v201008, :ReportDefinitionService] => 'cm/',
+      [:v201008, :ServicedAccountService] => 'mcm/',
+      [:v201008, :TargetingIdeaService] => 'o/',
+      [:v201008, :TrafficEstimatorService] => 'o/',
+      [:v201008, :UserListService] => 'cm/',
+      # v201101
+      [:v201101, :AdExtensionOverrideService] => 'cm/',
+      [:v201101, :AdGroupAdService] => 'cm/',
+      [:v201101, :AdGroupCriterionService] => 'cm/',
+      [:v201101, :AdGroupService] => 'cm/',
+      [:v201101, :AdParamService] => 'cm/',
+      [:v201101, :AlertService] => 'mcm/',
+      [:v201101, :BulkMutateJobService] => 'job/',
+      [:v201101, :CampaignAdExtensionService] => 'cm/',
+      [:v201101, :CampaignCriterionService] => 'cm/',
+      [:v201101, :CampaignService] => 'cm/',
+      [:v201101, :CampaignTargetService] => 'cm/',
+      [:v201101, :CustomerSyncService] => 'ch/',
+      [:v201101, :DataService] => 'cm/',
+      [:v201101, :ExperimentService] => 'cm/',
+      [:v201101, :GeoLocationService] => 'cm/',
+      [:v201101, :InfoService] => 'info/',
+      [:v201101, :MediaService] => 'cm/',
+      [:v201101, :ReportDefinitionService] => 'cm/',
+      [:v201101, :ServicedAccountService] => 'mcm/',
+      [:v201101, :TargetingIdeaService] => 'o/',
+      [:v201101, :TrafficEstimatorService] => 'o/',
+      [:v201101, :UserListService] => 'cm/'
+    }
+
+    # Configure the auth servers to use for each environment
+    @@auth_server_config = {
+      :PRODUCTION => 'https://www.google.com',
+      :SANDBOX => 'https://www.google.com'
+    }
+
+    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.api_path
+      API_PATH
+    end
+
+    def self.service_config
+      @@service_config
+    end
+
+    def self.environment_config
+      @@environment_config
+    end
+
+    def self.subdir_config
+      @@subdir_config
+    end
+
+    def self.auth_server_config
+      @@auth_server_config
+    end
+
+    # Returns the full interface class name for a given service. Overriding this
+    # method from ads_common to fix odd behaviour with v13 class names.
+    #
+    # Args:
+    # - version: the API version (as an integer)
+    # - service: the service name (as a string)
+    #
+    # Returns:
+    # The full interface class name for the given service (as a string)
+    #
+    def self.interface_name(version, service)
+      version = version.to_sym
+      service = service.to_sym
+      service_str = service.to_s
+      service_str = service_str.sub(/Service$/, '') if version == :v13
+      return module_name(version, service) + "::#{service_str}Interface"
+    end
+
+    # Get the download URL for reports.
+    #
+    # Args:
+    # - environment: the service environment to be used (as a string)
+    # - version: the API version (as an integer)
+    #
+    # Returns:
+    # The endpoint URL (as a string)
+    #
+    def self.report_download_url(environment, version)
+      version = version.to_sym
+      base = get_wsdl_base(environment.to_sym, version)
+      if base
+        path = service_config[version].include?(:ReportDefinitionService) ?
+            'reportdownload' : nil
+        base += path.to_s
+      end
+      return base
+    end
+  end
+end

data/lib/adwords_api/auth/v13_login_handler.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/ruby
+#
+# Authors:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# 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.
+#
+# Handles v13 authentication.
+
+require 'ads_common/auth/base_handler'
+
+module AdwordsApi
+  module Auth
+    class V13LoginHandler < AdsCommon::Auth::BaseHandler
+
+      # Ensure that clientEmail and clientCustomerId are always present
+      def header_list(credentials)
+        creds = credentials.keys.dup
+        creds << :clientEmail unless creds.include? :clientEmail
+        creds << :clientCustomerId unless creds.include? :clientCustomerId
+      end
+    end
+  end
+end

data/lib/adwords_api/credential_handler.rb

@@ -0,0 +1,111 @@
+#!/usr/bin/ruby
+#
+# Authors:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# 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.
+#
+# AdWords-specific credential handler.
+
+require 'ads_common/credential_handler'
+require 'adwords_api/api_config'
+
+module AdwordsApi
+  class CredentialHandler < AdsCommon::CredentialHandler
+    SERVICE_NAME = 'adwords'
+
+    # Whether we're making MCC-level requests.
+    attr_accessor :use_mcc
+    # Whether we're making validate-only requests.
+    attr_accessor :validate_only
+    # Whether we're making partial failure requests.
+    attr_accessor :partial_failure
+
+    def initialize(config)
+      super
+      @use_mcc = false
+      @validate_only = false
+      @partial_failure = false
+    end
+
+    # Create the list of credentials to be used by the auth handler for header
+    # generation.
+    def credentials(version = nil)
+      validate_headers_for_server
+      result = {}
+      client_lib = 'Ruby-AwApi-%s|' % AdwordsApi::ApiConfig::CLIENT_LIB_VERSION
+      user_agent = @credentials[:user_agent]
+      user_agent = $0 if user_agent.nil?
+      user_agent = client_lib + user_agent
+      if (version == :v13)
+        result[:useragent] = user_agent
+      else
+        result[:userAgent] = user_agent
+      end
+      result[:email] = @credentials[:email]
+      result[:password] = @credentials[:password]
+      result[:developerToken] = @credentials[:developer_token]
+      unless @use_mcc
+        if @credentials[:client_email]
+          result[:clientEmail] = @credentials[:client_email]
+        elsif @credentials[:client_customer_id]
+          result[:clientCustomerId] = @credentials[:client_customer_id]
+        end
+      end
+      if version != :v13 and @validate_only
+        result[:validateOnly] = 'true'
+      end
+      if version != :v13 and @partial_failure
+        result[:partialFailure] = 'true'
+      end
+      return result
+    end
+
+    private
+
+    # Validates that the right credentials are being used for the chosen
+    # environment.
+    #
+    # Raises:
+    # Adwordsapi::Error::EnvironmentMismatchError if sandbox credentials are
+    # being used for production or vice-versa.
+    #
+    def validate_headers_for_server
+      email = @credentials[:email]
+      token = @credentials[:developer_token]
+      client = @credentials[:client_email]
+      environment = @config.read('service.environment').to_s.upcase
+
+      sandbox_token = (token =~ /#{Regexp.escape(email)}\+\+[a-zA-Z]{3}/)
+      sandbox_client = (client =~ /client_[1-5]\+#{Regexp.escape(email)}/)
+
+      # Only check the token, because 'client_n+x@y.tld' may be a valid client
+      # email for some customers.
+      if environment == 'PRODUCTION' and sandbox_token
+        raise AdsCommon::Errors::EnvironmentMismatchError,
+            'Attempting to connect to production with sandbox credentials.'
+      # Check if either the token or client email do not follow the correct
+      # format. Client email may not exist, though.
+      elsif environment == 'SANDBOX' and (!sandbox_token or
+          (client.length > 0 and !sandbox_client))
+        raise AdsCommon::Errors::EnvironmentMismatchError,
+            'Attempting to connect to the sandbox with malformatted ' +
+            'credentials. Please check ' +
+            'http://code.google.com/apis/adwords/docs/developer/' +
+            'adwords_api_sandbox.html#requestheaders for details.'
+      end
+    end
+  end
+end

data/lib/adwords_api/errors.rb

@@ -0,0 +1,85 @@
+#!/usr/bin/ruby
+#
+# Authors:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# 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.
+#
+# Specific error handling for the AdWords API.
+
+require 'ads_common/errors'
+
+module AdwordsApi
+  module Errors
+
+    # This class encapsulates a v13 or v20xx exception. Errors are stored in an
+    # array, with each error being a hash, rather than a Ruby object. This is
+    # for the purpose of making the errors independent from the SOAP toolkit
+    # being used.
+    class ApiException < AdsCommon::Errors::ApiException
+      attr_reader :code, :errors, :trigger
+
+      def initialize(message = nil, errors = nil, code = nil, trigger = nil)
+        @message, @errors, @code, @trigger = message, errors, code, trigger
+      end
+
+      # Returns the source operation index for an error
+      #
+      # Args:
+      # - error: the error to be analyzed
+      #
+      # Returns:
+      # - index for the source operation, nil if none
+      #
+      def operation_index_for_error(error)
+        if error and error.include? :field_path and error[:field_path]
+          parts = error[:field_path].split('.')
+          if parts.length > 0
+            match = parts.first.match(/operations\[(\d)\]/)
+            return match ? match[1].to_i : nil
+          end
+        end
+        return nil
+      end
+    end
+
+    # Creates an ApiException given a SOAPFault and a service wrapper.
+    def self.create_api_exception(fault, wrapper)
+      # Get the inner fault.
+      inner_fault = nil
+      if fault and fault.detail
+        if fault.detail.respond_to? :apiExceptionFault
+          inner_fault = fault.detail.apiExceptionFault
+        elsif fault.detail.respond_to? :fault
+          inner_fault = fault.detail.fault
+        end
+      end
+      if inner_fault
+        # Convert error objects to hashes.
+        errors = nil
+        if inner_fault.errors
+          errors = inner_fault.errors.map do |error_object|
+            wrapper.convert_from_object(error_object)
+          end
+        end
+        code = inner_fault.respond_to?(:code) ? inner_fault.code : nil
+        trigger = inner_fault.respond_to?(:trigger) ? inner_fault.trigger : nil
+        return ApiException.new(inner_fault.message, errors, code, trigger)
+      else
+        return ApiException.new
+      end
+    end
+  end
+end