adwords4r 13.0.1 → 15.0.1

data/Authors.txt

@@ -1,4 +1,5 @@
-jeffy@google.com (Current)
+sgomes@google.com (Current)
+jeffy@google.com
 opensource@google.com
 chanezon@google.com
 leavengood@gmail.com

data/ChangeLog.txt

@@ -1,3 +1,31 @@
+15.0.1
+- Bugfix: added generation of ApiError exceptions upon SOAP faults.
+
+15.0.0
+- Added support for the v200902 sandbox.
+- Added support for multiple API versions on the same AdWords::API object.
+- Added request and SOAP XML file logging options.
+  This complements the previously existing SOAP XML console output.
+- Moved API classes to their own version and service-dependent modules.
+  This is necessary for multiple version support.
+- Moved API methods from the AdWords::API object to service wrappers.
+  This is necessary to avoid collisions between similarly named methods in different services.
+- Added get_service method to AdWords::API to be able to access a particular version of a service.
+  It returns the service wrapper containing the API methods for that service.
+- Added extensions mechanism, allowing for plugging of client-side methods into the wrapper objects.
+  This allows us to provide smart methods at the service level that simplify common tasks.
+- Added report download helper method, via the extension mechanism above.
+- Moved unit tracking to happen within AdWords::API instances.
+  This allows for correct tracking with multiple AdWords::API objects.
+  The methods have been renamed total_units and last_units to fit with the getter conventions.
+- Made code style more coherent.
+- Updated v13 code samples to work with new client library model.
+- Added v200902 and multiple version code samples.
+
+14.0.0
+- Sérgio Gomes (api.sgomes@gmail.com) takes over as maintainer of this project.
+- Removed support for v12 of the API, which has been deco'ed.
+
 13.0.1
 - Modified the file permissions on many of the files to make them world-readable.
 

data/Copying.txt

@@ -1,4 +1,4 @@
-Copyright 2008, Google Inc. All Rights Reserved.
+Copyright 2009, Google Inc. All Rights Reserved.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

data/{Licence.txt → License.txt}

@@ -1,4 +1,4 @@
-Copyright 2008, Google Inc. All Rights Reserved.
+Copyright 2009, Google Inc. All Rights Reserved.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

data/Rakefile

@@ -16,7 +16,7 @@ require 'lib/adwords4r/services'
 
 CLOBBER.include('pkg')
 
-CURRENT_VERSION = '13.0.1'
+CURRENT_VERSION = '15.0.1'
 PKG_VERSION = ENV['REL'] ? ENV['REL'] : CURRENT_VERSION
 
 SRC_RB = FileList['lib/**/*.rb']
@@ -28,7 +28,7 @@ GENDIR = LIBDIR + '/adwords4r'
 logger = Logger.new(STDERR)
 
 CLEAN.include(WSDLDIR)
-AdWords::Service.getVersions.each do |v|
+AdWords::Service.get_versions.each do |v|
   vname = "v#{v}"
   CLEAN.include(File.join(GENDIR, vname))
 end
@@ -38,37 +38,44 @@ task :default => [:getwsdl, :generate]
 
 desc "gets the wsdl files for AdWords services"
 task :getwsdl do
-  AdWords::Service.getVersions.each do |v|
+  AdWords::Service.get_versions.each do |v|
     vname = "v#{v}"
     mkdir_p File.join(WSDLDIR, vname)
-    AdWords::Service.getServices(v).each {|s|
-      save(getfile("adwords.google.com",
-		   "/api/adwords/#{vname}/#{s}Service?wsdl"),
-           getWsdlFileName(vname,s))}
+    AdWords::Service.get_services(v).each do |s|
+      if v.to_i <= 13
+        save(getfile("adwords.google.com",
+                     "/api/adwords/#{vname}/#{s}Service?wsdl"),
+             get_wsdl_file_name(vname, s))
+      else
+        save(getfile("adwords-sandbox.google.com",
+                     "/api/adwords/cm/#{vname}/#{s}Service?wsdl"),
+             get_wsdl_file_name(vname, s))
+      end
+    end
   end
 end
 
 desc "generates AdWords classes from the wsdl files"
 task :generate do
-  AdWords::Service.getVersions.each do |v|
+  AdWords::Service.get_versions.each do |v|
     vname = "v#{v}"
     gendir = "#{LIBDIR}/adwords4r/#{vname}"
     mkdir_p gendir
-    AdWords::Service.getServices(v).each do |name|
+    AdWords::Service.get_services(v).each do |name|
       worker = WSDL::SOAP::WSDL2Ruby.new
       worker.logger = logger
-      worker.location = getWsdlFileName(vname,name)
+      worker.location = get_wsdl_file_name(vname,name)
       worker.basedir = gendir
-      worker.opt.update(getWsdlOpt(name))
+      worker.opt.update(get_wsdl_opt(vname,name))
       worker.run
-      fixImport(v, File.join(gendir, "#{name}Driver.rb"))
-      fixImport(v, File.join(gendir, "#{name}MappingRegistry.rb"))
-      fixImport(v, File.join(gendir, "#{name}.rb"))
+      fix_import(v, File.join(gendir, "#{name}Driver.rb"))
+      fix_import(v, File.join(gendir, "#{name}MappingRegistry.rb"))
+      fix_import(v, File.join(gendir, "#{name}.rb"))
     end
   end
 end
 
-def fixImport(version, file)
+def fix_import(version, file)
   vname = "v#{version}"
   tempfile = file + '.tmp'
   outfile = File.new(tempfile,"w")
@@ -86,25 +93,25 @@ def fixImport(version, file)
   File.rename(tempfile, file)
 end 
 
-def getWsdlOpt(s)
+def get_wsdl_opt(v,s)
   optcmd= {}
   s << "Service"
   optcmd['classdef'] = s
   optcmd['force'] = true
   optcmd['mapping_registry'] = true
   optcmd['driver'] = nil
-  
+
   # Causes soap4r to wrap the classes it outputs into the given modules
-  optcmd['module_path'] = ['AdWords', s]
+  optcmd['module_path'] = ['AdWords', v.capitalize, s]
   return optcmd
 end
 
-def getWsdlFileName(v,s)
+def get_wsdl_file_name(v,s)
   "#{WSDLDIR}/#{v}/#{s}.wsdl"
 end
 
 def getfile(host, path)
-  puts "getting https//#{host}#{path}"
+  puts "getting https://#{host}#{path}"
   https = Net::HTTP.new(host, 443)
   https.use_ssl = true
   https.verify_mode = OpenSSL::SSL::VERIFY_NONE
@@ -115,8 +122,8 @@ def fix_attribute(text, name, type)
   text.gsub!(Regexp.new("#{name}=\"#{type}\""),"#{name}=\"xsd:#{type}\"")
 end
 
-def fixWsdl(wsdl)
-  ['type', 'base'].each {|name| 
+def fix_wsdl(wsdl)
+  ['type', 'base'].each {|name|
     ['long', 'string', 'date', 'int', 'boolean'].each {|type|
       fix_attribute(wsdl, name, type)}}
   schema_ns = "xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\""
@@ -124,14 +131,13 @@ def fixWsdl(wsdl)
     wsdl.gsub!(/(<wsdl:definitions[^>]*)>/, '\1 ' + schema_ns + '>')
   end
   return wsdl
-  #wsdl.gsub(/type=\"long\"/, 'type="xsd:long"')
 end
 
 # Saves this document to the specified @var path.
-#doesn't create the file if contains markup for google 404 page
+# doesn't create the file if contains markup for google 404 page
 def save(content, path)
   if content !~ /<H2>Error 404<\/H2>/
-    File::open(path, 'w') {|f| f.write(fixWsdl(content))}
+    File::open(path, 'w') {|f| f.write(fix_wsdl(content))}
   end
 end
 
@@ -140,60 +146,49 @@ end
 # gem files.
 
 PKG_FILES = FileList[
-  '*.*', 
-  'Rakefile', 
-  'lib/**/*.rb', 
-  'examples/**/*.rb', 
-  #  'test/**/*.rb',
+  '*.*',
+  'Rakefile',
+  'lib/**/*.rb',
+  'examples/**/*.rb',
   'scripts/**/*.rb'
 ]
 
-#puts PKG_FILES
-
 PKG_FILES.exclude(/\._/)
 
 if ! defined?(Gem)
   puts "Package Target requires RubyGems"
 else
   spec = Gem::Specification.new do |s|
-    
+
     #### Basic information.
-    
+
     s.name = 'adwords4r'
     s.version = PKG_VERSION
     s.summary = "Client library for the AdWords API."
     s.description = %{\
-Adwords4r provides an easy to use way to access the AdWords API in ruby.\
+Adwords4r provides an easy to use way to access the AdWords API in Ruby.\
 Currently the following AdWords API versions are supported:\
 \
-* V12\
 * V13\
+* V200902 (sandbox)
 }
-    
+
     s.files = PKG_FILES.to_a
     s.require_path = 'lib'
     s.autorequire = 'adwords4r'
-    
-    #s.test_files = PKG_FILES.select { |fn| fn =~ /^test\/test/ }
-    
-    #s.has_rdoc = true
+
     s.has_rdoc = false
-    #s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$/ }.to_a
-    #s.rdoc_options <<
-    #      '--title' <<  'Builder -- Easy XML Building' <<
-    #      '--main' << 'README' <<
-    #      '--line-numbers'
-    
-    s.author = "Jeffrey Posnick, Patrick Chanezon, Ryan Leavengood"
-    s.email = "jeffy@google.com"
-    s.homepage = "http://rubyforge.org/projects/google4r/"
-    s.requirements << 'soap4r v1.5.8 or greater'
+
+    s.author =
+        "Sergio Gomes, Jeffrey Posnick, Patrick Chanezon, Ryan Leavengood"
+    s.email = "api.sgomes@gmail.com"
+    s.homepage = "http://code.google.com/p/google-api-adwords-ruby/"
+    s.requirements << 'soap4r v1.5.8'
     s.requirements << 'httpclient v2.1.2 or greater'
-    s.rubyforge_project = 'google4r'
-    s.add_dependency('soap4r', '>= 1.5.8')
+    s.add_dependency('soap4r', '= 1.5.8')
     s.add_dependency('httpclient', '>= 2.1.2')
   end
-  
+
   Rake::GemPackageTask.new(spec) do |t|
     t.need_tar = true
   end

data/Readme.txt

@@ -1,7 +1,8 @@
-Google adwwords4r Library
+Google adwords4r Library
 -------------------------
 
-Welcome to adwords4r: Bringing the delights of ruby programming to the AdWords world!
+Welcome to adwords4r: Bringing the delights of Ruby programming to the AdWords
+world!
 
 Documentation and comments are a work in progress.
 
@@ -9,26 +10,36 @@ Documentation and comments are a work in progress.
 Useful Web Resources
 --------------------
 
-- AdWords home: https://adwords.google.com/
-- AdWords API discussion forum: http://groups.google.com/group/adwords-api
-- AdWords API documentation: http://www.google.com/apis/adwords/developer/index.html
-- This project's Google Code page: http://code.google.com/p/google-api-adwords-ruby/
+- AdWords home:
+    https://adwords.google.com/
+- AdWords API discussion forum:
+    http://groups.google.com/group/adwords-api
+- AdWords API documentation:
+    http://code.google.com/apis/adwords/docs/developer/index.html
+- This project's Google Code page:
+    http://code.google.com/p/google-api-adwords-ruby/
 
 
 Docs for Users
 --------------
 
+1 - Instalation:
+
 adwords4r is a ruby gem.  See http://docs.rubygems.org/read/book/1
 
 Install it using the gem install command.
-> gem install --remote adwords4r
+> gem install --local adwords4r
 
 The following gem libraries are required:
-- soap4r v1.5.8 or greater
+- soap4r v1.5.8
 - httpclient v2.1.2 or greater
 
+
+2 - Using the client library:
+
 It's pretty easy to use.
-See http://docs.rubygems.org/read/chapter/3#page70 for how to set the rubygem environment.
+See http://docs.rubygems.org/read/chapter/3#page70 for how to set the rubygem
+environment.
 export RUBYOPT=rubygems
 or ruby -rubygems my_program_that_uses_gems
 
@@ -36,11 +47,12 @@ If you do not use the rubygems option, you need to add
 require 'rubygems'
 at the beginning of your programs.
 
-Then   
+Then:
 require 'adwords4r'
 
 adwords = AdWords::API.new
-creates a driver for the latest version of AdWords API using a credentials file in ENV['HOME']/adwords.properties
+creates a driver for the latest version of AdWords API using a credentials file
+in ENV['HOME']/adwords.properties
 There is an example credentials in the root adwords4r directory.
 You can also pass API a manually constructed AdWordsCredentials object like:
 adwords = AdWords::API.new(AdWords::AdWordsCredentials.new({
@@ -52,21 +64,63 @@ adwords = AdWords::API.new(AdWords::AdWordsCredentials.new({
   'clientEmail' => 'user2@domain.com',
 }))
 
-If you want something more specific, use the optional parameters of the constructor
-adwords = AdWords::API.new(credentials, version)
+Then, just specify which service you're looking to use, and which version:
+account_srv = adwords.get_service(13, 'Account')
+
+and you should now be able to just use the API methods in the object you were
+returned:
+client_accounts = account_srv.getClientAccounts
+
+See the code in the examples directory for working examples you can build from.
+
+
+2.1 - Using the Sandbox:
+
+In order to use the v13 sandbox, you can add a credential named alternateUrl:
+alternateUrl=https://sandbox.google.com/api/adwords/v13/
 
-In order to use the sandbox, you can add a credential named
-alternateUrl like:
-alternateUrl=https://sandbox.google.com/api/adwords/v12/
+As for v200902, the alternateUrl parameter is currently ignored, since only the
+sandbox is available at the moment. For this API version, all requests will be
+sent to the sandbox, using the "email" and "password" fields defined in the
+credentials for authentication, and clientEmail for specifying which client
+account to access. Developer and application tokens are ignored.
 
-Then just use methods of the API against your driver.
-See sample code in the examples directory for working examples you can build from.
+This way, it's possible to access both the v13 and v200902 sandboxes
+simultaneously. Since they share a common backend storage, it is possible for
+your application to choose between v13 and v200902 services at will, mixing and
+matching them.
+
+The multiple_versions.rb code sample shows you how to build an application using
+v13 and v200902 services simultaneously.
+
+
+2.2 - Logging:
 
 It is often useful to see a trace of the raw SOAP XML being sent and received.
-To enable this, set the ADWORDS4R_DEBUG environment variable to TRUE.
-e.g. in the bash shell, export ADWORDS4R_DEBUG=TRUE
-or from your Ruby code, ENV['ADWORDS4R_DEBUG'] = 'TRUE'
-The SOAP logs will be written to the current directory.
+The quickest way of achieving this when debugging your application is by setting
+the ADWORDS4R_DEBUG environment variable to TRUE; e.g. in the bash shell:
+export ADWORDS4R_DEBUG=TRUE
+or from your Ruby code:
+ENV['ADWORDS4R_DEBUG'] = 'TRUE'
+
+This will output the SOAP XML to stderr, which will usually show up in your
+terminal window.
+
+There's also the option of logging requests and XML to files. In order to enable
+this, you should use the write_to_file method of the loggers inside your
+AdWords::API object:
+adwords = AdWords::API.new
+adwords.unit_logger.log_to_file
+adwords.xml_logger.log_to_file
+
+The first logs the units spent and the requests made, whereas the second logs
+the full SOAP XML being sent and received over the wire. These will be written
+to the current directory by default, but you can specify a path as an optional
+parameter to log_to_file:
+adwords.unit_logger.log_to_file('/var/log/my_app')
+adwords.xml_logger.log_to_file('/var/log/my_app')
+
+The files will be named request_info and soap_xml, respectively.
 
 
 Docs for Developers
@@ -78,12 +132,12 @@ rake generate
     to regenerate the bindings if needed
 rake package
     to package the gem and create a release
-    
+
 
 Copyright/License Info
 ----------------------
 
-Copyright 2008, Google Inc. All Rights Reserved.
+Copyright 2009, Google Inc. All Rights Reserved.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

data/adwords.properties

@@ -4,4 +4,4 @@ useragent=APPLICATION_NAME
 password=ADWORDS_PASSWORD
 email=ADWORDS_MCC_LOGIN
 clientEmail=OPTIONAL_CLIENT_LOGIN
-#alternateUrl=https://sandbox.google.com/api/adwords/v12/
+#alternateUrl=https://sandbox.google.com/api/adwords/v13/

data/examples/account_info.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/ruby
 #
-# Copyright 2008, Google Inc. All Rights Reserved.
+# Copyright 2009, Google Inc. All Rights Reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -18,7 +18,7 @@
 # MCC account, and then iteratively retrieves information about each account.
 
 require 'rubygems'
-gem 'soap4r', '>= 1.5.8'
+gem 'soap4r', '= 1.5.8'
 require 'adwords4r'
 
 
@@ -38,30 +38,30 @@ def main()
     # specified inline as a hash:
     #
     # creds = {
-    #   'developerToken' => 'user@domain.com++USD',
-    #   'useragent' => 'Sample User Agent',
-    #   'password' => 'password',
-    #   'email' => 'user@domain.com',
-    #   'clientEmail' => 'client_1+user@domain.com',
-    #   'applicationToken' => 'IGNORED',
-    #   'alternateUrl' => 'https://sandbox.google.com/api/adwords/v13/',
+    #     'developerToken' => 'user@domain.com++USD',
+    #     'useragent' => 'Sample User Agent',
+    #     'password' => 'password',
+    #     'email' => 'user@domain.com',
+    #     'clientEmail' => 'client_1+user@domain.com',
+    #     'applicationToken' => 'IGNORED',
+    #     'alternateUrl' => 'https://sandbox.google.com/api/adwords/v13/',
     # }
-    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds), 13)
-
+    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds))
     adwords = AdWords::API.new
 
     # Clear out the clientEmail header temporarily so that we run under the
     # context of the MCC user.
-    adwords.credentials.setHeader('clientEmail', '')
+    adwords.credentials.set_header('clientEmail', '')
 
-    client_accounts = adwords.getClientAccounts
+    account_srv = adwords.get_service(13, 'Account')
+    client_accounts = account_srv.getClientAccounts
 
     if client_accounts.length > 0 then
       client_accounts.each do |client_account|
         # Set the clientEmail header to each account's login email so that API
         # calls are made in the context of that account.
-        adwords.credentials.setHeader('clientEmail', client_account)
-        account_info = adwords.getAccountInfo.getAccountInfoReturn
+        adwords.credentials.set_header('clientEmail', client_account)
+        account_info = account_srv.getAccountInfo.getAccountInfoReturn
 
         puts 'Client Email: %s' % client_account
         if ! account_info.descriptiveName.empty? then
@@ -77,16 +77,14 @@ def main()
   rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => e
     # This exception indicates a connection-level error.
     # In general, it is likely to be transitory.
-
     puts 'Connection Error: %s' % e
     puts 'Source: %s' % e.backtrace.first
-    
+
   rescue AdWords::Error::UnknownAPICall => e
     # This exception is thrown when an unknown SOAP method is invoked.
-
     puts e
     puts 'Source: %s' % e.backtrace.first
-    
+
   rescue AdWords::Error::ApiError => e
     # This exception maps to receiving a SOAP Fault back from the service.
     # The e.soap_faultstring_ex, e.code_ex, and potentially e.trigger_ex
@@ -99,7 +97,6 @@ def main()
     #     puts '%s => %s' % [var, value]
     #   end
     # end
-
     puts 'SOAP Error: %s (code: %d)' % [e.soap_faultstring_ex, e.code_ex]
     puts 'Trigger: %s' % e.trigger_ex unless e.trigger_ex.nil?
     puts 'Source: %s' % e.backtrace.first
@@ -107,13 +104,11 @@ def main()
   ensure
     # Display API unit usage info. This data is stored as a class variable
     # in the AdWords::API class and accessed via static methods.
-    # AdWords::API.get_total_units() returns a running total of units used in
-    # the scope of the current program.
-    # AdWords::API.get_last_units() returns the number used in the last call.
-
+    # total_units() returns a running total of units used in the scope of the
+    # current program. last_units() returns the number used in the last call.
     puts
     puts '%d API units consumed total (%d in last call).' %
-      [AdWords::API.get_total_units(), AdWords::API.get_last_units()]
+        [adwords.total_units, adwords.last_units]
   end
 end
 
@@ -124,7 +119,6 @@ if __FILE__ == $0
   # To enable this, set the ADWORDS4R_DEBUG environement varaible to 'true'.
   # This can be done either from your operating system environment or via
   # code, as done below.
-
   ENV['ADWORDS4R_DEBUG'] = 'false'
 
   main()