The code samples below provide examples of common account management functions using the AdWords API. Client Library.
Accept an invitation for linking to a manager account
#!/usr/bin/env ruby
# Encoding: utf-8
#
# Copyright:: Copyright 2016, 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 accepts a pending invitation to link your AdWords account to a
# Google Merchant Center account.
require 'adwords_api'
def accept_service_link(service_link_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')
# Get the CustomerService.
customer_srv = adwords.service(:CustomerService, API_VERSION)
# Create the operation to set the status to ACTIVE.
operation = {
:operator => 'SET',
:operand => {
:service_link_id => service_link_id,
:service_type => 'MERCHANT_CENTER',
:link_status => 'ACTIVE'
}
}
# Update the service link.
mutated_service_links = customer_srv.mutate_service_links([operation])
# Display the results.
mutated_service_links.each do |mutated_service_link|
puts ("Service link with service link ID %d, type '%s' updated to status:" +
"%s.") % [
mutated_service_link[:service_link_id],
mutated_service_link[:service_type],
mutated_service_link[:link_status]
]
end
end
if __FILE__ == $0
API_VERSION = :v201809
begin
service_link_id = 'INSERT_SERVICE_LINK_ID_HERE'.to_i
accept_service_link(service_link_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
Create a new account under an AdWords manager
#!/usr/bin/env ruby
# Encoding: utf-8
#
# 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 create an account. Note by default this
# account will only be accessible via parent AdWords manager account.
require 'adwords_api'
require 'adwords_api/utils'
def create_account()
# 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')
managed_customer_srv = adwords.service(:ManagedCustomerService, API_VERSION)
# Create a local Customer object.
customer = {
:name => 'Account created with ManagedCustomerService',
:currency_code => 'EUR',
:date_time_zone => 'Europe/London'
}
# Prepare operation to create an account.
operation = {
:operator => 'ADD',
:operand => customer
}
# Create the account. It is possible to create multiple accounts with one
# request by sending an array of operations.
response = managed_customer_srv.mutate([operation])
response[:value].each do |new_account|
puts "Account with customer ID '%s' was successfully created." %
AdwordsApi::Utils.format_id(new_account[:customer_id])
end
end
if __FILE__ == $0
API_VERSION = :v201809
begin
create_account()
# 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
Get all account changes during the past 24 hours
#!/usr/bin/env ruby
# Encoding: utf-8
#
# 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 all account changes that happened within the last 24 hours,
# for all your campaigns.
require 'adwords_api'
require 'date'
require 'pp'
def get_account_changes()
# 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)
customer_sync_srv = adwords.service(:CustomerSyncService, API_VERSION)
today_at_midnight = DateTime.parse(Date.today.to_s)
yesterday_at_midnight = DateTime.parse((Date.today - 1).to_s)
min_date_time = yesterday_at_midnight.strftime("%Y%m%d %H%M%S")
max_date_time = today_at_midnight.strftime("%Y%m%d %H%M%S")
# Get all the campaigns for this account.
selector = {
:fields => ['Id']
}
response = campaign_srv.get(selector)
campaign_ids = []
if response and response[:entries]
campaign_ids = response[:entries].map { |campaign| campaign[:id] }
else
raise StandardError, 'No campaigns were found.'
end
# Create a selector for CustomerSyncService.
selector = {
:campaign_ids => campaign_ids,
:date_time_range => {
:min => min_date_time,
:max => max_date_time
}
}
# Get all account changes for the campaigns.
campaign_changes = customer_sync_srv.get(selector)
# Display changes.
if campaign_changes
puts "Most recent change: %s" % campaign_changes[:last_change_timestamp]
campaign_changes[:changed_campaigns].each do |campaign|
puts "Campaign with ID %d was changed:" % campaign[:campaign_id]
puts "\tCampaign change status: '%s'" % campaign[:campaign_change_status]
unless ['NEW', 'FIELDS_UNCHANGED'].include?(
campaign[:campaign_change_status])
puts "\tAdded campaign criteria: '%s'" %
campaign[:added_campaign_criteria].pretty_inspect.chomp
puts "\tRemoved campaign criteria: '%s'" %
campaign[:removed_campaign_criteria].pretty_inspect.chomp
if campaign[:changed_ad_groups]
campaign[:changed_ad_groups].each do |ad_group|
puts "\tAd group with ID %d was changed:" % ad_group[:ad_group_id]
puts "\t\tAd group changed status: '%s'" %
ad_group[:ad_group_change_status]
unless ['NEW', 'FIELDS_UNCHANGED'].include?(
ad_group[:ad_group_change_status])
puts "\t\tAds changed: '%s'" %
ad_group[:changed_ads].pretty_inspect.chomp
puts "\t\tCriteria changed: '%s'" %
ad_group[:changed_criteria].pretty_inspect.chomp
puts "\t\tCriteria removed: '%s'" %
ad_group[:removed_criteria].pretty_inspect.chomp
end
end
end
end
puts
end
else
puts 'No account changes were found.'
end
end
if __FILE__ == $0
API_VERSION = :v201809
begin
get_account_changes()
# 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
Get the account hierarchy under the current account
#!/usr/bin/env ruby
# Encoding: utf-8
#
# 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. This example needs to be run against an AdWords manager account.
require 'adwords_api'
require 'adwords_api/utils'
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')
managed_customer_srv = adwords.service(:ManagedCustomerService, API_VERSION)
# Get the account hierarchy for this account.
selector = {
:fields => ['CustomerId', 'Name'],
:paging => {
:start_index => 0,
:number_results => PAGE_SIZE
}
}
# Set initial values
offset, page = 0, {}
accounts = {}
child_links = {}
parent_links = {}
root_account = nil
begin
page = managed_customer_srv.get(selector)
if page and page[:entries]
if page[:links]
page[:links].each do |link|
unless child_links.include?(link[:manager_customer_id])
child_links[link[:manager_customer_id]] = []
end
child_links[link[:manager_customer_id]] << link
unless parent_links.include?(link[:client_customer_id])
parent_links[link[:client_customer_id]] = []
end
parent_links[link[:client_customer_id]] << link
end
end
page[:entries].each do |account|
accounts[account[:customer_id]] = account
unless parent_links.include?(account[:customer_id])
root_account = account
end
end
# Increment values to request the next page.
offset += PAGE_SIZE
selector[:paging][:start_index] = offset
end
end while page[:total_num_entries] > offset
if root_account.nil?
puts "Unable to determine a root account."
else
puts "CustomerId, Name"
display_account_tree(root_account, accounts, child_links, 0)
end
end
def display_account_tree(account, accounts, links, depth)
prefix = '-' * depth * 2
puts '%s%s, %s' % [prefix, account[:customer_id], account[:name]]
if links.include?(account[:customer_id])
links[account[:customer_id]].each do |child_link|
child_account = accounts[child_link[:client_customer_id]]
display_account_tree(child_account, accounts, links, depth + 1)
end
end
end
if __FILE__ == $0
API_VERSION = :v201809
PAGE_SIZE = 500
begin
get_account_hierarchy()
# 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