google-adwords-api 0.4.0 → 0.4.1

data/examples/v201109/delete_campaign.rb

@@ -0,0 +1,78 @@
+#!/usr/bin/ruby
+#
+# Author:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# 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 deletes a campaign by setting the status to 'DELETED'. To get
+# campaigns, run get_all_campaigns.rb.
+#
+# Tags: CampaignService.mutate
+
+require 'rubygems'
+require 'adwords_api'
+
+API_VERSION = :v201109
+
+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
+
+  # Prepare for deleting campaign.
+  operation = {
+    :operator => 'SET',
+    :operand => {
+      :id => campaign_id,
+      :status => 'DELETED',
+    }
+  }
+
+  # Delete campaign.
+  response = campaign_srv.mutate([operation])
+  campaign = response[:value].first
+  puts 'Campaign with name "%s" and id %d was deleted.' %
+      [campaign[:name], campaign[:id]]
+end
+
+if __FILE__ == $0
+  begin
+    delete_campaign()
+
+  # 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/v201109/delete_experiment.rb

@@ -0,0 +1,78 @@
+#!/usr/bin/ruby
+#
+# Author:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# 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 deletes an experiment. To get experiments, run
+# get_all_experiments.rb. To add an experiment, run add_experiment.rb.
+#
+# Tags: ExperimentService.mutate
+
+require 'rubygems'
+require 'adwords_api'
+
+API_VERSION = :v201109
+
+def delete_experiment()
+  # 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')
+
+  experiment_srv = adwords.service(:ExperimentService, API_VERSION)
+
+  experiment_id = 'INSERT_EXPERIMENT_ID_HERE'.to_i
+
+  # Prepare for deleting experiment.
+  operation = {
+    :operator => 'SET',
+    :operand => {
+      :id => experiment_id,
+      :status => 'DELETED'
+    }
+  }
+
+  # Delete experiment.
+  response = experiment_srv.mutate([operation])
+  experiment = response[:value].first
+  puts 'Experiment with name "%s" and id %d was deleted.' %
+      [experiment[:name], experiment[:id]]
+end
+
+if __FILE__ == $0
+  begin
+    delete_experiment()
+
+  # 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/v201109/delete_user_list.rb

@@ -0,0 +1,78 @@
+#!/usr/bin/ruby
+#
+# Author:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# 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 deletes a user list by setting the status to 'CLOSED'. To get
+# user lists, run get_all_user_lists.rb.
+#
+# Tags: UserListService.mutate
+
+require 'rubygems'
+require 'adwords_api'
+
+API_VERSION = :v201109
+
+def delete_user_list()
+  # 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')
+
+  user_list_srv = adwords.service(:UserListService, API_VERSION)
+
+  user_list_id = 'INSERT_USER_LIST_ID_HERE'.to_i
+
+  # Prepare for deleting remarketing user list.
+  operation = {
+    :operator => 'SET',
+    :operand => {
+      :id => user_list_id,
+      :status => 'CLOSED'
+    }
+  }
+
+  # Delete user list.
+  response = user_list_srv.mutate([operation])
+  user_list = response[:value].first
+  puts 'User list with name "%s" and id %d was deleted (closed).' %
+      [user_list[:name], user_list[:id]]
+end
+
+if __FILE__ == $0
+  begin
+    delete_user_list()
+
+  # 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/v201109/download_adhoc_report.rb

@@ -0,0 +1,79 @@
+#!/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 'adwords_api'
+
+API_VERSION = :v201109
+
+def download_adhoc_report()
+  # 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)
+
+  # File name to write report to. To retrieve the report as return value, use
+  # "download_report" method.
+  file_name = 'INSERT_OUTPUT_FILE_NAME_HERE'
+
+  # 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
+  }
+
+  # Download report, using "download_report_as_file" utility method.
+  report_utils.download_report_as_file(report_definition, file_name)
+  puts "Report was downloaded to '%s'." % file_name
+end
+
+if __FILE__ == $0
+  begin
+    download_adhoc_report()
+
+  # 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/examples/v201109/download_report.rb

@@ -0,0 +1,67 @@
+#!/usr/bin/ruby
+#
+# Author:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# 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 a report from a report definition. To get a
+# report definition, run add_keywords_performance_report_definition.rb.
+
+require 'rubygems'
+require 'adwords_api'
+
+API_VERSION = :v201109
+
+def download_report()
+  # 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)
+
+  report_definition_id = 'INSERT_REPORT_DEFINITION_ID'.to_i
+  file_name = 'INSERT_OUTPUT_FILE_NAME_HERE'
+
+  # Download report, using "download_report_as_file" extension method.
+  report_def_srv.download_report_as_file(report_definition_id, file_name)
+  puts 'Report with definition id %d was downloaded to \'%s\'.' %
+      [report_definition_id, file_name]
+end
+
+if __FILE__ == $0
+  begin
+    download_report()
+
+  # 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/v201109/get_account_hierarchy.rb

@@ -0,0 +1,93 @@
+#!/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 illustrates how to retrieve the account hierarchy under an
+# account.
+#
+# Tags: ServicedAccountService.get
+
+require 'rubygems'
+require 'adwords_api'
+require 'adwords_api/utils'
+
+API_VERSION = :v201109
+
+def get_account_hierarchy()
+  # 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')
+
+  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)}
+
+  if graph and graph[:accounts]
+    accounts = graph[:accounts]
+    puts "Accounts under this hierarchy: %d" % accounts.size
+    accounts.each_with_index do |account, index|
+      puts "%d) Customer ID: %s" %
+          [index + 1, AdwordsApi::Utils.format_id(account[:customer_id])]
+      puts "\tLogin email: %s" % account[:login]
+      puts "\tCompany name: %s" % account[:company_name]
+      puts "\tIsMcc: %s" % account[:can_manage_clients].to_s
+    end
+
+    # Display the links.
+    if graph[:links]
+      puts 'Hierarchy links:'
+      graph[:links].each do |link|
+        puts "\tThere is a '%s' link from %s to %s" %
+            [link[:type_of_link],
+             AdwordsApi::Utils.format_id(link[:manager_id][:id]),
+             AdwordsApi::Utils.format_id(link[:client_id][:id])]
+      end
+    end
+  else
+    puts 'No accounts were found.'
+  end
+end
+
+if __FILE__ == $0
+  begin
+    get_account_hierarchy()
+
+  # 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