Module: AdWords::Service

Defined in:
lib/adwords4r/services.rb

Overview

Contains helper methods for loading and managing the available services.

Constant Summary collapse

DEFAULT_VERSION =

Set defaults

201008
DEFAULT_ENVIRONMENT = 
'PRODUCTION'
@@services =

Configure the services available to each version

{
  13 => ['Account', 'Report', 'TrafficEstimator'],
  200909 => ['AdExtensionOverride', 'AdGroupAd', 'AdGroupCriterion',
             'AdGroup', 'AdParam', 'BulkMutateJob', 'CampaignAdExtension',
             'CampaignCriterion', 'Campaign', 'CampaignTarget',
             'GeoLocation', 'Info', 'TargetingIdea'],
  201003 => ['AdExtensionOverride', 'AdGroupAd', 'AdGroupCriterion',
             'AdGroup', 'AdParam', 'BidLandscape', 'BulkMutateJob',
             'CampaignAdExtension', 'CampaignCriterion', 'Campaign',
             'CampaignTarget', 'GeoLocation', 'Info', 'Media',
             'ReportDefinition', 'TargetingIdea'],
  201008 => ['AdExtensionOverride', 'AdGroupAd', 'AdGroupCriterion',
             'AdGroup', 'AdParam', 'BidLandscape', 'BulkMutateJob',
             'CampaignAdExtension', 'CampaignCriterion', 'Campaign',
             'CampaignTarget', 'Experiment', 'GeoLocation',
             'Info', 'Media', 'ReportDefinition', 'TargetingIdea',
             'TrafficEstimator']
}
@@environments =

Configure the different environments, with the base URL for each one

{
  'PRODUCTION' => {
    13 => 'https://adwords.google.com/api/adwords/',
    200909 => 'https://adwords.google.com/api/adwords/',
    201003 => 'https://adwords.google.com/api/adwords/',
    201008 => 'https://adwords.google.com/api/adwords/',
  },
  'SANDBOX' => {
    13 => 'https://sandbox.google.com/api/adwords/',
    200909 => 'https://adwords-sandbox.google.com/api/adwords/',
    201003 => 'https://adwords-sandbox.google.com/api/adwords/',
    201008 => 'https://adwords-sandbox.google.com/api/adwords/'
  }
}
@@subdirs =

Configure the subdirectories for each version / service pair. A missing pair means that only the base URL is used.

{
  # v13
  [13, 'Account'] => 'v13/',
  [13, 'Report'] => 'v13/',
  [13, 'TrafficEstimator'] => 'v13/',
  # v200909
  [200909, 'AdExtensionOverride'] => 'cm/v200909/',
  [200909, 'AdGroupAd'] => 'cm/v200909/',
  [200909, 'AdGroupCriterion'] => 'cm/v200909/',
  [200909, 'AdGroup'] => 'cm/v200909/',
  [200909, 'AdParam'] => 'cm/v200909/',
  [200909, 'BulkMutateJob'] => 'job/v200909/',
  [200909, 'CampaignAdExtension'] => 'cm/v200909/',
  [200909, 'CampaignCriterion'] => 'cm/v200909/',
  [200909, 'Campaign'] => 'cm/v200909/',
  [200909, 'CampaignTarget'] => 'cm/v200909/',
  [200909, 'GeoLocation'] => 'cm/v200909/',
  [200909, 'Info'] => 'info/v200909/',
  [200909, 'TargetingIdea'] => 'o/v200909/',
  # v201003
  [201003, 'AdExtensionOverride'] => 'cm/v201003/',
  [201003, 'AdGroupAd'] => 'cm/v201003/',
  [201003, 'AdGroupCriterion'] => 'cm/v201003/',
  [201003, 'AdGroup'] => 'cm/v201003/',
  [201003, 'AdParam'] => 'cm/v201003/',
  [201003, 'BidLandscape'] => 'cm/v201003/',
  [201003, 'BulkMutateJob'] => 'job/v201003/',
  [201003, 'CampaignAdExtension'] => 'cm/v201003/',
  [201003, 'CampaignCriterion'] => 'cm/v201003/',
  [201003, 'Campaign'] => 'cm/v201003/',
  [201003, 'CampaignTarget'] => 'cm/v201003/',
  [201003, 'GeoLocation'] => 'cm/v201003/',
  [201003, 'Info'] => 'info/v201003/',
  [201003, 'Media'] => 'cm/v201003/',
  [201003, 'ReportDefinition'] => 'cm/v201003/',
  [201003, 'TargetingIdea'] => 'o/v201003/',
   # v201008
  [201008, 'AdExtensionOverride'] => 'cm/v201008/',
  [201008, 'AdGroupAd'] => 'cm/v201008/',
  [201008, 'AdGroupCriterion'] => 'cm/v201008/',
  [201008, 'AdGroup'] => 'cm/v201008/',
  [201008, 'AdParam'] => 'cm/v201008/',
  [201008, 'BidLandscape'] => 'cm/v201008/',
  [201008, 'BulkMutateJob'] => 'job/v201008/',
  [201008, 'CampaignAdExtension'] => 'cm/v201008/',
  [201008, 'CampaignCriterion'] => 'cm/v201008/',
  [201008, 'Campaign'] => 'cm/v201008/',
  [201008, 'CampaignTarget'] => 'cm/v201008/',
  [201008, 'Experiment'] => 'cm/v201008/',
  [201008, 'GeoLocation'] => 'cm/v201008/',
  [201008, 'Info'] => 'info/v201008/',
  [201008, 'Media'] => 'cm/v201008/',
  [201008, 'ReportDefinition'] => 'cm/v201008/',
  [201008, 'ServicedAccount'] => 'mcm/v201008/',
  [201008, 'TargetingIdea'] => 'o/v201008/',
  [201008, 'TrafficEstimator'] => 'o/v201008/'
}
@@auth_servers =

Configure the auth servers to use for each environment The tuplet should be (hostname, port, use_ssl?)

{
  'PRODUCTION' => ['www.google.com', 443, true],
  'SANDBOX' => ['www.google.com', 443, true]
}

Class Method Summary collapse

Class Method Details

.add_environment(name, endpoint_hash) ⇒ Object

Add a new environment to the list.

Args:

  • name: the name for the new environment

  • endpoint_hash: a hash of base endpoint URLs, indexed by version number, e.g.:

    { 13 => 'URL_FOR_v13', 200906 => 'URL_FOR_v200906' }



293
294
295
 
# File 'lib/adwords4r/services.rb', line 293

def self.add_environment(name, endpoint_hash)
  @@environments[name] = endpoint_hash
end

.do_require(version) ⇒ Object

Perform the loading of the necessary source files for a version

Args:

  • version: the API version (as an integer)



302
303
304
305
306
 
# File 'lib/adwords4r/services.rb', line 302

def self.do_require(version)
  get_services(version).each do |service|
    eval("require 'adwords4r/v#{version}/#{service}ServiceWrapper.rb'")
  end
end

.environment_has_version(environment, version) ⇒ Object

Does the given environment exist and contain the given version?

Returns: Boolean indicating whether the given environment exists and contains the given version



163
164
165
166
 
# File 'lib/adwords4r/services.rb', line 163

def self.environment_has_version(environment, version)
  return (!@@environments[environment].nil? and
          !@@environments[environment][version].nil?)
end

.get_auth_server(environment) ⇒ Object Also known as: auth_server

Get the authentication server details for an environment

Args:

  • environment: the service environment to be used (as a string)

Returns: Array containing

  • the hostname for the auth server (as a string)

  • the port for the auth server (as an integer)

  • whether to use SSL or not (as a boolean)



275
276
277
278
279
280
281
282
283
 
# File 'lib/adwords4r/services.rb', line 275

def self.get_auth_server(environment)
  # If we don't have an entry for this environment, we just return the
  # default server (the same one being used for the default environment)
  if @@auth_servers[environment].nil?
    return @@auth_servers[DEFAULT_ENVIRONMENT]
  end

  return @@auth_servers[environment]
end

.get_default_environment ⇒ Object Also known as: default_environment

Get the default environment.

Returns: Default environment (as a string)



214
215
216
 
# File 'lib/adwords4r/services.rb', line 214

def self.get_default_environment
  return DEFAULT_ENVIRONMENT
end

.get_default_version ⇒ Object Also known as: default_version

Get the default API version.

Returns: Default version (as an integer)



184
185
186
 
# File 'lib/adwords4r/services.rb', line 184

def self.get_default_version
  return DEFAULT_VERSION
end

.get_endpoint(environment, version, service) ⇒ Object Also known as: endpoint

Get the endpoint for a service on a given environment and API version.

Args:

  • environment: the service environment to be used (as a string)

  • version: the API version (as an integer)

  • service: the name of the API service (as a string)

Returns: The endpoint URL (as a string)



228
229
230
231
232
233
 
# File 'lib/adwords4r/services.rb', line 228

def self.get_endpoint(environment, version, service)
  base = @@environments[environment][version]
  path = @@subdirs[[version, service]]
  return base.to_s + path.to_s if base
  return nil
end

.get_environments ⇒ Object Also known as: environments

Get the available environments.

Returns: List of available environments (as strings)



205
206
207
 
# File 'lib/adwords4r/services.rb', line 205

def self.get_environments
  @@environments.keys
end

.get_interface_name(version, service) ⇒ Object Also known as: interface_name

Returns the full interface class name for a given service

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)



330
331
332
333
334
335
336
337
 
# File 'lib/adwords4r/services.rb', line 330

def self.get_interface_name(version, service)
  if version.is_a? Integer and version <= 13
    return get_module_name(version, service) + "::#{service}Interface"
  else
    return get_module_name(version, service) +
        "::#{service}ServiceInterface"
  end
end

.get_latest_version ⇒ Object Also known as: latest_version

Get the latest API version.

Returns: Latest version (as an integer)



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

def self.get_latest_version
  @@services.keys.select { |service| service.is_a? Integer }.max
end

.get_module_name(version, service) ⇒ Object Also known as: module_name

Returns the full module name for a given service

Args:

  • version: the API version (as an integer)

  • service: the service name (as a string)

Returns: The full module name for the given service (as a string)



317
318
319
 
# File 'lib/adwords4r/services.rb', line 317

def self.get_module_name(version, service)
  return "AdWords::V#{version.to_s}::#{service}Service"
end

.get_namespace_v2009(driver) ⇒ Object Also known as: namespace_v2009

Returns the namespace for a version and service

Args:

  • driver: the service driver

Returns: String with the namespace



359
360
361
362
363
364
365
366
367
 
# File 'lib/adwords4r/services.rb', line 359

def self.get_namespace_v2009(driver)
  # This is a huge hack to get the correct namespace for a given service,
  # but short from configuring it ourselves there seems to be no other
  # option. This accesses one of the fields in the description of the
  # service's methods, which indicates the namespace.
  # Thankfully, since it's a constant and checked as part of our unit tests,
  # it should always work.
  return driver.class::Methods[0][2][0][2][1]
end

.get_report_download_url(environment, version) ⇒ Object Also known as: report_download_url

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)



244
245
246
247
248
249
 
# File 'lib/adwords4r/services.rb', line 244

def self.get_report_download_url(environment, version)
  base = @@environments[environment][version]
  path = 'reportdownload' if version >= 201003
  return base.to_s + path.to_s if base and path
  return nil
end

.get_services(version) ⇒ Object Also known as: services

Get the list of service names for a given version

Args:

  • version: the API version (as an integer)

Returns: List of names of services (as strings) available for given version



196
197
198
 
# File 'lib/adwords4r/services.rb', line 196

def self.get_services(version)
  @@services[version]
end

.get_subdir(version, service) ⇒ Object Also known as: subdir

Get the subdirectory for a service, for a given API version.

Args:

  • version: the API version (as an integer)

  • service: the name of the API service (as a string)

Returns: The endpoint URL (as a string)



260
261
262
 
# File 'lib/adwords4r/services.rb', line 260

def self.get_subdir(version, service)
  return @@subdirs[[version, service]]
end

.get_versions ⇒ Object Also known as: versions

Get the available API versions.

Returns: List of versions available (as integers)



144
145
146
 
# File 'lib/adwords4r/services.rb', line 144

def self.get_versions
  @@services.keys
end

.get_wrapper_name(version, service) ⇒ Object Also known as: wrapper_name

Returns the full wrapper class name for a given service

Args:

  • version: the API version (as an integer)

  • service: the service name (as a string)

Returns: The full wrapper class name for the given service (as a string)



348
349
350
 
# File 'lib/adwords4r/services.rb', line 348

def self.get_wrapper_name(version, service)
  return get_module_name(version, service) + "::#{service}ServiceWrapper"
end

.validate_param(param_name, param, type) ⇒ Object

Validates whether a parameter is of the correct type This method is invoked by the wrappers during runtime to check the validity of every parameter.

Args:

  • param_name: the parameter name (as a String)

  • param: the parameter value

  • type: the expected type (the class object itself)

Returns: nil, upon success

Raises:

  • ArgumentError: in case of an unexpected type



384
385
386
387
388
389
390
391
392
393
394
 
# File 'lib/adwords4r/services.rb', line 384

def self.validate_param(param_name, param, type)
  return nil if param.is_a? type

  begin
    type.new(param)
  rescue
    raise ArgumentError, "Parameter '#{param_name}'" +
        " should be convertible into type #{type.to_s}"
  end
  return nil
end

.version_has_service(version, service) ⇒ Object

Does the given version exist and contain the given service?

Returns: Boolean indicating whether the given version exists and contains the given service



174
175
176
177
 
# File 'lib/adwords4r/services.rb', line 174

def self.version_has_service(version, service)
  return (!@@services[version].nil? and
          @@services[version].include?(service))
end