google-adwords-api 0.1.0

data/README

@@ -0,0 +1,178 @@
+= Google AdWords Client Library
+
+Welcome to the next generation Google-developed Ruby client library for the
+AdWords API!
+
+Please note that this is an early PREVIEW of the client library, under heavy
+development! A lot of things (such as documentation and full unit testing) are
+still missing or being worked on.
+
+It contains full support for v13, v200909, v201003, v201008 and v201101, with
+full stubs, and a simplified programming interface that lets you handle
+everything in native Ruby collections, instead of forcing you to deal with SOAP
+library-generated objects.
+
+
+= Docs for Users
+
+== 1 - Installation:
+
+google-adwords-api is a ruby gem.  See http://docs.rubygems.org/read/book/1
+
+Install it using the gem install command.
+   $ gem install --remote google-adwords-api
+
+The following gem libraries are required:
+- soap4r v1.5.8
+- httpclient v2.1.2 or greater
+- google-ads-common v0.1.x
+
+
+== 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.
+   $ export RUBYOPT=rubygems
+or
+   $ ruby -rubygems my_program_that_uses_gems
+
+If you are running Ruby 1.8 and do not use the rubygems option, you need to add
+   require 'rubygems'
+at the beginning of your programs.
+
+Then:
+   gem 'google-adwords-api'
+   require 'adwords_api'
+
+   adwords = AdwordsApi::Api.new
+creates an Api object that will grant you access to all the services for all of
+the currently supported vesions of the AdWords API. It uses a config file in
+ENV['HOME']/adwords_api.yml to read all of your configurations.
+There is an example config file in the root adwords_api directory.
+You can also pass API a manually constructed config hash like:
+   adwords = AdwordsApi::Api.new({
+     :authentication => {
+         :method => 'ClientLogin',
+         :developer_token => 'DEVELOPER_TOKEN',
+         :user_agent => 'Ruby Sample',
+         :password => 'PASSWORD',
+         :email => 'user@domain.com'
+         :client_email => 'user2@domain.com'
+     },
+     :service => {
+       :environment => 'Production'
+     }
+   })
+
+Then, just specify which service you're looking to use, and which version:
+   campaign_srv = adwords.service(:CampaignService, :v201101)
+
+and you should now be able to just use the API methods in the object you were
+returned:
+   campaigns = campaign_srv.get({}) # Empty selector to get all
+
+See the code in the examples directory for working examples you can build from.
+
+*Note*: if your setup requires you to send connections through a proxy server,
+please set the appropriate options in the config file or config hash. E.g.:
+   config[:connection] = {
+     :proxy => 'http://user:password@proxy_hostname:8080/path'
+   }
+
+
+=== 2.1 - Ruby names for a Ruby library:
+
+In order to make things more Ruby-like for our Ruby developers, we've renamed
+API objects and methods to more closely match Ruby conventions. This means using
+snake_case for methods and parameters, and UpperCamelCase for class names.
+
+For example, the 'getReportFields' method of the ReportDefinitionService is
+named 'get_report_fields' in the client library. You invoke it by doing:
+   response = report_def_srv.get_report_fields(report_type)
+
+The 'get' method, on the other hand, returns a ReportDefinitionPage object which
+has an 'entries' and a 'total_num_entries' field. So, to access the return
+values, you would do:
+   response = report_def_srv.get(selector)
+   num_entries = response[:rval][:total_num_entries]
+
+Essentially, all you have to do is follow Ruby conventions, and the library will
+do the rest. All of the examples are written following this standard.
+
+If, however, you would prefer to use the names as provided in the AdWords
+documentation, please disable the 'use_ruby_names' option under the 'service'
+category in the config:
+   config[:service][:use_ruby_names] = false
+
+Disabling Ruby names is an experimental feature, and it is not recommended.
+
+
+=== 2.2 - Using the Sandbox:
+
+In order to use the sandbox, make sure that the 'environment' parameter under
+'service' in the configuration is set to Sandbox.
+   config[:service] = {
+     :environment => 'Sandbox'
+   }
+
+
+=== 2.3 - Logging:
+
+It is often useful to see a trace of the raw SOAP XML being sent and received.
+The quickest way of achieving this when debugging your application is by setting
+the ADWORDSAPI_DEBUG environment variable to TRUE; e.g. in the bash shell:
+   $ export ADWORDSAPI_DEBUG=TRUE
+or from your Ruby code:
+   ENV['ADWORDSAPI_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 log_to_file method of the loggers inside your
+AdwordsApi::Api object:
+   adwords = AdwordsApi::Api.new
+   adwords.request_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 another directory as an
+optional parameter to log_to_file:
+   adwords.request_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
+
+ $ 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 test
+to run unit tests on the library
+
+
+= Copyright/License Info
+
+Copyright 2011, 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.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/Rakefile

@@ -0,0 +1,117 @@
+#!/usr/bin/ruby
+#
+# Authors:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
+#
+# License:: Licensed under the Apache License, Version 2.0 (the "License");
+#           you may not use this file except in compliance with the License.
+#           You may obtain a copy of the License at
+#
+#           http://www.apache.org/licenses/LICENSE-2.0
+#
+#           Unless required by applicable law or agreed to in writing, software
+#           distributed under the License is distributed on an "AS IS" BASIS,
+#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+#           implied.
+#           See the License for the specific language governing permissions and
+#           limitations under the License.
+#
+# Rakefile for the AdWords API client library.
+
+# A little trick so we can load things from the lib/ directory without having
+# to patch the "require" statements in the files
+$:.unshift File.join(File.dirname(__FILE__), 'lib')
+
+require 'rubygems'
+gem 'google-ads-common'
+require 'ads_common/build/soap4r_generator'
+require 'ads_common/config'
+require 'adwords_api/api_config'
+require 'adwords_api/extensions'
+
+# Configure some constants and built-in tasks
+$PROJECT_NAME = 'adwords_api'
+$GEM_NAME = 'google-adwords-api'
+$API_NAME = 'AdWords API'
+$CURRENT_VERSION = AdwordsApi::ApiConfig::CLIENT_LIB_VERSION
+$PRODDIR = 'adwords_api'
+$ADS_COMMON_VERSION = '~> 0.2.0'
+
+# Configure module / namespace
+$MODULE = AdwordsApi
+
+# Configure config file location.
+$CONFIG_FILE = 'adwords_api.yml'
+
+# Configure gem details
+$GEM_SUMMARY = "Client library for the AdWords API."
+description = "#{$PROJECT_NAME} provides an easy to use way to access " +
+    "the AdWords API in Ruby.\nCurrently the following AdWords API versions " +
+    "are supported:"
+versions = AdwordsApi::ApiConfig.versions.map { |version| version.to_s }
+versions.sort.each do |version|
+  description += "\n  * #{version}"
+end
+$GEM_DESCRIPTION = description
+$GEM_AUTHORS = ['Sergio Gomes']
+$GEM_EMAIL = 'api.sgomes@gmail.com'
+$GEM_HOMEPAGE = 'http://code.google.com/p/google-api-adwords-ruby/'
+
+
+# Configure code generation for the AdWords API client library.
+module Generator
+
+  class << Generator
+    include AdsCommon::Build::Soap4rGenerator
+  end
+
+  def self.api_config
+    AdwordsApi::ApiConfig
+  end
+
+  def self.config
+    filename = File.join(ENV['HOME'], $CONFIG_FILE)
+    if File.exist?(filename)
+      AdsCommon::Config.new(filename)
+    else
+      nil
+    end
+  end
+
+  def self.extension_config
+    AdwordsApi::Extensions
+  end
+
+  private
+
+  # Helper method to create a link to a method's entry in the API online docs.
+  #
+  # Args:
+  # - version: the API version (as an integer)
+  # - service: the service name (as a string)
+  # - method: the method name (as a string)
+  #
+  # Returns:
+  # The URL to the method's entry in the documentation (as a string).
+  # nil if none.
+  #
+  def self.doc_link(version, service, method)
+    if version.to_s == 'v13'
+      base = 'http://code.google.com/apis/adwords/docs/developer/'
+      url = base + service.to_s + '.html#' + method
+      return url
+    elsif version.to_s =~ /v20\d[\d]+/
+      base = 'http://code.google.com/apis/adwords/docs/reference/'
+      url = base + version.to_s + '/' + service.to_s + '.html#' + method
+      return url
+    else
+      return nil
+    end
+  end
+
+end
+
+
+# Import tasks in common file
+require 'ads_common/build/rake_common'

data/adwords_api.yml

@@ -0,0 +1,21 @@
+---
+# This is an example configuration file for the AdWords API client library.
+# Please fill in the required fields, and copy it over to your home directory.
+:authentication:
+  :method: ClientLogin
+  :developer_token: INSERT_YOUR_DEVELOPER_TOKEN_HERE
+  :user_agent: INSERT_YOUR_USER_AGENT_HERE
+  :password: INSERT_YOUR_PASSWORD_HERE
+  :email: INSERT_YOUR_LOGIN_EMAIL_HERE
+  :client_email: INSERT_YOUR_CLIENT_EMAIL_HERE
+  # If you would like to manage your auth tokens manually, use the 'auth_token'
+  # property.
+  #:auth_token: INSERT_AUTH_TOKEN_HERE
+:service:
+  :environment: Production
+  :use_ruby_names: true
+:connection:
+  :strict_ssl_verification: false
+  # If your proxy connection requires authentication, make sure to include it in
+  # the URL, e.g.: http://user:password@proxy_hostname:8080/path
+  # :proxy: INSERT_PROXY_HERE

data/examples/v200909/add_ad_extension_override.rb

@@ -0,0 +1,91 @@
+#!/usr/bin/ruby
+#
+# Author:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
+#
+# License:: Licensed under the Apache License, Version 2.0 (the "License");
+#           you may not use this file except in compliance with the License.
+#           You may obtain a copy of the License at
+#
+#           http://www.apache.org/licenses/LICENSE-2.0
+#
+#           Unless required by applicable law or agreed to in writing, software
+#           distributed under the License is distributed on an "AS IS" BASIS,
+#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+#           implied.
+#           See the License for the specific language governing permissions and
+#           limitations under the License.
+#
+# This example illustrates override an ad extension for a specific ad, by
+# creating an ad extension override. To create a campaign, run add_campaign.rb.
+# To create an ad, run add_ads.rb.
+#
+# Tags: AdExtensionOverrideService.mutate
+
+require 'rubygems'
+gem 'google-adwords-api'
+require 'adwords_api'
+
+API_VERSION = :v200909
+
+def add_ad_extension_override()
+  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
+  # when called without parameters.
+  adwords = AdwordsApi::Api.new
+  ad_ext_override_srv =
+      adwords.service(:AdExtensionOverrideService, API_VERSION)
+
+  ad_id = 'INSERT_AD_ID_HERE'.to_i
+  campaign_ad_extension_id = 'INSERT_CAMPAIGN_AD_EXTENSION_ID_HERE'.to_i
+
+  # Create operation.
+  operation = {
+    :operator => 'ADD',
+    :operand => {
+      :ad_id => ad_id,
+      :ad_extension => {
+        :id => campaign_ad_extension_id
+      }
+    }
+  }
+
+  # Add override.
+  response = ad_ext_override_srv.mutate([operation])
+  ad_ext_override = response[:value].first
+  puts 'Ad extension override was successfully added.'
+end
+
+if __FILE__ == $0
+  # To enable logging of SOAP requests, set the ADWORDSAPI_DEBUG environment
+  # variable to 'true'. This can be done either from your operating system
+  # environment or via code, as done below.
+  ENV['ADWORDSAPI_DEBUG'] = 'false'
+
+  begin
+    add_ad_extension_override()
+
+  # Connection error. Likely transitory.
+  rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => e
+    puts 'Connection Error: %s' % e
+    puts 'Source: %s' % e.backtrace.first
+
+  # API Error.
+  rescue AdwordsApi::Errors::ApiException => e
+    puts 'API Exception caught.'
+    puts 'Message: %s' % e.message
+    puts 'Code: %d' % e.code if e.code
+    puts 'Trigger: %s' % e.trigger if e.trigger
+    puts 'Errors:'
+    if e.errors
+      e.errors.each_with_index do |error, index|
+        puts ' %d. Error type is %s. Fields:' % [index + 1, error[:xsi_type]]
+        error.each_pair do |field, value|
+          if field != :xsi_type
+            puts '     %s: %s' % [field, value]
+          end
+        end
+      end
+    end
+  end
+end

data/examples/v200909/add_ad_group.rb

@@ -0,0 +1,98 @@
+#!/usr/bin/ruby
+#
+# Author:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
+#
+# License:: Licensed under the Apache License, Version 2.0 (the "License");
+#           you may not use this file except in compliance with the License.
+#           You may obtain a copy of the License at
+#
+#           http://www.apache.org/licenses/LICENSE-2.0
+#
+#           Unless required by applicable law or agreed to in writing, software
+#           distributed under the License is distributed on an "AS IS" BASIS,
+#           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+#           implied.
+#           See the License for the specific language governing permissions and
+#           limitations under the License.
+#
+# This example illustrates how to create an ad group. To create a campaign, run
+# add_campaign.rb.
+#
+# Tags: AdGroupService.mutate
+
+require 'rubygems'
+gem 'google-adwords-api'
+require 'adwords_api'
+
+API_VERSION = :v200909
+
+def add_ad_group()
+  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
+  # when called without parameters.
+  adwords = AdwordsApi::Api.new
+  ad_group_srv = adwords.service(:AdGroupService, API_VERSION)
+
+  campaign_id = 'INSERT_CAMPAIGN_ID_HERE'.to_i
+
+  # Prepare for adding ad group.
+  operation = {
+    :operator => 'ADD',
+    :operand => {
+      :name => 'Earth to Mars Cruises #%s' % (Time.new.to_f * 1000).to_i,
+      :status => 'ENABLED',
+      :campaign_id => campaign_id,
+      :bids => {
+        # The 'xsi_type' field allows you to specify the xsi:type of the object
+        # being created. It's only necessary when you must provide an explicit
+        # type that the client library can't infer.
+        :xsi_type => 'ManualCPCAdGroupBids',
+        :keyword_max_cpc => {
+          :amount => {
+            :micro_amount => 10000000
+          }
+        }
+      },
+    }
+  }
+
+  # Add ad group.
+  response = ad_group_srv.mutate([operation])
+  ad_group = response[:value].first
+  puts 'Ad group id %d was successfully added.' % ad_group[:id]
+end
+
+if __FILE__ == $0
+  # To enable logging of SOAP requests, set the ADWORDSAPI_DEBUG environment
+  # variable to 'true'. This can be done either from your operating system
+  # environment or via code, as done below.
+  ENV['ADWORDSAPI_DEBUG'] = 'false'
+
+  begin
+    add_ad_group()
+
+  # Connection error. Likely transitory.
+  rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => e
+    puts 'Connection Error: %s' % e
+    puts 'Source: %s' % e.backtrace.first
+
+  # API Error.
+  rescue AdwordsApi::Errors::ApiException => e
+    puts 'API Exception caught.'
+    puts 'Message: %s' % e.message
+    puts 'Code: %d' % e.code if e.code
+    puts 'Trigger: %s' % e.trigger if e.trigger
+    puts 'Errors:'
+    if e.errors
+      e.errors.each_with_index do |error, index|
+        puts ' %d. Error type is %s. Fields:' % [index + 1, error[:xsi_type]]
+        error.each_pair do |field, value|
+          if field != :xsi_type
+            puts '     %s: %s' % [field, value]
+          end
+        end
+      end
+    end
+  end
+end