class AdwordsApi::Api

Wrapper class that serves as the main point of access for all the API usage.

Holds all the services, as well as login credentials.

Attributes

utils_reporter[R]

Public Class Methods

new(provided_config = nil) click to toggle source

Constructor for API.

Calls superclass method
# File lib/adwords_api.rb, line 43
def initialize(provided_config = nil)
  super(provided_config)
  @credential_handler = AdwordsApi::CredentialHandler.new(@config)
  @utils_reporter = AdwordsApi::UtilsReporter.new(@credential_handler)
end

Public Instance Methods

api_config() click to toggle source

Getter for the API service configurations

# File lib/adwords_api.rb, line 50
def api_config()
  AdwordsApi::ApiConfig
end
batch_job_utils(version = nil) click to toggle source

Returns an instance of BatchJobUtils object with all utilities relevant to running batch jobs.

Args:

  • version: version of the API to use (optional).

# File lib/adwords_api.rb, line 202
def batch_job_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 AdwordsApi::BatchJobUtils.new(self, version)
end
include_zero_impressions=(value) click to toggle source

Helper method to include zero impressions when downloading reports.

Args:

  • value: whether to include zero impressions (boolean)

# File lib/adwords_api.rb, line 140
def include_zero_impressions=(value)
  @config.set('library.include_zero_impressions', value)
end
partial_failure(&block) click to toggle source

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

# File lib/adwords_api.rb, line 165
def partial_failure(&block)
  return (block_given?) ?
    run_with_temporary_flag(:@partial_failure, true, block) :
    @credential_handler.partial_failure
end
partial_failure=(value) click to toggle source

Helper method to provide a simple way of performing requests with support for partial failures.

Args:

  • value: the new value for the property (boolean)

# File lib/adwords_api.rb, line 177
def partial_failure=(value)
  @credential_handler.partial_failure = value
end
report_query_builder(&block) click to toggle source

Returns an instance of ReportQueryBuilder to aid in generating AWQL for reports.

# File lib/adwords_api.rb, line 213
def report_query_builder(&block)
  return AdwordsApi::ReportQueryBuilder.new(self, &block)
end
report_utils(version = nil) click to toggle source

Returns an instance of ReportUtils object with all utilities relevant to the reporting.

Args:

  • version: version of the API to use (optional).

# File lib/adwords_api.rb, line 187
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 AdwordsApi::ReportUtils.new(self, version)
end
service_query_builder(&block) click to toggle source

Returns an instance of ServiceQueryBuilder to aid in generating AWQL for service queries.

# File lib/adwords_api.rb, line 219
def service_query_builder(&block)
  return AdwordsApi::ServiceQueryBuilder.new(self, &block)
end
skip_column_header=(value) click to toggle source

Helper method to skip the column header when downloading reports.

Args:

  • value: whether to skip the column header (boolean)

# File lib/adwords_api.rb, line 131
def skip_column_header=(value)
  @config.set('library.skip_column_header', value)
end
skip_report_header=(value) click to toggle source

Helper method to skip the report header when downloading reports.

Args:

  • value: whether to skip the report header (boolean)

# File lib/adwords_api.rb, line 113
def skip_report_header=(value)
  @config.set('library.skip_report_header', value)
end
skip_report_summary=(value) click to toggle source

Helper method to skip the report summary when downloading reports.

Args:

  • value: whether to skip the report summary (boolean)

# File lib/adwords_api.rb, line 122
def skip_report_summary=(value)
  @config.set('library.skip_report_summary', value)
end
soap_header_handler(auth_handler, version, header_ns, default_ns) click to toggle source

Retrieve correct soap_header_handler.

Args:

  • auth_handler: instance of an AdsCommon::Auth::BaseHandler subclass to handle authentication

  • version: intended API version

  • header_ns: header namespace

  • default_ns: default namespace

Returns:

  • SOAP header handler

# File lib/adwords_api.rb, line 66
def soap_header_handler(auth_handler, version, header_ns, default_ns)
  auth_method = @config.read('authentication.method', :OAUTH2)
  handler_class = case auth_method
    when :OAUTH2, :OAUTH2_SERVICE_ACCOUNT
      AdsCommon::SavonHeaders::OAuthHeaderHandler
    else
      raise AdsCommon::Errors::AuthError,
          "Unknown auth method: %s" % auth_method
    end
  return handler_class.new(@credential_handler, auth_handler, header_ns,
                              default_ns, version)
end
use_raw_enum_values=(value) click to toggle source

Helper method to use raw enum values when downloading reports.

Args:

  • value: whether to use raw enum values (boolean)

# File lib/adwords_api.rb, line 149
def use_raw_enum_values=(value)
  @config.set('library.use_raw_enum_values', value)
end
validate_only(&block) click to toggle source

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

# File lib/adwords_api.rb, line 91
def validate_only(&block)
  return (block_given?) ?
    run_with_temporary_flag(:@validate_only, true, block) :
    @credential_handler.validate_only
end
validate_only=(value) click to toggle source

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)

# File lib/adwords_api.rb, line 104
def validate_only=(value)
  @credential_handler.validate_only = value
end

Private Instance Methods

run_with_temporary_flag(flag_name, flag_value, block) click to toggle source

Executes block with a temporary flag set to a given value. Returns block result.

# File lib/adwords_api.rb, line 227
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