google-adwords-api 0.4.2 → 0.4.3

data/ChangeLog

@@ -1,3 +1,6 @@
+0.4.3:
+  - Added example for client-side cross-client reporting.
+
 0.4.2:
   - Updated Reporting error codes handling.
   - Fix for old v13 services compatibility.

data/examples/v201109/parallel_report_download.rb

@@ -0,0 +1,159 @@
+#!/usr/bin/ruby
+#
+# Author:: api.dklimkin@gmail.com (Danial Klimkin)
+#
+# 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 gets and downloads an Ad Hoc report from a XML report definition.
+
+require 'rubygems'
+require 'thread'
+
+require 'adwords_api'
+require 'adwords_api/utils'
+
+API_VERSION = :v201109
+# Number of parallel threads to spawn.
+THREADS = 10
+# Maximum number of retries for 500 errors.
+MAX_RETRIES = 5
+# Timeout between retries in seconds.
+BACKOFF_FACTOR = 5
+
+def parallel_report_download()
+  # 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')
+
+  # Determine list of customer IDs to retrieve report for. For this example we
+  # will use ServicedAccountService to get all IDs in hierarchy.
+
+  serviced_account_srv = adwords.service(:ServicedAccountService, API_VERSION)
+
+  # Get the account hierarchy for this account.
+  selector = {:enable_paging => false}
+
+  # Run the request at the MCC level.
+  graph = adwords.use_mcc() {serviced_account_srv.get(selector)}
+
+  # Using queue to balance load between threads.
+  queue = Queue.new()
+
+  if graph and graph[:accounts] and !graph[:accounts].empty?
+    graph[:accounts].each {|account| queue << account[:customer_id]}
+  else
+    raise StandardError, 'Can not retrieve any customer ID'
+  end
+
+  # Get report utilities for the version.
+  report_utils = adwords.report_utils(API_VERSION)
+
+  # Define report definition. You can also pass your own XML text as a string.
+  report_definition = {
+    :selector => {
+        :fields => ['CampaignId', 'Id', 'Impressions', 'Clicks', 'Cost'],
+        # Predicates are optional.
+        :predicates => {
+          :field => 'Status',
+          :operator => 'IN',
+          :values => ['ENABLED', 'PAUSED']
+        }
+      },
+      :report_name => 'Custom ADGROUP_PERFORMANCE_REPORT',
+      :report_type => 'ADGROUP_PERFORMANCE_REPORT',
+      :download_format => 'CSV',
+      :date_range_type => 'LAST_7_DAYS',
+      # Enable to get rows with zero impressions.
+      :include_zero_impressions => false
+  }
+
+  puts "Retrieving %d reports with %d threads:" % [queue.size, THREADS]
+
+  reports_succeeded = Queue.new()
+  reports_failed = Queue.new()
+
+  # Creating a mutex to control access to the queue.
+  queue_mutex = Mutex.new
+
+  # Start all the threads.
+  threads = (1..THREADS).map do |thread_id|
+    Thread.new(report_definition) do |local_def|
+      cid = nil
+      begin
+        cid = queue_mutex.synchronize {(queue.empty?) ? nil : queue.pop(true)}
+        if cid
+          retry_count = 0
+          file_name = "adgroup_%010d.csv" % cid
+          puts "[%2d/%d] Loading report for customer ID %s into '%s'..." %
+              [thread_id, retry_count,
+               AdwordsApi::Utils.format_id(cid), file_name]
+          begin
+            report_utils.download_report_as_file(local_def, file_name, cid)
+            reports_succeeded << {:cid => cid, :file_name => file_name}
+          rescue AdwordsApi::Errors::ReportError => e
+            if e.http_code == 500 && retry_count < MAX_RETRIES
+              retry_count += 1
+              sleep(retry_count * BACKOFF_FACTOR)
+              retry
+            else
+              puts(("Report failed for customer ID %s with code %d after %d " +
+                  "retries.") % [cid, e.http_code, retry_count + 1])
+              reports_failed <<
+                {:cid => cid, :http_code => e.http_code, :message => e.message}
+            end
+          end
+        end
+      end while (cid != nil)
+    end
+  end
+
+  # Wait for all threads to finish.
+  threads.each { |aThread|  aThread.join }
+
+  puts 'Download completed, results:'
+  puts 'Successful reports:'
+  while !reports_succeeded.empty? do
+    result = reports_succeeded.pop()
+    puts "\tClient ID %s => '%s'" %
+        [AdwordsApi::Utils.format_id(result[:cid]), result[:file_name]]
+  end
+  puts 'Failed reports:'
+  while !reports_failed.empty? do
+    result = reports_failed.pop()
+    puts "\tClient ID %s => Code: %d, Message: '%s'" %
+        [AdwordsApi::Utils.format_id(result[:cid]),
+         result[:http_code], result[:message]]
+  end
+  puts 'End of results.'
+end
+
+if __FILE__ == $0
+  begin
+    parallel_report_download()
+
+  # 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

@@ -41,7 +41,7 @@ module AdwordsApi
 
     # Set other constants
     API_NAME = 'AdwordsApi'
-    CLIENT_LIB_VERSION = '0.4.2'
+    CLIENT_LIB_VERSION = '0.4.3'
     DEFAULT_CONFIG_FILENAME = 'adwords_api.yml'
 
     # Configure the services available to each version

data/lib/adwords_api/report_utils.rb

@@ -40,6 +40,7 @@ module AdwordsApi
     #
     # Args:
     # - report_definition: definition of the report in XML text or hash
+    # - cid: optional customer ID to run against
     #
     # Returns:
     # - report body
@@ -49,8 +50,8 @@ module AdwordsApi
     #   definition is invalid
     # - AdwordsApi::Errors::ReportError if server-side error occurred
     #
-    def download_report(report_definition)
-      return get_report_response(report_definition).body
+    def download_report(report_definition, cid = nil)
+      return get_report_response(report_definition, cid).body
     end
 
     # Downloads a report and saves it to a file.
@@ -58,6 +59,7 @@ module AdwordsApi
     # Args:
     # - report_definition: definition of the report in XML text or hash
     # - path: path to save report to
+    # - cid: optional customer ID to run against
     #
     # Returns:
     # - nil
@@ -67,8 +69,8 @@ module AdwordsApi
     #   definition is invalid
     # - AdwordsApi::Errors::ReportError if server-side error occurred
     #
-    def download_report_as_file(report_definition, path)
-      report_body = download_report(report_definition)
+    def download_report_as_file(report_definition, path, cid = nil)
+      report_body = download_report(report_definition, cid)
       save_to_file(report_body, path)
       return nil
     end
@@ -83,17 +85,19 @@ module AdwordsApi
     REPORT_DEFINITION_ORDER = {
       :root => [:selector, :report_name, :report_type, :date_range_type,
           :download_format, :include_zero_impressions],
-      :selector => [:fields, :predicates, :date_range],
-      :predicates => [:field, :operator, :values]
+      :selector => [:fields, :predicates, :date_range, :ordering, :paging],
+      :predicates => [:field, :operator, :values],
+      :ordering => [:field, :sort_order],
+      :paging => [:start_index, :number_results]
     }
 
     # Send POST request for a report and returns Response object.
-    def get_report_response(report_definition)
+    def get_report_response(report_definition, cid = nil)
       definition_text = get_report_definition_text(report_definition)
       data = {'__rdxml' => definition_text}
       url = @api.api_config.adhoc_report_download_url(
           @api.config.read('service.environment'), @version)
-      headers = get_report_request_headers(url)
+      headers = get_report_request_headers(url, cid)
       response = AdsCommon::Http.post_response(url, data, @api.config, headers)
       check_for_errors(response)
       return response
@@ -113,15 +117,16 @@ module AdwordsApi
     end
 
     # Prepares headers for report request.
-    def get_report_request_headers(url)
+    def get_report_request_headers(url, cid = nil)
       credentials = @api.credential_handler.credentials
       auth_handler = @api.get_auth_handler(
           @api.config.read('service.environment'), @version)
       auth_string = auth_handler.auth_string(
           credentials, HTTPI::Request.new(url))
+      customer_id = validate_cid(cid || credentials[:clientCustomerId])
       headers = {
           'Authorization' => auth_string,
-          'ClientCustomerId' => credentials[:clientCustomerId],
+          'ClientCustomerId' => customer_id,
           'Content-Type' => 'multipart/form-data',
           'developerToken' => credentials[:developerToken]
       }
@@ -133,6 +138,20 @@ module AdwordsApi
       open(path, 'wb') { |file| file.puts(data) } if path
     end
 
+    # Validates the customer ID specified is correct.
+    def validate_cid(cid)
+      if (cid.kind_of?(Integer) || (
+          cid.kind_of?(String) && (
+              ((/\d{3}-\d{3}-\d{4}/ =~ cid) == 0) ||
+              ((/\d{10}/ =~ cid) == 0)
+          )))
+        return cid
+      else
+        raise AdwordsApi::Errors::BadCredentialsError,
+            "Invalid client customer ID: %s" % cid
+      end
+    end
+
     # Checks downloaded data for error signature. Raises ReportError if it
     # detects an error.
     def check_for_errors(response)
@@ -195,8 +214,15 @@ module AdwordsApi
       def_order = REPORT_DEFINITION_ORDER[name]
       var_order = def_order.reject {|field| !node.include?(field)}
       node.keys.each do |key|
-        if node[key].is_a?(Hash) and REPORT_DEFINITION_ORDER.include?(key)
-          add_report_definition_hash_order(node[key], key)
+        if REPORT_DEFINITION_ORDER.include?(key)
+          case node[key]
+            when Hash
+              add_report_definition_hash_order(node[key], key)
+            when Array
+              node[key].each do |item|
+                add_report_definition_hash_order(item, key)
+              end
+          end
         end
       end
       node[:order!] = var_order

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 4
-  - 2
-  version: 0.4.2
+  - 3
+  version: 0.4.3
 platform: ruby
 authors: 
 - Danial Klimkin
@@ -535,6 +535,7 @@ files:
 - examples/v201109/get_all_paused_campaigns.rb
 - examples/v201109/handle_partial_failures.rb
 - examples/v201109/get_related_keywords.rb
+- examples/v201109/parallel_report_download.rb
 - examples/v201109/oauth_handling.rb
 - examples/v201109/add_ads.rb
 - examples/v201109/get_campaign_alerts.rb