Class: AdwordsApi::Api

Inherits:
AdsCommon::Api
  • Object
show all
Defined in:
lib/adwords_api.rb

Overview

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

Holds all the services, as well as login credentials.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(provided_config = nil) ⇒ Api

Constructor for API.



43
44
45
46
47
 
# 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

Instance Attribute Details

#utils_reporter ⇒ Object (readonly)

Returns the value of attribute utils_reporter.



40
41
42
 
# File 'lib/adwords_api.rb', line 40

def utils_reporter
  @utils_reporter
end

Instance Method Details

#api_config ⇒ Object

Getter for the API service configurations



50
51
52
 
# File 'lib/adwords_api.rb', line 50

def api_config()
  AdwordsApi::ApiConfig
end

#batch_job_utils(version = nil) ⇒ Object

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

Args:

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



202
203
204
205
206
207
208
209
 
# 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) ⇒ Object

Helper method to include zero impressions when downloading reports.

Args:

  • value: whether to include zero impressions (boolean)



140
141
142
 
# File 'lib/adwords_api.rb', line 140

def include_zero_impressions=(value)
  @config.set('library.include_zero_impressions', value)
end

#partial_failure(&block) ⇒ Object

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



165
166
167
168
169
 
# 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) ⇒ Object

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

Args:

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



177
178
179
 
# File 'lib/adwords_api.rb', line 177

def partial_failure=(value)
  @credential_handler.partial_failure = value
end

#report_query_builder(&block) ⇒ Object

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



213
214
215
 
# File 'lib/adwords_api.rb', line 213

def report_query_builder(&block)
  return AdwordsApi::ReportQueryBuilder.new(self, &block)
end

#report_utils(version = nil) ⇒ Object

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

Args:

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



187
188
189
190
191
192
193
194
 
# 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) ⇒ Object

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



219
220
221
 
# File 'lib/adwords_api.rb', line 219

def service_query_builder(&block)
  return AdwordsApi::ServiceQueryBuilder.new(self, &block)
end

#skip_column_header=(value) ⇒ Object

Helper method to skip the column header when downloading reports.

Args:

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



131
132
133
 
# File 'lib/adwords_api.rb', line 131

def skip_column_header=(value)
  @config.set('library.skip_column_header', value)
end

#skip_report_header=(value) ⇒ Object

Helper method to skip the report header when downloading reports.

Args:

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



113
114
115
 
# File 'lib/adwords_api.rb', line 113

def skip_report_header=(value)
  @config.set('library.skip_report_header', value)
end

#skip_report_summary=(value) ⇒ Object

Helper method to skip the report summary when downloading reports.

Args:

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



122
123
124
 
# 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) ⇒ Object

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



66
67
68
69
70
71
72
73
74
75
76
77
 
# 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) ⇒ Object

Helper method to use raw enum values when downloading reports.

Args:

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



149
150
151
 
# 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) ⇒ Object

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



91
92
93
94
95
 
# 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) ⇒ Object

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)



104
105
106
 
# File 'lib/adwords_api.rb', line 104

def validate_only=(value)
  @credential_handler.validate_only = value
end