adwords4r 0.2

data/Authors.txt

@@ -0,0 +1,2 @@
+opensource@google.com
+chanezon@google.com

data/ChangeLog.txt

@@ -0,0 +1,4 @@
+0.2 added packaging and made it a gem, for easy installation.
+0.1 -first version, not fully tested
+works for Campaigns
+

data/Copying.txt

@@ -0,0 +1,28 @@
+Copyright (c) 2006, Google Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+    * Neither the name of Google Inc. nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Licence.txt

@@ -0,0 +1,10 @@
+Copyright (c) 2006, Google Inc
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+    * Neither the name of Google, Inc nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Rakefile

@@ -0,0 +1,190 @@
+require 'wsdl/soap/wsdl2ruby'
+require 'net/https'
+require 'fileutils'
+require 'rake/clean'
+require 'logger'
+begin
+  require 'rubygems'
+  require 'rake/gempackagetask'
+rescue Exception
+  nil
+end
+begin
+  require 'lib/adwords4r/services'
+rescue Exception
+  puts 'require services not found'
+  nil
+end
+
+# Determine the current version of the software
+
+CLOBBER.include('pkg')
+
+CURRENT_VERSION = '0.2'
+PKG_VERSION = ENV['REL'] ? ENV['REL'] : CURRENT_VERSION
+
+SRC_RB = FileList['lib/**/*.rb']
+
+# The default task is run if rake is given no explicit arguments.
+
+#desc "Default Task"
+#task :default => :test_all
+
+WSDLDIR = 'wsdl'
+LIBDIR = 'lib'
+logger = Logger.new(STDERR)
+
+#CLEAN.include(WSDLDIR)
+
+desc "gets the wsdl and generates the classes"
+task :default => [:getwsdl, :generate]
+
+desc "gets the wsdl files for AdWords services"
+task :getwsdl do
+    AdWords::Service.getVersions.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))}
+    end
+end
+
+desc "generates AdWords classes from the wsdl files"
+task :generate do
+    AdWords::Service.getVersions.each do |v|
+        vname = "v#{v}"
+        gendir = "#{LIBDIR}/adwords4r/#{vname}"
+        mkdir_p gendir
+        AdWords::Service.getServices(v).each do |name|
+            worker = WSDL::SOAP::WSDL2Ruby.new
+            worker.logger = logger
+            worker.location = getWsdlFileName(vname,name)
+            worker.basedir = gendir
+            worker.opt.update(getWsdlOpt(name))
+            worker.run
+            fixImport(v, File.join(gendir, "#{name}Driver.rb"))
+        end
+    end
+end
+
+def fixImport(version, file)
+    vname = "v#{version}"
+    tempfile = file + '.tmp'
+    outfile = File.new(tempfile,"w")
+    File.open(file, "r") do |infile|
+        req = 0
+        infile.each do |l|
+            if (l =~/require/) then
+#                outfile.puts l.gsub(/require \'(.*)Service.rb\'/, 'require #\'adwords4r/' + vname + '/\1Service\'')
+                outfile.puts l.gsub(/require \'(.*)Service.rb\'/, 'require \'adwords4r/' + vname + '/\1Service\'')
+                req = req + 1
+            else
+                if (req == 2) then
+                    outfile.puts "module AdWordsV#{version}"
+                    req = req + 1
+                end
+                outfile.puts l
+            end
+        end
+    end
+    outfile.puts "end"
+    outfile.close
+    File.rename(tempfile, file)
+end 
+
+
+def getWsdlOpt(s)
+    optcmd= {}
+    s << "Service"
+    optcmd['classdef'] = s
+    #should work but doesn't, driver name is derived from classname
+    #if you specify both it breaks, same thing for client_skelton
+    #optcmd['driver'] = s
+    optcmd['driver'] = nil
+    #optcmd['client_skelton'] = nil
+    optcmd['force'] = true
+    return optcmd
+end
+  
+def getWsdlFileName(v,s)
+    "#{WSDLDIR}/#{v}/#{s}.wsdl"
+end
+     
+def getfile(host, path)
+    puts "getting https//#{host}#{path}"
+    https = Net::HTTP.new(host, 443)
+    https.use_ssl = true
+    https.verify_mode = OpenSSL::SSL::VERIFY_NONE
+    https.start { |w| w.get2(path).body }
+end
+
+# Saves this document to the specified @var path.
+#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(content)}
+    end
+end
+
+# ====================================================================
+# Create a task that will package the Rake software into distributable
+# gem files.
+
+PKG_FILES = FileList[
+  '*.*', 
+  'Rakefile', 
+  'lib/**/*.rb', 
+  'examples/**/*.rb', 
+#  'test/**/*.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.
+Currently the following AdWords API versions are supported:
+
+* V2
+* V3
+}
+
+    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 = "Patrick Chanezon"
+    s.email = "patrick@chanezon.com"
+    s.homepage = "http://rubyforge.org/projects/adwords4r/"
+    s.requirements << 'soap4r v 1.5.4 or greater'
+    s.rubyforge_project = 'adwords4r'
+  end
+  
+    Rake::GemPackageTask.new(spec) do |t|
+      t.need_tar = true
+    end
+end
+
+require 'scripts/publish'
+

data/Readme.txt

@@ -0,0 +1,61 @@
+Google adwwords4r Library
+----------------------
+
+Welcome to adwords4r, bringing the delights of ruby programming to the AdWords world: AdWords::API.new.getAllAdWordsCampaigns(123).each {|c| puts c.name}
+
+Not much doc or comments yet
+
+docs for users
+--------------
+
+adwords4r is a ruby gem.  See http://docs.rubygems.org/read/book/1
+Install it using the gem install command.
+> gem install --remote adwords4r
+
+It's pretty easy to use.
+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
+
+If you do not use the rubygems option, you need to add
+require 'rubygems'
+at the beginning of your programs.
+
+Then   
+require 'adwords4r'
+
+adwords = AdWords::API.new
+creates a driver for the latest version of AdWords API using credentials provided in ~/.adwords.yaml
+If you want something more specific, use the optional paramters of the constructor
+adwords = AdWords::API.new(credentials, version)
+
+Then just use methods of the API against your driver.
+adwords.getAllAdWordsCampaigns(123).each {|c| puts c.name}
+
+See sample code in examples.
+
+docs for developers
+-------------------
+rake getwsdl
+    to get the wsdl files
+rake generate
+    to regenerate the bindings if needed
+rake package
+    to package the gem and create a release
+rake publish
+    to publish the gem to rubyforge
+    
+adwords4r is licensed under the BSD License
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
+GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
+THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
+
+It is fun to use adwords4r anyway...

data/Todo.txt

@@ -0,0 +1,9 @@
+adwords4r todo list
+---
+
+- gem file
+- handling quota management in the driver
+- pass in a hash for complex objects
+- comments everywhere, rdoc
+- documentation
+- more samples

data/examples/campaign.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+
+require 'adwords4r'
+require 'pp'
+
+SEP = "---"
+
+def dumpObj(o)
+    str = ""
+    o.instance_variables.each { |v| str << dumpAttr(o, v)}
+    return str << SEP
+end
+
+def dumpAttr(o, v)
+    name = v.sub(/@/,'')
+    value = eval("o.#{name}.to_s")
+    return "#{name}: #{value}\n"
+end
+
+begin
+    adwords = AdWords::API.new
+    #pp adwords.thismethodDoesNotExist()
+    adwords.getAllAdWordsCampaigns(123).each {|c| puts dumpObj(c)}
+    c = Campaign.new
+    c.dailyBudget = 10000
+    c.status = 'Paused'
+    c.name = 'Test P@ #{rand(10000}'
+    pp adwords.addCampaign(c)
+
+rescue AdWords::Error::UnknownAPICall => e
+    puts e
+rescue AdWords::Error::ApiError => e
+    puts e.code
+    puts e.message
+end
+

data/examples/framework.rb

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require 'adwords4r'
+require 'pp'
+
+adwords = AdWords::API.new

data/lib/adwords4r.rb

@@ -0,0 +1,136 @@
+require 'adwords4r/credentials'
+require 'adwords4r/services'
+require 'soap/soap'
+
+module AdWords
+
+    class API
+    
+        attr_reader :credentials, :drivers, :version
+        @methodMap = Hash.new
+        
+        def initialize(*parm)
+            if parm[0] 
+                @credentials = parm[0]
+            else
+                @credentials = AdWordsCredentials.new
+            end
+            if parm[1] 
+                @version = parm[1]
+            else
+                @version = Service.getVersions.sort.last
+            end
+            @drivers = Hash.new
+            prepareDrivers
+        end
+        
+        def method_missing(m, *args)
+            methodName = m.id2name
+            requestName = AdWords::fix_case_up(m.id2name) # upper first character
+            param = args[0]
+        
+            if valid_call?(methodName)
+                req = eval("#{requestName}.new(param)")
+                resp = eval("getDriver(methodName).#{methodName}(req)")
+                return resp
+            else
+                raise(Error::UnknownAPICall, "Unknown API Call: #{requestName}", caller)
+            end
+            # Handle AdWords Application-level error
+            rescue SOAP::FaultError => fault
+                raise(Error::ApiError.new(fault), "#{methodName} Call Failed: #{fault.faultstring.to_s}", caller)
+        end
+        
+        private
+        
+        def prepareDrivers()
+            Service.doRequire(@version)
+            Service.getServices(@version).each {|s| @drivers[s] = prepareDriver(s)}
+            @methodMap = Service.getMethodMap(@drivers)
+        end
+        
+        #pass in call name, get the driver back
+        def getDriver(call)
+            return @methodMap[call]
+        end
+        
+        def prepareDriver(s)
+            driver = eval("AdWordsV#{@version}::#{getServiceName(s)}.new")
+            @credentials.handlers.each {|h| driver.headerhandler << h}
+            #driver.wiredump_dev = STDOUT if @debug
+            driver.wiredump_file_base = "log"
+            driver.options['protocol.http.ssl_config.verify_mode'] = nil
+            #set driver.proxy if you are behing a proxy
+            return driver
+        end
+        
+        #workaround the bug: some services do not follow the naming convention
+        def getServiceName(s)
+            if s == "TrafficEstimator" then "TrafficEstimatorInterface"
+            elsif s == "Report" then "ReportServiceInterface"
+            elsif s == "Info" then "InfoServiceInterface"
+            elsif s == "KeywordTool" then "KeywordToolInterface"
+            else (s + "Service")
+            end
+        end
+        
+        def valid_call?(call)
+            return @methodMap.has_key?(call)
+        end
+    
+    end
+
+    #copied and adapted from ebay4r
+    #maybe these type of handlers should be generalized and put in soap4r 
+    #for other api projects to be able to get started more quickly
+    class Error
+        class Error < StandardError; end
+        
+        # Raised if a call is made to a method that does not exist in the AdWords SOAP API
+        class UnknownAPICall < Error; end
+        
+        # Raised if an attempt is made to instantiate a type that does not exist in the AdWords SOAP API
+        class UnknownType < Error; end
+        
+        # Raised if a call returns with a SOAP error, gives you easy access to adwords error fields
+        class ApiError < Error
+        
+            attr_accessor :soap_faultcode
+            attr_accessor :soap_faultstring
+            attr_accessor :code
+            attr_accessor :internal
+            attr_accessor :message
+            attr_accessor :trigger
+            attr_accessor :violations
+            
+            def initialize(fault)
+                @soap_faultcode = getOrNil(fault, 'faultcode')
+                @soap_faultstring = getOrNil(fault, 'faultstring')
+                @code = getOrNil(fault.detail, 'code')
+                @internal = getOrNil(fault.detail,'internal')
+                @message = getOrNil(fault.detail,'message')
+                @trigger = getOrNil(fault.detail,'trigger')
+                @violations = getOrNil(fault.detail,'violations')
+            end
+            
+            private
+            def getOrNil(obj, meth)
+                obj.respond_to?(meth) ? eval("obj.#{meth}") : nil
+            end
+        end
+    end
+
+    # These class module methods are helper functions
+    class <<self 
+    
+      def fix_case_up(name)
+        name[0] = name[0,1].upcase # upper first character
+        name
+      end
+    
+      def fix_case_down(name)
+        name[0] = name[0,1].downcase
+        name
+      end
+    end
+end