google-adwords-api 0.17.0 → 0.18.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    YWE0OTA1NTlhMzhjOTI1YjJmODhlZThjMWU2YjNhNTc1MjgzNmNkZA==
-  data.tar.gz: !binary |-
-    NThjZDRkYmNiMjQyY2E5ZTIzM2VkMmE1MWE1OGI3ZTFjZGFkOGVjYQ==
+SHA1:
+  metadata.gz: 916926a4584ed9782e9efb72932b0c39b90473cc
+  data.tar.gz: 48a8aa5a00664fb2116662b84df12d07a9845e10
 SHA512:
-  metadata.gz: !binary |-
-    Y2IzYTNjMjE1ZDZmYjEzNWM5YzhlYTYzNjlhYzQ2MGUxOTM0ZGMxN2U4OWUz
-    ZTc4NTZlZDlhZjI5YWIzMzcxMWQ4OTJiZjliYzE5ZDhhYzU2NWQyNTA1ZDQ5
-    ZDcyMDFjZWUyOGViYzM1ZDlkOTEwNTE2ZjhkY2IxZDI5MmEzZTA=
-  data.tar.gz: !binary |-
-    ZjIxYTIwYmNiMDJmZmQxMDI0ZGUzNTM3ZTdhODIwZGI5OWQ5YmFmOTUwYzQ5
-    MmNlMDU2ODZmZTBjN2ViOTJiYjBmZjMxYTIzM2ZlZmMwZDY0NzA0MjFiZDg0
-    ODlmY2FmZTliN2Y4NjE5Yzc0ZjVkY2Y3ZGZmZmJhZTYzZTk3MWE=
+  metadata.gz: 5b87032f752d27c955deedeee692a1db207e4d8d96050be8d3c1cb2b70a1dfb12eaa0b0e77324a18fb8ee4f503003af3e48d33637cc41293b7bc7572eb811ca3
+  data.tar.gz: 1847b728836bbad92cac627a709f3e8a4b7e574009143507d6b48f99179b66f5593ce68c2d6e695730702faa2abb4ae7a3c9aed3b9ad0d30cbc6489f6d79fceb

data/ChangeLog

@@ -1,3 +1,8 @@
+0.18.0:
+  - Removed deprecated API version v201502.
+  - Support for streaming report requests in report_utils.
+  - Require google-ads-common 0.11.1 or later from now on.
+
 0.17.0:
   - Support and examples for v201509.
   - Require google-ads-common 0.11.0 or later from now on.

data/README.md

@@ -74,7 +74,7 @@ The basics of making a request are:
 
  3. Specify which service you're looking to use, and which version:
 
-        campaign_srv = adwords.service(:CampaignService, :v201502)
+        campaign_srv = adwords.service(:CampaignService, :v201509)
 
  4. You should now be able to just use the API methods in the returned object:
 
@@ -211,7 +211,7 @@ To target a specific version:
 
 For example:
 
-    $ rake generate[v201502]
+    $ rake generate[v201509]
 
 To target a specific service in a specific version:
 
@@ -219,7 +219,7 @@ To target a specific service in a specific version:
 
 For example:
 
-    $ rake generate[v201502,CampaignService]
+    $ rake generate[v201509,CampaignService]
 
 To build the gems:
 

data/adwords_api.yml

@@ -17,6 +17,9 @@
   #:oauth2_state: INSERT_OAUTH2_STATE_HERE
   #:oauth2_access_type: INSERT_OAUTH2_ACCESS_TYPE_HERE
   #:oauth2_approval_prompt: INSERT_OAUTH2_APPROVAL_PROMPT_HERE
+  # You can define extra scopes so that you can reuse your refresh token for
+  # other APIs.
+  #:oauth2_extra_scopes: [INSERT_EXTRA_SCOPES_HERE]
 
   # Auth parameters for OAUTH2_SERVICE_ACCOUNT method. See:
   #   https://developers.google.com/accounts/docs/OAuth2ServiceAccount

data/examples/v201509/{campaign_management → advanced_operations}/add_complete_campaigns_using_batch_job.rb

@@ -52,42 +52,36 @@ def add_complete_campaigns_using_batch_job()
   temp_id_generator = TempIdGenerator.new()
 
   # Create an array of hashed operations generated from the batch_job_utils.
-  hashed_operations = []
+  operations = []
 
   # Create an operation to create a new budget.
   budget_operation = build_budget_operation(temp_id_generator)
-  hashed_operations += batch_job_utils.generate_soap_operations(
-      [budget_operation])
+  operations << budget_operation
 
   # Create operations to create new campaigns.
   campaign_operations = build_campaign_operations(
       temp_id_generator, budget_operation)
-  hashed_operations += batch_job_utils.generate_soap_operations(
-      campaign_operations)
+  operations += campaign_operations
 
   # Create operations to create new negative keyword criteria for each
   # campaign.
-  hashed_operations += batch_job_utils.generate_soap_operations(
-      build_campaign_criterion_operations(campaign_operations))
+  operations += build_campaign_criterion_operations(campaign_operations)
 
   # Create operations to create new ad groups.
   ad_group_operations = build_ad_group_operations(
       temp_id_generator, campaign_operations)
-  hashed_operations += batch_job_utils.generate_soap_operations(
-      ad_group_operations)
+  operations += ad_group_operations
 
   # Create operations to create new ad group criteria (keywords).
-  hashed_operations += batch_job_utils.generate_soap_operations(
-      build_ad_group_criterion_operations(ad_group_operations))
+  operations += build_ad_group_criterion_operations(ad_group_operations)
 
   # Create operations to create new ad group ads (text ads).
-  hashed_operations += batch_job_utils.generate_soap_operations(
-      build_ad_group_ad_operations(ad_group_operations))
+  operations += build_ad_group_ad_operations(ad_group_operations)
 
   # Use the batch_job_utils to upload all operations.
-  batch_job_utils.post_soap_operations(hashed_operations, upload_url)
+  batch_job_utils.upload_operations(operations, upload_url)
   puts "Uploaded %d operations for batch job with ID %d." %
-      [hashed_operations.size, batch_job[:id]]
+      [operations.size, batch_job[:id]]
 
   # Poll for completion of the batch job using an exponential back off.
   poll_attempts = 0
@@ -104,7 +98,7 @@ def add_complete_campaigns_using_batch_job()
 
   begin
     sleep_seconds = 30 * (2 ** poll_attempts)
-    puts "Sleeping %d seconds" % sleep_seconds
+    puts "Sleeping for %d seconds" % sleep_seconds
     sleep(sleep_seconds)
 
     batch_job = batch_job_srv.get(selector)[:entries].first

data/examples/v201509/advanced_operations/add_keywords_using_incremental_batch_job.rb

@@ -0,0 +1,179 @@
+#!/usr/bin/env ruby
+# Encoding: utf-8
+#
+# Copyright:: Copyright 2015, 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 perform multiple requests using the
+# BatchJobService using incremental uploads.
+
+require 'adwords_api'
+
+def add_keywords_using_incremental_batch_job(ad_group_id)
+  # 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')
+
+  batch_job_srv = adwords.service(:BatchJobService, API_VERSION)
+  batch_job_utils = adwords.batch_job_utils(API_VERSION)
+
+  # Create a BatchJob.
+  add_op = {
+    :operator => 'ADD',
+    :operand => {}
+  }
+
+  response = batch_job_srv.mutate([add_op])
+  batch_job = response[:value].first
+
+  # Get the upload URL from the new job.
+  upload_url = batch_job[:upload_url][:url]
+  puts "Created BatchJob with ID %d, status '%s', and upload URL %s." %
+      [batch_job[:id], batch_job[:status], upload_url]
+
+  # Upload #1
+  incremental_helper = batch_job_utils.start_incremental_upload(upload_url)
+  operations = create_keyword_operations(ad_group_id)
+  incremental_helper.upload(operations)
+
+  # Upload #2
+  operations = create_keyword_operations(ad_group_id)
+  incremental_helper.upload(operations)
+
+  # Upload #3
+  operations = create_keyword_operations(ad_group_id)
+  incremental_helper.upload(operations, true)
+
+  # Poll for completion of the batch job using an exponential back off.
+  poll_attempts = 0
+  is_pending = true
+  selector = {
+    :fields =>
+        ['Id', 'Status', 'DownloadUrl', 'ProcessingErrors', 'ProgressStats'],
+    :predicates => [{
+      :field => 'Id',
+      :operator => 'IN',
+      :values => [batch_job[:id]]
+    }]
+  }
+
+  begin
+    sleep_seconds = 30 * (2 ** poll_attempts)
+    puts "Sleeping for %d seconds" % sleep_seconds
+    sleep(sleep_seconds)
+
+    batch_job = batch_job_srv.get(selector)[:entries].first
+
+    puts "Batch job ID %d has status '%s'." %
+        [batch_job[:id], batch_job[:status]]
+
+    poll_attempts += 1
+    is_pending = PENDING_STATUSES.include?(batch_job[:status])
+  end while is_pending and poll_attempts < MAX_POLL_ATTEMPTS
+
+  if is_pending
+    raise StandardError,
+        "Job is still in pending state after polling %d times." %
+        MAX_POLL_ATTEMPTS
+  end
+
+  unless batch_job[:processing_errors].nil?
+    batch_job[:processing_errors].each_with_index do |processing_error, i|
+      puts ("Processing error [%d]: errorType=%s, trigger=%s, errorString=%s" +
+          "fieldPath=%s, reason=%s") % [i, processing_error[:api_error_type],
+          processing_error[:trigger], processing_error[:error_string],
+          processing_error[:field_path], processing_error[:reason]]
+    end
+  end
+
+  unless batch_job[:download_url].nil? or batch_job[:download_url][:url].nil?
+    mutate_response = batch_job_utils.get_job_results(
+        batch_job[:download_url][:url])
+    puts "Downloaded results from '%s':" % batch_job[:download_url][:url]
+    mutate_response.each do |mutate_result|
+      outcome = "FAILURE"
+      outcome = "SUCCESS" if mutate_result[:error_list].nil?
+      puts "  Operation [%d] - %s" % [mutate_result[:index], outcome]
+    end
+  end
+end
+
+def create_keyword_operations(ad_group_id)
+  operations = []
+  KEYWORD_COUNT.times do |i|
+    text = "keyword %d" % i
+
+    # Make 10% of keywords invalid to demonstrate error handling.
+    text = text + "!!!" if i % 10 == 0
+    keyword = {
+      :xsi_type => 'Keyword',
+      :text => text,
+      :match_type => 'BROAD'
+    }
+    biddable_criterion = {
+      :xsi_type => 'BiddableAdGroupCriterion',
+      :ad_group_id => ad_group_id,
+      :criterion => keyword
+    }
+    operation = {
+      :xsi_type => 'AdGroupCriterionOperation',
+      :operator => 'ADD',
+      :operand => biddable_criterion
+    }
+    operations << operation
+  end
+
+  return operations
+end
+
+if __FILE__ == $0
+  API_VERSION = :v201509
+  KEYWORD_COUNT = 100
+  MAX_POLL_ATTEMPTS = 5
+  PENDING_STATUSES = ['ACTIVE', 'AWAITING_FILE']
+
+  begin
+    ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
+
+    add_keywords_using_incremental_batch_job(ad_group_id)
+
+  # Authorization error.
+  rescue AdsCommon::Errors::OAuth2VerificationRequired => e
+    puts "Authorization credentials are not valid. Edit adwords_api.yml for " +
+        "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " +
+        "to retrieve and store OAuth2 tokens."
+    puts "See this wiki page for more details:\n\n  " +
+        'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2'
+
+  # 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

data/examples/v201509/reporting/stream_criteria_report_results.rb

@@ -0,0 +1,97 @@
+#!/usr/bin/env ruby
+# Encoding: utf-8
+#
+# Copyright:: Copyright 2015, 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 streams the results of an Ad Hoc report to a file.
+
+require 'adwords_api'
+
+def stream_criteria_report_results()
+  # 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')
+
+  # Get report utilities for the version.
+  report_utils = adwords.report_utils(API_VERSION)
+
+  # Define report query.
+  report_query = 'SELECT Id, AdNetworkType1, Impressions ' +
+      'FROM CRITERIA_PERFORMANCE_REPORT ' +
+      'WHERE Status IN [ENABLED, PAUSED] ' +
+      'DURING LAST_7_DAYS'
+
+  # Optional: Set the configuration of the API instance to suppress header,
+  # column name, or summary rows in the report output. You can also configure
+  # this in your adwords_api.yml configuration file.
+  adwords.skip_report_header = true
+  adwords.skip_column_header = true
+  adwords.skip_report_summary = true
+  # Enable to allow rows with zero impressions to show.
+  adwords.include_zero_impressions = false
+
+  # Set the default value of the hash to 0 to allow easy totaling.
+  ad_network_map = Hash.new(0)
+
+  # We use get_stream_helper_with_awql.each_line here, which uses the
+  # ReportStream utility to handle breaking the streamed results into lines
+  # for easy processing. If you'd rather handle processing yourself, you can
+  # use download_report_as_stream_with_awql, which just passes data to the
+  # block as it's downloaded, without breaking it up into meaningful chunks.
+  report_utils.get_stream_helper_with_awql(
+        report_query, 'CSV').each_line do |line|
+    process_line(line, ad_network_map)
+  end
+
+  puts 'Total impressions by ad network type 1:'
+  ad_network_map.each do |ad_network_type, total_impressions|
+    puts '  %s: %s' % [ad_network_type, total_impressions]
+  end
+end
+
+def process_line(line, ad_network_map)
+  id, ad_network_type_1, impressions = line.split(',')
+  ad_network_map[ad_network_type_1] += impressions
+end
+
+if __FILE__ == $0
+  API_VERSION = :v201509
+
+  begin
+    # File name to write report to.
+    stream_criteria_report_results()
+
+  # Authorization error.
+  rescue AdsCommon::Errors::OAuth2VerificationRequired => e
+    puts "Authorization credentials are not valid. Edit adwords_api.yml for " +
+        "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " +
+        "to retrieve and store OAuth2 tokens."
+    puts "See this wiki page for more details:\n\n  " +
+        'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2'
+
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
+
+  # API errors.
+  rescue AdwordsApi::Errors::ReportError => e
+    puts "Reporting Error: %s" % e.message
+  end
+end

data/lib/adwords_api/api_config.rb

@@ -43,49 +43,6 @@ module AdwordsApi
 
     # Configure the services available to each version
     @@service_config = {
-      :v201502 => [
-          :AccountLabelService,
-          :AdCustomizerFeedService,
-          :AdGroupAdService,
-          :AdGroupBidModifierService,
-          :AdGroupCriterionService,
-          :AdGroupExtensionSettingService,
-          :AdGroupFeedService,
-          :AdGroupService,
-          :AdParamService,
-          :AdwordsUserListService,
-          :BiddingStrategyService,
-          :BudgetOrderService,
-          :BudgetService,
-          :CampaignCriterionService,
-          :CampaignExtensionSettingService,
-          :CampaignFeedService,
-          :CampaignService,
-          :CampaignSharedSetService,
-          :ConstantDataService,
-          :ConversionTrackerService,
-          :CustomerExtensionSettingService,
-          :CustomerFeedService,
-          :CustomerService,
-          :CustomerSyncService,
-          :DataService,
-          :ExperimentService,
-          :FeedItemService,
-          :FeedMappingService,
-          :FeedService,
-          :GeoLocationService,
-          :LabelService,
-          :LocationCriterionService,
-          :ManagedCustomerService,
-          :MediaService,
-          :MutateJobService,
-          :OfflineConversionFeedService,
-          :ReportDefinitionService,
-          :SharedCriterionService,
-          :SharedSetService,
-          :TargetingIdeaService,
-          :TrafficEstimatorService
-      ],
       :v201506 => [
           :AccountLabelService,
           :AdCustomizerFeedService,
@@ -179,7 +136,6 @@ module AdwordsApi
       :PRODUCTION => {
         :oauth_scope => 'https://www.googleapis.com/auth/adwords',
         :header_ns => 'https://adwords.google.com/api/adwords/cm/',
-        :v201502 => 'https://adwords.google.com/api/adwords/',
         :v201506 => 'https://adwords.google.com/api/adwords/',
         :v201509 => 'https://adwords.google.com/api/adwords/'
       }
@@ -188,48 +144,6 @@ module AdwordsApi
     # Configure the subdirectories for each version / service pair.
     # A missing pair means that only the base URL is used.
     @@subdir_config = {
-      # v201502
-      [:v201502, :AccountLabelService] => 'mcm/',
-      [:v201502, :AdCustomizerFeedService] => 'cm/',
-      [:v201502, :AdGroupAdService] => 'cm/',
-      [:v201502, :AdGroupBidModifierService] => 'cm/',
-      [:v201502, :AdGroupCriterionService] => 'cm/',
-      [:v201502, :AdGroupExtensionSettingService] => 'cm/',
-      [:v201502, :AdGroupFeedService] => 'cm/',
-      [:v201502, :AdGroupService] => 'cm/',
-      [:v201502, :AdParamService] => 'cm/',
-      [:v201502, :BudgetOrderService] => 'billing/',
-      [:v201502, :CampaignCriterionService] => 'cm/',
-      [:v201502, :CampaignExtensionSettingService] => 'cm/',
-      [:v201502, :CampaignFeedService] => 'cm/',
-      [:v201502, :CampaignService] => 'cm/',
-      [:v201502, :CampaignSharedSetService] => 'cm/',
-      [:v201502, :ConstantDataService] => 'cm/',
-      [:v201502, :ConversionTrackerService] => 'cm/',
-      [:v201502, :CustomerExtensionSettingService] => 'cm/',
-      [:v201502, :CustomerSyncService] => 'ch/',
-      [:v201502, :DataService] => 'cm/',
-      [:v201502, :ExperimentService] => 'cm/',
-      [:v201502, :FeedItemService] => 'cm/',
-      [:v201502, :FeedMappingService] => 'cm/',
-      [:v201502, :FeedService] => 'cm/',
-      [:v201502, :GeoLocationService] => 'cm/',
-      [:v201502, :LocationCriterionService] => 'cm/',
-      [:v201502, :MediaService] => 'cm/',
-      [:v201502, :MutateJobService] => 'cm/',
-      [:v201502, :OfflineConversionFeedService] => 'cm/',
-      [:v201502, :ReportDefinitionService] => 'cm/',
-      [:v201502, :SharedCriterionService] => 'cm/',
-      [:v201502, :SharedSetService] => 'cm/',
-      [:v201502, :TargetingIdeaService] => 'o/',
-      [:v201502, :TrafficEstimatorService] => 'o/',
-      [:v201502, :ManagedCustomerService] => 'mcm/',
-      [:v201502, :CustomerService] => 'mcm/',
-      [:v201502, :CustomerFeedService] => 'cm/',
-      [:v201502, :BudgetService] => 'cm/',
-      [:v201502, :BiddingStrategyService] => 'cm/',
-      [:v201502, :AdwordsUserListService] => 'rm/',
-      [:v201502, :LabelService] => 'cm/',
       # v201506
       [:v201506, :AccountLabelService] => 'mcm/',
       [:v201506, :AdCustomizerFeedService] => 'cm/',