google-adwords-api 0.5.0 → 0.5.1

data/ChangeLog

@@ -1,3 +1,11 @@
+0.5.1:
+  - Require google-ads-common 0.6.3 or later from now on.
+  - Support for CAPTCHA challenge handling.
+  - Added .gemspec and updated packaging process.
+  - Removed explicit require for RubyGems, see README.
+  - Fixed reports retrieval via curb HTTPI backend.
+  - Removed support for deprecated BulkOpportunityService.
+
 0.5.0:
   - Removed deprecated API versions (pre-v201109).
   - Example updates and revamp.

data/README

@@ -28,30 +28,21 @@ which is installed automatically as a dependency.
 
 The following gem libraries are required:
   - savon v0.9.7
-  - google-ads-common v0.6.1 or later.
+  - google-ads-common v0.6.3 or later.
 
 
 == 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'
+Include the library with 'require':
    require 'adwords_api'
 
+Then create an API instance:
    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 APIs. It uses a config file in:
-ENV['HOME']/adwords_api.yml to read all of your configurations.
+
+The created API object will grant you access to all the services for all of the
+currently supported vesions of the APIs. It uses a config file in:
+  ENV['HOME']/adwords_api.yml to read all of your configurations by default.
+
 There is an example configuration file shipped with these libraries.
 
 You can also pass API a manually constructed config hash like:
@@ -85,6 +76,17 @@ please set the appropriate options in the config file or config hash. E.g.:
      :proxy => 'http://user:password@proxy_hostname:8080'
    }
 
+*Note*: if you are using Ruby 1.8 you may need to include RubyGems to be able
+to require other gems code. There are several ways to do it, the easiest one is
+to pass '-rubygems' parameter to the ruby interpreter:
+   $ ruby -rubygems my_program_that_uses_gems
+
+you can also set this up in the environment:
+   $ export RUBYOPT="rubygems"
+
+or add it to the bash configuration file:
+   $ echo 'export RUBYOPT="rubygems"' >> ~/.bashrc
+
 
 === 2.1 - Ruby names for a Ruby library:
 
@@ -175,8 +177,8 @@ respond in gzipped format. All requests are sent uncompressed regardless.
  $ rake generate
 to regenerate the stubs if needed
 
- $ rake package
-to package the gem and create a release
+ $ gem build google-adwords-api.gemspec
+to build the gem
 
  $ rake test
 to run unit tests on the library
@@ -197,7 +199,7 @@ Questions can be asked on forum
 
 == Licence
 
-Copyright 2011, Google Inc. All Rights Reserved.
+Copyright 2010-2012, 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_api.yml

@@ -0,0 +1,40 @@
+---
+# 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:
+  # Authentication method, methods currently supported: OAuth, ClientLogin.
+  :method: ClientLogin
+
+  # Auth parameters for OAuth method.
+  # Set the OAuth consumer key and secret. Anonymous values can be used for
+  # testing, and real values can be obtained by registering your application:
+  # http://code.google.com/apis/accounts/docs/RegistrationForWebAppsAuto.html
+  #:oauth_consumer_key: anonymous
+  #:oauth_consumer_secret: anonymous
+  # If you manage or store access token manually, you can specify it here.
+  #:oauth_token: INSERT_OAUTH_TOKEN_HERE
+  # If you need to change signature method, specify it here.
+  #:oauth_signature_method: HMAC-SHA1
+  # Token secret for HMAC-SHA1 method.
+  #:oauth_token_secret: INSERT_OAUTH_TOKEN_SECRET_HERE
+
+  # Auth parameters for ClientLogin method.
+  :password: INSERT_YOUR_PASSWORD_HERE
+  :email: INSERT_YOUR_LOGIN_EMAIL_HERE
+  # To manage your auth tokens manually, use the 'auth_token' property.
+  #:auth_token: INSERT_AUTH_TOKEN_HERE
+
+  # Other parameters.
+  :developer_token: INSERT_YOUR_DEVELOPER_TOKEN_HERE
+  :client_customer_id: INSERT_YOUR_CLIENT_CUSTOMER_ID_HERE
+  :user_agent: INSERT_YOUR_USER_AGENT_HERE
+:service:
+  :environment: SANDBOX
+:connection:
+  # Enable to request all responses to be compressed.
+  :enable_gzip: false
+  # If your proxy connection requires authentication, make sure to include it in
+  # the URL, e.g.: http://user:password@proxy_hostname:8080
+  # :proxy: INSERT_PROXY_HERE
+:library:
+  :log_level: INFO

data/examples/v201109/account_management/create_account.rb

@@ -23,7 +23,6 @@
 #
 # Tags: CreateAccountService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 require 'adwords_api/utils'
 

data/examples/v201109/account_management/get_account_alerts.rb

@@ -23,7 +23,6 @@
 #
 # Tags: AlertService.get
 
-require 'rubygems'
 require 'adwords_api'
 require 'adwords_api/utils'
 

data/examples/v201109/account_management/get_account_changes.rb

@@ -23,7 +23,6 @@
 #
 # Tags: CustomerSyncService.get
 
-require 'rubygems'
 require 'adwords_api'
 require 'date'
 require 'pp'

data/examples/v201109/account_management/get_account_hierarchy.rb

@@ -23,7 +23,6 @@
 #
 # Tags: ServicedAccountService.get
 
-require 'rubygems'
 require 'adwords_api'
 require 'adwords_api/utils'
 

data/examples/v201109/account_management/get_client_customer_id.rb

@@ -24,7 +24,6 @@
 #
 # Tags: InfoService.get
 
-require 'rubygems'
 require 'adwords_api'
 require 'adwords_api/utils'
 

data/examples/v201109/account_management/get_client_unit_usage.rb

@@ -23,7 +23,6 @@
 #
 # Tags: InfoService.get
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/basic_operations/add_ad_group.rb

@@ -23,7 +23,6 @@
 #
 # Tags: AdGroupService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/basic_operations/add_campaign.rb

@@ -22,7 +22,6 @@
 #
 # Tags: CampaignService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/basic_operations/add_keywords.rb

@@ -23,7 +23,6 @@
 #
 # Tags: AdGroupCriterionService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/basic_operations/add_text_ads.rb

@@ -23,7 +23,6 @@
 #
 # Tags: AdGroupAdService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/basic_operations/delete_ad.rb

@@ -23,7 +23,6 @@
 #
 # Tags: AdGroupAdService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/basic_operations/delete_ad_group.rb

@@ -23,7 +23,6 @@
 #
 # Tags: AdGroupService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/basic_operations/delete_campaign.rb

@@ -23,7 +23,6 @@
 #
 # Tags: CampaignService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/basic_operations/delete_keyword.rb

@@ -23,7 +23,6 @@
 #
 # Tags: AdGroupCriterionService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/basic_operations/get_ad_groups.rb

@@ -23,7 +23,6 @@
 #
 # Tags: AdGroupService.get
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/basic_operations/get_campaigns.rb

@@ -22,7 +22,6 @@
 #
 # Tags: CampaignService.get
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/basic_operations/get_keywords.rb

@@ -23,7 +23,6 @@
 #
 # Tags: AdGroupCriterionService.get
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/basic_operations/get_text_ads.rb

@@ -23,7 +23,6 @@
 #
 # Tags: AdGroupAdService.get
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/basic_operations/pause_ad.rb

@@ -23,7 +23,6 @@
 #
 # Tags: AdGroupAdService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/basic_operations/update_ad_group.rb

@@ -23,7 +23,6 @@
 #
 # Tags: AdGroupService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/basic_operations/update_campaign.rb

@@ -23,7 +23,6 @@
 #
 # Tags: CampaignService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/basic_operations/update_keyword.rb

@@ -23,7 +23,6 @@
 #
 # Tags: AdGroupCriterionService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/campaign_management/add_experiment.rb

@@ -26,7 +26,6 @@
 #
 # Tags: ExperimentService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/campaign_management/add_keywords_in_bulk.rb

@@ -24,7 +24,6 @@
 # Tags: MutateJobService.mutate, MutateJobService.get,
 #       MutateJobService.getResult
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/campaign_management/add_location_extension.rb

@@ -23,7 +23,6 @@
 #
 # Tags: GeoLocationService.get, CampaignAdExtensionService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/campaign_management/add_location_extension_override.rb

@@ -24,7 +24,6 @@
 #
 # Tags: AdExtensionOverrideService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/campaign_management/get_all_disapproved_ads.rb

@@ -23,7 +23,6 @@
 #
 # Tags: AdGroupAdService.get
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/campaign_management/promote_experiment.rb

@@ -23,7 +23,6 @@
 #
 # Tags: ExperimentService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/campaign_management/set_ad_parameters.rb

@@ -23,7 +23,6 @@
 #
 # Tags: AdGroupAdService.mutate, AdParamService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/campaign_management/validate_text_ad.rb

@@ -23,7 +23,6 @@
 #
 # Tags: CampaignService.mutate
 
-require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109

data/examples/v201109/error_handling/handle_captcha_challenge.rb

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+# Encoding: utf-8
+#
+# Author:: api.dklimkin@gmail.com (Danial Klimkin)
+#
+# Copyright:: Copyright 2012, 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 handle 'CAPTCHA required' authorization
+# errors. Refer to the best practices guide on how to avoid this error:
+#
+# http://code.google.com/apis/adwords/docs/guides/bestpractices.html#auth_tokens
+
+require 'adwords_api'
+
+API_VERSION = :v201109
+
+MAX_RETRIES = 500
+
+def handle_captcha_challenge()
+  # Initialize token variable.
+  logintoken = nil
+
+  # This code will repeatedly request authToken from the server until it gets
+  # a CAPTCHA challenge request. It is here for illustration purposes only
+  # and should never be used in a real application.
+  begin
+    MAX_RETRIES.times do |retry_number|
+      puts "Running request %d of %d..." % [retry_number + 1, MAX_RETRIES]
+      # Forcing library to request a new authorization token.
+      adwords = AdwordsApi::Api.new
+      auth_token = adwords.authorize()
+    end
+    # Still no challenge, make sure ClientLogin authorization is used.
+    raise StandardError, "Failed to get challenge after %d requests." %
+        MAX_RETRIES
+  rescue AdsCommon::Errors::CaptchaRequiredError => e
+    logintoken = e.captcha_token
+  end
+
+  puts "CaptchaRequiredError occurred. To recover download the image and type" +
+      " the CAPTCHA below: %s\n" % e.captcha_url
+  puts 'Enter code or ENTER to retry: '
+  logincaptcha = gets.chomp
+
+  # Initialize variable for extra parameters.
+  credentials = {}
+  if logincaptcha and !logincaptcha.empty?
+    credentials[:logincaptcha] = logincaptcha
+    credentials[:logintoken] = logintoken
+  end
+
+  begin
+    adwords = AdwordsApi::Api.new
+    auth_token = adwords.authorize(credentials)
+    puts "Successfully retrieved authToken: " + auth_token
+  rescue AdsCommon::Errors::CaptchaRequiredError => e
+    puts 'Invalid CAPTCHA text entered.'
+    raise e
+  end
+end
+
+if __FILE__ == $0
+  begin
+    handle_captcha_challenge()
+
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
+
+  # API errors.
+  rescue AdwordsApi::Errors::ApiException => e
+    puts "Message: %s" % e.message
+    puts 'Errors:'
+    e.errors.each_with_index do |error, index|
+      puts "\tError [%d]:" % (index + 1)
+      error.each do |field, value|
+        puts "\t\t%s: %s" % [field, value]
+      end
+    end
+  end
+end