Class: AdWords::API

Inherits:
Object
  • Object
show all
Defined in:
lib/adwords4r.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(credentials = AdWordsCredentials.new) ⇒ API

Constructor for API.

Args:

  • credentials: AdWordsCredentials object containing the login information



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/adwords4r.rb', line 69

def initialize(credentials = AdWordsCredentials.new)
  @credentials = credentials
  if !AdWords::Service.environments.include? @credentials.environment
    raise AdWords::Error::Error,
        "Unknown environment #{@credentials.environment}"
  end
  @drivers = Hash.new
  @wrappers = Hash.new
  @total_units = 0
  @last_units = 0
  log_to_console = !ENV['ADWORDS4R_DEBUG'].nil? &&
      ENV['ADWORDS4R_DEBUG'].upcase == 'TRUE'
  @xml_logger = AdWordsLogger.new('soap_xml', log_to_console)
  @unit_logger = AdWordsLogger.new('request_info')
  @mutex = Mutex.new
  prepare_drivers
end

Instance Attribute Details

#credentials ⇒ Object (readonly)

AdWordsCredentials object used for authentication



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

def credentials
  @credentials
end

#last_units ⇒ Object

Number of units spent on the last operation via this API object



58
59
60
 
# File 'lib/adwords4r.rb', line 58

def last_units
  @last_units
end

#mutex ⇒ Object (readonly)

Mutex object for controlling concurrent access to API object data



56
57
58
 
# File 'lib/adwords4r.rb', line 56

def mutex
  @mutex
end

#total_units ⇒ Object

Number of units spent in total, via this API object



60
61
62
 
# File 'lib/adwords4r.rb', line 60

def total_units
  @total_units
end

#unit_logger ⇒ Object (readonly)

AdWordsLogger object used for logging request info



54
55
56
 
# File 'lib/adwords4r.rb', line 54

def unit_logger
  @unit_logger
end

#xml_logger ⇒ Object (readonly)

AdWordsLogger object used for logging SOAP XML



52
53
54
 
# File 'lib/adwords4r.rb', line 52

def xml_logger
  @xml_logger
end

Instance Method Details

#get_service(name, version = nil) ⇒ Object Also known as: service

Obtain an API service, given a version and its name.

Args:

  • name: name for the intended service

  • version: intended API version. Must be an integer.

Returns:

  • the service wrapper for the intended service.



200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/adwords4r.rb', line 200

def get_service(name, version = nil)
  if name.is_a? Integer and version.is_a? String
    name, version = version, name
    warn("This parameter order is deprecated. " +
         "Please use get_service(name, version) from now on.")
  elsif name.is_a? String
    # Do nothing
  else
    raise ArgumentError, "Wrong arguments. " +
        "Expected: get_service(name, version = nil)"
  end
  version = AdWords::Service::get_default_version if version == nil
  # Check if version exists
  if !AdWords::Service.get_versions.include?(version)
    if version.is_a? String
      raise AdWords::Error::Error, "Unknown version '#{version}'. Please " +
          "note that version numbers should be numeric, not strings"
    else
      raise AdWords::Error::Error, "Unknown version #{version}"
    end
  end
  # Check if the current environment supports the requested version
  if !AdWords::Service.environment_has_version(@credentials.environment,
      version)
    raise AdWords::Error::Error, "Environment #{@credentials.environment}" +
        " does not support version #{version}"
  end
  # Check if the specified version has the requested service
  if !AdWords::Service.version_has_service(version, name)
    raise AdWords::Error::Error, "Version #{version} does not contain " +
      "service #{name}"
  end
  return @wrappers[[version, name]]
end

#partial_failure ⇒ 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 validate-only operation.

Returns: Boolean indicating whether validate-only operations are currently enabled or disabled



168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/adwords4r.rb', line 168

def partial_failure
  if block_given?
    previous = @credentials.partial_failure
    begin
      @credentials.partial_failure = true
      yield
    ensure
      @credentials.partial_failure = previous
    end
  end
  return @credentials.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)



187
188
189
 
# File 'lib/adwords4r.rb', line 187

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

#use_mcc ⇒ Object

Helper method to provide a simple way of doing an MCC-level operation without the need to change credentials. Executes a block of code as an MCC-level operation and/or returns the current status of the property.

Args:

  • accepts a block, which it will execute as an MCC-level operation.

Returns: Boolean indicating whether MCC-level operations are currently enabled or disabled



98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/adwords4r.rb', line 98

def use_mcc
  if block_given?
    previous = @credentials.use_mcc
    begin
      @credentials.use_mcc = true
      yield
    ensure
      @credentials.use_mcc = previous
    end
  end
  return @credentials.use_mcc
end

#use_mcc=(value) ⇒ Object

Helper method to provide a simple way of doing an MCC-level operation without the need to change credentials. Sets the value of the property that controls whether MCC-level operations are enabled or disabled.

Args:

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



118
119
120
 
# File 'lib/adwords4r.rb', line 118

def use_mcc=(value)
  @credentials.use_mcc = value
end

#validate_only ⇒ 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: Boolean indicating whether validate-only operations are currently enabled or disabled



133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/adwords4r.rb', line 133

def validate_only
  if block_given?
    previous = @credentials.validate_only
    begin
      @credentials.validate_only = true
      yield
    ensure
      @credentials.validate_only = previous
    end
  end
  return @credentials.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)



153
154
155
 
# File 'lib/adwords4r.rb', line 153

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