google-adwords-api 0.7.2 → 0.8.0

data/ChangeLog

@@ -1,3 +1,9 @@
+0.8.0:
+  - Removed deprecated API versions v201109, v201109_1.
+  - Removed support for deprecated Sandbox, see http://goo.gl/Plu3o
+  - Require google-ads-common 0.9.0 or later from now on.
+  - Added support for AOuth2.0 JWT, removed OAuth1.0a support.
+
 0.7.2:
   - Fixed issue #87 specific to ruby1.8.
 

data/README

@@ -3,9 +3,9 @@
 Welcome to the next generation Google-developed Ruby client library for the
 AdWords and DoubleClick Ad Exchange Buyer API!
 
-It contains full support for v201109, v201109_1, v201206 and v201209, with full
-stubs, and a simplified programming interface that lets you handle everything in
-native Ruby collections.
+It contains full support for v201206 and v201209, with full stubs, and a
+simplified programming interface that lets you handle everything in native
+Ruby collections.
 
 
 = Docs for Users
@@ -105,13 +105,16 @@ 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.
 
 
-=== 2.2 - Using the Sandbox:
+=== 2.2 - Using the Test Account:
 
-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'
-   }
+For testing purposes, obtain a Test Account in the production environment. Any
+request against a Test Account inccurs no API units charge. See this guide for
+more details:
+
+  https://developers.google.com/adwords/api/docs/test-accounts
+
+To use the library against a Test Account, set client_customer_id property in
+the configuration file to its client customer ID.
 
 
 === 2.3 - Logging:

data/adwords_api.yml

@@ -2,8 +2,7 @@
 # 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:
-  # OAuth2, OAuth, ClientLogin.
+  # Authentication method, methods currently supported: OAuth2, ClientLogin.
   :method: ClientLogin
 
   # Auth parameters for OAuth2.0 method.
@@ -18,20 +17,6 @@
   #:oauth2_access_type: INSERT_OAUTH2_ACCESS_TYPE_HERE
   #:oauth2_approval_prompt: INSERT_OAUTH2_APPROVAL_PROMPT_HERE
 
-  # Auth parameters for OAuth1.0a method.
-  # NOTE: OAuth1.0a method is deprecated, use OAuth2.0 instead.
-  # 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.
   # NOTE: ClientLogin method is deprecated, use OAuth2.0 instead.
   :password: INSERT_YOUR_PASSWORD_HERE
@@ -44,7 +29,8 @@
   :client_customer_id: INSERT_YOUR_CLIENT_CUSTOMER_ID_HERE
   :user_agent: INSERT_YOUR_USER_AGENT_HERE
 :service:
-  :environment: SANDBOX
+  # Only production environment is available now, see: http://goo.gl/Plu3o
+  :environment: PRODUCTION
 :connection:
   # Enable to request all responses to be compressed.
   :enable_gzip: false

data/examples/v201206/account_management/create_account.rb

@@ -21,6 +21,9 @@
 # This example illustrates how to create an account. Note by default this
 # account will only be accessible via parent MCC.
 #
+# Note: This code example uses MCC-level calls and won't work with Test
+# Accounts, see: https://developers.google.com/adwords/api/docs/test-accounts
+#
 # Tags: ManagedCustomerService.mutate
 
 require 'adwords_api'

data/examples/v201206/account_management/get_account_alerts.rb

@@ -21,6 +21,9 @@
 # This example gets all alerts for all clients of an MCC account. The effective
 # user (clientCustomerId, or authToken) must be an MCC user to get results.
 #
+# Note: This code example uses MCC-level calls and won't work with Test
+# Accounts, see: https://developers.google.com/adwords/api/docs/test-accounts
+#
 # Tags: AlertService.get
 
 require 'adwords_api'

data/examples/v201206/account_management/get_account_hierarchy.rb

@@ -21,6 +21,9 @@
 # This example illustrates how to retrieve the account hierarchy under an
 # account.
 #
+# Note: This code example uses MCC-level calls and won't work with Test
+# Accounts, see: https://developers.google.com/adwords/api/docs/test-accounts
+#
 # Tags: ManagedCustomerService.get
 
 require 'adwords_api'

data/examples/v201206/account_management/get_client_customer_id.rb

@@ -22,6 +22,9 @@
 # We recommend to use this script as a one off to convert your identifiers to
 # IDs and store them for future use.
 #
+# Note: This code example uses MCC-level calls and won't work with Test
+# Accounts, see: https://developers.google.com/adwords/api/docs/test-accounts
+#
 # Tags: InfoService.get
 
 require 'adwords_api'

data/examples/v201206/account_management/get_client_unit_usage.rb

@@ -21,6 +21,9 @@
 # This example illustrates how to retrieve the number of API units usage for a
 # client account for the current month.
 #
+# Note: This code example uses MCC-level calls and won't work with Test
+# Accounts, see: https://developers.google.com/adwords/api/docs/test-accounts
+#
 # Tags: InfoService.get
 
 require 'adwords_api'

data/examples/v201206/reporting/parallel_report_download.rb

@@ -19,6 +19,9 @@
 #           limitations under the License.
 #
 # This example gets and downloads an Ad Hoc report from a XML report definition.
+#
+# Note: This code example uses MCC-level calls and won't work with Test
+# Accounts, see: https://developers.google.com/adwords/api/docs/test-accounts
 
 require 'thread'
 

data/examples/v201209/account_management/create_account.rb

@@ -21,6 +21,9 @@
 # This example illustrates how to create an account. Note by default this
 # account will only be accessible via parent MCC.
 #
+# Note: This code example uses MCC-level calls and won't work with Test
+# Accounts, see: https://developers.google.com/adwords/api/docs/test-accounts
+#
 # Tags: ManagedCustomerService.mutate
 
 require 'adwords_api'

data/examples/v201209/account_management/get_account_alerts.rb

@@ -21,6 +21,9 @@
 # This example gets all alerts for all clients of an MCC account. The effective
 # user (clientCustomerId, or authToken) must be an MCC user to get results.
 #
+# Note: This code example uses MCC-level calls and won't work with Test
+# Accounts, see: https://developers.google.com/adwords/api/docs/test-accounts
+#
 # Tags: AlertService.get
 
 require 'adwords_api'

data/examples/v201209/account_management/get_account_hierarchy.rb

@@ -21,6 +21,9 @@
 # This example illustrates how to retrieve the account hierarchy under an
 # account.
 #
+# Note: This code example uses MCC-level calls and won't work with Test
+# Accounts, see: https://developers.google.com/adwords/api/docs/test-accounts
+#
 # Tags: ManagedCustomerService.get
 
 require 'adwords_api'

data/examples/v201209/account_management/get_client_customer_id.rb

@@ -22,6 +22,9 @@
 # We recommend to use this script as a one off to convert your identifiers to
 # IDs and store them for future use.
 #
+# Note: This code example uses MCC-level calls and won't work with Test
+# Accounts, see: https://developers.google.com/adwords/api/docs/test-accounts
+#
 # Tags: InfoService.get
 
 require 'adwords_api'

data/examples/v201209/account_management/get_client_unit_usage.rb

@@ -21,6 +21,9 @@
 # This example illustrates how to retrieve the number of API units usage for a
 # client account for the current month.
 #
+# Note: This code example uses MCC-level calls and won't work with Test
+# Accounts, see: https://developers.google.com/adwords/api/docs/test-accounts
+#
 # Tags: InfoService.get
 
 require 'adwords_api'

data/examples/{v201109/misc/use_oauth2.rb → v201209/misc/use_oauth2_jwt.rb}

@@ -18,13 +18,14 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example illustrates how to use OAuth2.0 authentication method.
+# This example illustrates how to use OAuth2.0 authentication method with
+# Service Account (JWT).
 #
 # Tags: CampaignService.get
 
 require 'adwords_api'
 
-def use_oauth2()
+def use_oauth2_jwt()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -33,6 +34,19 @@ def use_oauth2()
   # the configuration file or provide your own logger:
   # adwords.logger = Logger.new('adwords_xml.log')
 
+  # Option 1: provide key filename as authentication -> oauth2_keyfile in the
+  #           configuration file. No additional code is necessary.
+  # To provide a file name at runtime, use authorize:
+  # adwords.authorize({:oauth2_keyfile => key_filename})
+
+  # Option 2: retrieve key manually and create OpenSSL::PKCS12 object.
+  # key_filename = 'INSERT_FILENAME_HERE'
+  # key_secret = 'INSERT_SECRET_HERE'
+  # key_file_data = File.read(key_filename)
+  # key = OpenSSL::PKCS12.new(key_file_data, key_secret).key
+  # adwords.authorize({:oauth2_key => key})
+
+  # Now you can make API calls.
   campaign_srv = adwords.service(:CampaignService, API_VERSION)
 
   # Get all the campaigns for this account; empty selector.
@@ -43,24 +57,7 @@ def use_oauth2()
     ]
   }
 
-  retry_count = 0
-
-  begin
-    response = campaign_srv.get(selector)
-  rescue AdsCommon::Errors::OAuth2VerificationRequired => e
-    if retry_count < MAX_RETRIES
-      puts "Hit Auth error, please navigate to URL:\n\t%s" % e.oauth_url
-      print 'log in and type the verification code: '
-      verification_code = gets.chomp
-      adwords.credential_handler.set_credential(
-          :oauth2_verification_code, verification_code)
-      retry_count += 1
-      retry
-    else
-      raise AdsCommon::Errors::AuthError, 'Failed to authenticate.'
-    end
-  end
-
+  response = campaign_srv.get(selector)
   if response and response[:entries]
     campaigns = response[:entries]
     campaigns.each do |campaign|
@@ -73,11 +70,10 @@ def use_oauth2()
 end
 
 if __FILE__ == $0
-  API_VERSION = :v201109
-  MAX_RETRIES = 3
+  API_VERSION = :v201209
 
   begin
-    use_oauth2()
+    use_oauth2_jwt()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201209/reporting/parallel_report_download.rb

@@ -20,6 +20,9 @@
 #
 # This example gets and downloads an Ad Hoc report from a XML report definition
 # for all accounts in hierarchy in multiple parallel threads.
+#
+# Note: This code example uses MCC-level calls and won't work with Test
+# Accounts, see: https://developers.google.com/adwords/api/docs/test-accounts
 
 require 'thread'
 

data/lib/adwords_api.rb

@@ -63,9 +63,14 @@ module AdwordsApi
     def soap_header_handler(auth_handler, version, header_ns, default_ns)
       auth_method = @config.read('authentication.method', :CLIENTLOGIN)
       handler_class = case auth_method
-        when :CLIENTLOGIN then AdwordsApi::ClientLoginHeaderHandler
-        when :OAUTH, :OAUTH2 then AdsCommon::SavonHeaders::OAuthHeaderHandler
-      end
+        when :CLIENTLOGIN
+            AdwordsApi::ClientLoginHeaderHandler
+        when :OAUTH2, :OAUTH2_JWT
+            AdsCommon::SavonHeaders::OAuthHeaderHandler
+        else
+            raise AdsCommon::Errors::AuthError,
+                "Unknown auth method: %s" % auth_method
+        end
       return handler_class.new(@credential_handler, auth_handler, header_ns,
                                   default_ns, version)
     end

data/lib/adwords_api/api_config.rb

@@ -45,68 +45,6 @@ module AdwordsApi
 
     # Configure the services available to each version
     @@service_config = {
-      :v201109 => [
-          :AdExtensionOverrideService,
-          :AdGroupAdService,
-          :AdGroupCriterionService,
-          :AdGroupService,
-          :AdParamService,
-          :AlertService,
-          :BudgetOrderService,
-          :BulkMutateJobService,
-          :CampaignAdExtensionService,
-          :CampaignCriterionService,
-          :CampaignService,
-          :CampaignTargetService,
-          :ConstantDataService,
-          :ConversionTrackerService,
-          :CreateAccountService,
-          :CustomerSyncService,
-          :DataService,
-          :ExperimentService,
-          :GeoLocationService,
-          :InfoService,
-          :LocationCriterionService,
-          :MediaService,
-          :MutateJobService,
-          :ReportDefinitionService,
-          :ServicedAccountService,
-          :TargetingIdeaService,
-          :TrafficEstimatorService,
-          :UserListService
-      ],
-      :v201109_1 => [
-          :AdExtensionOverrideService,
-          :AdGroupAdService,
-          :AdGroupCriterionService,
-          :AdGroupService,
-          :AdParamService,
-          :AlertService,
-          :BudgetOrderService,
-          :BulkMutateJobService,
-          :CampaignAdExtensionService,
-          :CampaignCriterionService,
-          :CampaignService,
-          :CampaignTargetService,
-          :ConstantDataService,
-          :ConversionTrackerService,
-          :CreateAccountService,
-          :CustomerService,
-          :CustomerSyncService,
-          :DataService,
-          :ExperimentService,
-          :GeoLocationService,
-          :InfoService,
-          :LocationCriterionService,
-          :ManagedCustomerService,
-          :MediaService,
-          :MutateJobService,
-          :ReportDefinitionService,
-          :ServicedAccountService,
-          :TargetingIdeaService,
-          :TrafficEstimatorService,
-          :UserListService
-      ],
       :v201206 => [
           :AdExtensionOverrideService,
           :AdGroupAdService,
@@ -172,84 +110,14 @@ module AdwordsApi
       :PRODUCTION => {
         :oauth_scope => 'https://adwords.google.com/api/adwords/',
         :header_ns => 'https://adwords.google.com/api/adwords/cm/',
-        :v201109 => 'https://adwords.google.com/api/adwords/',
-        :v201109_1 => 'https://adwords.google.com/api/adwords/',
         :v201206 => 'https://adwords.google.com/api/adwords/',
         :v201209 => 'https://adwords.google.com/api/adwords/'
-      },
-      :SANDBOX => {
-        :oauth_scope => 'https://adwords-sandbox.google.com/api/adwords/',
-        :header_ns => 'https://adwords.google.com/api/adwords/cm/',
-        :v201109 => 'https://adwords-sandbox.google.com/api/adwords/',
-        :v201109_1 => 'https://adwords-sandbox.google.com/api/adwords/',
-        :v201206 => 'https://adwords-sandbox.google.com/api/adwords/',
-        :v201209 => 'https://adwords-sandbox.google.com/api/adwords/'
       }
     }
 
     # Configure the subdirectories for each version / service pair.
     # A missing pair means that only the base URL is used.
     @@subdir_config = {
-      # v201109
-      [:v201109, :AdExtensionOverrideService] => 'cm/',
-      [:v201109, :AdGroupAdService] => 'cm/',
-      [:v201109, :AdGroupCriterionService] => 'cm/',
-      [:v201109, :AdGroupService] => 'cm/',
-      [:v201109, :AdParamService] => 'cm/',
-      [:v201109, :AlertService] => 'mcm/',
-      [:v201109, :BudgetOrderService] => 'billing/',
-      [:v201109, :BulkMutateJobService] => 'job/',
-      [:v201109, :CampaignAdExtensionService] => 'cm/',
-      [:v201109, :CampaignCriterionService] => 'cm/',
-      [:v201109, :CampaignService] => 'cm/',
-      [:v201109, :CampaignTargetService] => 'cm/',
-      [:v201109, :ConstantDataService] => 'cm/',
-      [:v201109, :ConversionTrackerService] => 'cm/',
-      [:v201109, :CreateAccountService] => 'mcm/',
-      [:v201109, :CustomerSyncService] => 'ch/',
-      [:v201109, :DataService] => 'cm/',
-      [:v201109, :ExperimentService] => 'cm/',
-      [:v201109, :GeoLocationService] => 'cm/',
-      [:v201109, :InfoService] => 'info/',
-      [:v201109, :LocationCriterionService] => 'cm/',
-      [:v201109, :MediaService] => 'cm/',
-      [:v201109, :MutateJobService] => 'cm/',
-      [:v201109, :ReportDefinitionService] => 'cm/',
-      [:v201109, :ServicedAccountService] => 'mcm/',
-      [:v201109, :TargetingIdeaService] => 'o/',
-      [:v201109, :TrafficEstimatorService] => 'o/',
-      [:v201109, :UserListService] => 'cm/',
-      # v201109_1
-      [:v201109_1, :AdExtensionOverrideService] => 'cm/',
-      [:v201109_1, :AdGroupAdService] => 'cm/',
-      [:v201109_1, :AdGroupCriterionService] => 'cm/',
-      [:v201109_1, :AdGroupService] => 'cm/',
-      [:v201109_1, :AdParamService] => 'cm/',
-      [:v201109_1, :AlertService] => 'mcm/',
-      [:v201109_1, :BudgetOrderService] => 'billing/',
-      [:v201109_1, :BulkMutateJobService] => 'job/',
-      [:v201109_1, :CampaignAdExtensionService] => 'cm/',
-      [:v201109_1, :CampaignCriterionService] => 'cm/',
-      [:v201109_1, :CampaignService] => 'cm/',
-      [:v201109_1, :CampaignTargetService] => 'cm/',
-      [:v201109_1, :ConstantDataService] => 'cm/',
-      [:v201109_1, :ConversionTrackerService] => 'cm/',
-      [:v201109_1, :CreateAccountService] => 'mcm/',
-      [:v201109_1, :CustomerSyncService] => 'ch/',
-      [:v201109_1, :DataService] => 'cm/',
-      [:v201109_1, :ExperimentService] => 'cm/',
-      [:v201109_1, :GeoLocationService] => 'cm/',
-      [:v201109_1, :InfoService] => 'info/',
-      [:v201109_1, :LocationCriterionService] => 'cm/',
-      [:v201109_1, :MediaService] => 'cm/',
-      [:v201109_1, :MutateJobService] => 'cm/',
-      [:v201109_1, :ReportDefinitionService] => 'cm/',
-      [:v201109_1, :ServicedAccountService] => 'mcm/',
-      [:v201109_1, :TargetingIdeaService] => 'o/',
-      [:v201109_1, :TrafficEstimatorService] => 'o/',
-      [:v201109_1, :UserListService] => 'cm/',
-      [:v201109_1, :ManagedCustomerService] => 'mcm/',
-      [:v201109_1, :CustomerService] => 'mcm/',
       # v201206
       [:v201206, :AdExtensionOverrideService] => 'cm/',
       [:v201206, :AdGroupAdService] => 'cm/',