google-adx-buyer-api 0.2.0 → 0.4.0

data/ChangeLog

@@ -1,2 +1,9 @@
+0.4.0:
+  - Compatibility with google-adwords-api-0.4.1.
+  - Switched to Savon backend.
+
+0.3.0:
+  - Compatibility with google-adwords-api-0.2.0.
+
 0.2.0:
   - Initial release.

data/README

@@ -6,10 +6,9 @@ AdWords and DoubleClick Ad Exchange Buyer API!
 Please note that this is an early PREVIEW of the client library, still under
 development.
 
-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.
+It contains full support for v13, v200909, v201003, v201008, v201101 and
+v201109, with full stubs, and a simplified programming interface that lets you
+handle everything in native Ruby collections.
 
 
 = Docs for Users
@@ -28,9 +27,9 @@ Buyer client library examples. You need the AdWords library in order to use it
 which is installed automatically as a dependency.
 
 The following gem libraries are required:
-- soap4r v1.5.8
-- httpclient v2.1.2 or greater
-- google-ads-common v0.2.1 or later.
+  - savon v0.9.6
+  - httpclient v2.1.2 or greater
+  - google-ads-common v0.5.4 or later.
 
 
 == 2 - Using the client library:
@@ -63,27 +62,28 @@ You can also pass API a manually constructed config hash like:
          :developer_token => 'DEVELOPER_TOKEN',
          :user_agent => 'Ruby Sample',
          :password => 'PASSWORD',
-         :email => 'user@domain.com'
-         :client_email => 'user2@domain.com'
+         :email => 'user@domain.com',
+         :client_customer_id => '012-345-6789'
      },
      :service => {
-       :environment => 'Production'
+       :environment => 'PRODUCTION'
      }
    })
 
 Then, just specify which service you're looking to use, and which version:
-   campaign_srv = adwords.service(:CampaignService, :v201101)
+   campaign_srv = adwords.service(:CampaignService, :v201109)
 
 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
+   # Get 'Id', 'Name' and 'Status' fields of all campaigns.
+   campaigns = campaign_srv.get({:fields => ['Id', 'Name', 'Status']})
 
 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'
+     :proxy => 'http://user:password@proxy_hostname:8080'
    }
 
 
@@ -106,20 +106,13 @@ values, you would do:
 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'
+     :environment => 'SANDBOX'
    }
 
 
@@ -127,40 +120,49 @@ In order to use the sandbox, make sure that the 'environment' parameter under
 
 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'
+the library.log_level configuration variable to 'DEBUG':
+   config[:library] = {
+     :log_level => 'DEBUG'
+   }
+or via configuration file (see example).
 
 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:
+There's also an option of logging requests and XML to a file. In order to enable
+this, you should create a standard Logger object and pass it to the library:
+   require 'logger'
+   logger = Logger.new('path/to/log_filename')
+   logger.level = Logger::DEBUG
    adwords = AdwordsApi::Api.new
-   adwords.request_logger.log_to_file
-   adwords.xml_logger.log_to_file
+   adwords.logger = logger
+
+Request details and units spend are logged at the INFO log level, while raw HTTP
+headers and XML dumps are logged at the DEBUG log level. For more details on
+using Logger refer to the Ruby Logger documentation.
 
-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/')
+=== 2.4 - Calculating unit spend:
 
-The files will be named request_info and soap_xml, respectively.
+Each AdWords API operation performed consumes a certain number of API units, as
+specified in the rate sheet:
+  http://code.google.com/apis/adwords/docs/ratesheet.html
+
+The amount of units spent is returned in the header part of the SOAP response.
+This information can be obtained by passing a user block during method call:
+  response = report_def_srv.get(selector) do |header|
+    puts "Units spent: %d" % header[:units]
+  end
+
+You can also retrieve the response body as the second block parameter:
+  report_def_srv.get(selector) {|header, body| ... }
 
 
 = Docs for Developers
 
 == Rake targets
 
- $ rake getwsdl
-to get the wsdl files
-
  $ rake generate
-to regenerate the bindings if needed
+to regenerate the stubs if needed
 
  $ rake package
 to package the gem and create a release

data/Rakefile

@@ -17,7 +17,7 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# DoubleClick Ad Exchange Buyer API Rakefile
+# DoubleClick Ad Exchange Buyer API Rakefile.
 #
 
 require 'rubygems'
@@ -28,7 +28,7 @@ docs = ['README', 'COPYING', 'ChangeLog']
 
 spec = Gem::Specification.new do |s|
   s.name = 'google-adx-buyer-api'
-  s.version = '0.2.0'
+  s.version = '0.4.0'
   s.author = 'Danial Klimkin'
   s.email = 'api.dklimkin@gmail.com'
   s.homepage = 'http://code.google.com/p/google-api-ads-ruby/'
@@ -39,7 +39,7 @@ spec = Gem::Specification.new do |s|
   s.files = files
   s.has_rdoc = true
   s.extra_rdoc_files = docs
-  s.add_dependency('google-adwords-api', '~> 0.1.2')
+  s.add_dependency('google-adwords-api', '~> 0.4.1')
 end
 
 Rake::GemPackageTask.new(spec) do |pkg|

data/examples/v201003/add_ad_group.rb

@@ -32,6 +32,11 @@ 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
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
   ad_group_srv = adwords.service(:AdGroupService, API_VERSION)
 
   campaign_id = 'INSERT_CAMPAIGN_ID_HERE'.to_i
@@ -64,11 +69,6 @@ def add_ad_group()
 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()
 

data/examples/v201003/add_ad_group_criteria.rb

@@ -32,6 +32,11 @@ def add_ad_group_criteria()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
   ad_group_criterion_srv =
       adwords.service(:AdGroupCriterionService, API_VERSION)
 
@@ -66,11 +71,6 @@ def add_ad_group_criteria()
 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_criteria()
 

data/examples/v201003/add_ads.rb

@@ -33,6 +33,11 @@ def add_ads()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
   ad_group_ad_srv = adwords.service(:AdGroupAdService, API_VERSION)
 
   ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
@@ -76,11 +81,6 @@ def add_ads()
 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_ads()
 

data/examples/v201003/add_campaign.rb

@@ -31,6 +31,11 @@ def add_campaign()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
   campaign_srv = adwords.service(:CampaignService, API_VERSION)
 
   # Prepare for adding campaign.
@@ -67,11 +72,6 @@ def add_campaign()
 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_campaign()
 

data/examples/v201003/add_negative_campaign_criterion.rb

@@ -32,6 +32,11 @@ def add_negative_campaign_criterion()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
   campaign_criterion_srv =
       adwords.service(:CampaignCriterionService, API_VERSION)
 
@@ -61,11 +66,6 @@ def add_negative_campaign_criterion()
 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_negative_campaign_criterion()
 

data/examples/v201003/add_placement_performance_report_definition.rb

@@ -32,6 +32,11 @@ def add_placement_performance_report_definition()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
   report_def_srv = adwords.service(:ReportDefinitionService, API_VERSION)
 
   ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
@@ -74,11 +79,6 @@ def add_placement_performance_report_definition()
 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_placement_performance_report_definition()
 

data/examples/v201003/check_campaigns.rb

@@ -32,6 +32,11 @@ def check_campaigns()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
   campaign_srv = adwords.service(:CampaignService, API_VERSION)
 
   # Enable 'validate only'
@@ -98,11 +103,6 @@ def check_campaigns()
 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
     check_campaigns()
 

data/examples/v201003/delete_ad.rb

@@ -32,6 +32,11 @@ def delete_ad()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
   ad_group_ad_srv = adwords.service(:AdGroupAdService, API_VERSION)
 
   ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
@@ -60,11 +65,6 @@ def delete_ad()
 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
     delete_ad()
 

data/examples/v201003/delete_ad_group.rb

@@ -32,6 +32,11 @@ def delete_ad_group()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
   ad_group_srv = adwords.service(:AdGroupService, API_VERSION)
 
   ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
@@ -52,11 +57,6 @@ def delete_ad_group()
 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
     delete_ad_group()
 

data/examples/v201003/delete_ad_group_criterion.rb

@@ -32,6 +32,11 @@ def delete_ad_group_criterion()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
   ad_group_criterion_srv =
       adwords.service(:AdGroupCriterionService, API_VERSION)
 
@@ -61,11 +66,6 @@ def delete_ad_group_criterion()
 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
     delete_ad_group_criterion()
 

data/examples/v201003/delete_campaign.rb

@@ -32,6 +32,11 @@ def delete_campaign()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
   campaign_srv = adwords.service(:CampaignService, API_VERSION)
 
   campaign_id = 'INSERT_CAMPAIGN_ID_HERE'.to_i
@@ -53,11 +58,6 @@ def delete_campaign()
 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
     delete_campaign()