Skip to content

Commit

Permalink
Adding v201406 support to AdWords library.
Browse files Browse the repository at this point in the history
  • Loading branch information
mcloonan committed Jul 9, 2014
1 parent 97b7206 commit 2da6d98
Show file tree
Hide file tree
Showing 157 changed files with 12,135 additions and 35 deletions.
5 changes: 5 additions & 0 deletions adwords_api/ChangeLog
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
0.12.1:
- Support and examples for v201406.
- Changed default OAuth scope. See:
https://developers.google.com/adwords/api/docs/guides/authentication#scope

0.12.0:
- Removed deprecated API version v201306.

Expand Down
59 changes: 33 additions & 26 deletions adwords_api/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,9 @@ Install them using the gem install command:
$ gem install --remote google-adwords-api
$ gem install --remote google-adx-buyer-api

Please note the google-adx-buyer-api gem contains only DoubleClick Ad Exchange
Buyer client library examples. You need the AdWords library in order to use it
which is installed automatically as a dependency.
Please note the `google-adx-buyer-api` gem contains only DoubleClick Ad
Exchange Buyer client library examples. The gem also depends on the
AdWords library, which will be installed automatically.

The following gem libraries are required:

Expand All @@ -32,21 +32,15 @@ The following gem libraries are required:

## 2 - Using the client library

Include the library with 'require':

require 'adwords_api'

Then create an API instance:

adwords = AdwordsApi::Api.new

The created API object will grant you access to all the services for all of the
currently supported vesions of the APIs. It uses a config file in
`ENV['HOME']/adwords_api.yml` to read all of your configurations by default.
Before starting to use the client library, you need to set up OAuth2. You can
find our guide on how to obtain OAuth2 credentials
[on the wiki](https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2).

There is an example configuration file shipped with these libraries.
By default, the API uses a config file in `ENV['HOME']/adwords_api.yml`. When
generating your OAuth2 refresh token, you will be given the option for the
sample to automatically store the refresh token in this file.

You can also pass API a manually constructed config hash like:
You can also pass the API a manually constructed config hash like:

adwords = AdwordsApi::Api.new({
:authentication => {
Expand All @@ -62,21 +56,33 @@ You can also pass API a manually constructed config hash like:
}
})

To obtain OAuth2 client credentials, follow the instructions
[on the wiki](https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2).
Once you have all the requisite setup complete, you're ready to make an API
call. The easiest way to do this is to look at one of our
[examples](https://github.com/googleads/google-api-ads-ruby/tree/master/adwords_api/examples).
The `adwords_on_rails` example will show how to use the web flow, and the other
examples will use the installed application OAuth2 flow.

Once the library instance is created, specify which service you're looking to
use, and which version:
The basics of making a request are:

campaign_srv = adwords.service(:CampaignService, :v201309)
1. Include the library with `require`:

You should now be able to just use the API methods in the object you were
returned:
require 'adwords_api'

# Get 'Id', 'Name' and 'Status' fields of all campaigns.
campaigns = campaign_srv.get({:fields => ['Id', 'Name', 'Status']})
2. Create an API instance:

See the code in the examples directory for working examples you can build from.
adwords = AdwordsApi::Api.new

3. Specify which service you're looking to use, and which version:

campaign_srv = adwords.service(:CampaignService, :v201402)

4. You should now be able to just use the API methods in the returned object:

# Get 'Id', 'Name' and 'Status' fields of all campaigns.
campaigns = campaign_srv.get({:fields => ['Id', 'Name', 'Status']})

See the code in the examples directory for more thorough working examples you
can build from.

*Note*: If your setup requires you to send connections through a proxy server,
please set the appropriate options in the config file or config hash.
Expand Down Expand Up @@ -266,3 +272,4 @@ Authors:
Maintainer:

- [email protected] (Michael Cloonan)

92 changes: 92 additions & 0 deletions adwords_api/examples/v201406/account_management/create_account.rb
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
#!/usr/bin/env ruby
# Encoding: utf-8
#
# Author:: [email protected] (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 create an account. Note by default this
# account will only be accessible via parent MCC.
#
# Tags: ManagedCustomerService.mutate

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 = :v201406

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 " +
'http://code.google.com/p/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
122 changes: 122 additions & 0 deletions adwords_api/examples/v201406/account_management/get_account_alerts.rb
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
#!/usr/bin/env ruby
# Encoding: utf-8
#
# Author:: [email protected] (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 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'
require 'adwords_api/utils'

def get_account_alerts()
# 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')

alert_srv = adwords.service(:AlertService, API_VERSION)

# Create the selector.
selector = {
:query => {
:filter_spec => 'ALL',
:client_spec => 'ALL',
:trigger_time_spec => 'ALL_TIME',
:severities => ['GREEN', 'YELLOW', 'RED'],
:types => [
'ACCOUNT_BUDGET_BURN_RATE', 'ACCOUNT_BUDGET_ENDING',
'ACCOUNT_ON_TARGET', 'CAMPAIGN_ENDED', 'CAMPAIGN_ENDING',
'CREDIT_CARD_EXPIRING', 'DECLINED_PAYMENT', 'MANAGER_LINK_PENDING',
'MISSING_BANK_REFERENCE_NUMBER', 'PAYMENT_NOT_ENTERED',
'TV_ACCOUNT_BUDGET_ENDING', 'TV_ACCOUNT_ON_TARGET',
'TV_ZERO_DAILY_SPENDING_LIMIT', 'USER_INVITE_ACCEPTED',
'USER_INVITE_PENDING', 'ZERO_DAILY_SPENDING_LIMIT'
]
},
:paging => {
:start_index => 0,
:number_results => PAGE_SIZE
}
}

# Set initial values.
offset, page = 0, {}

# Get alerts.
begin
page = alert_srv.get(selector)
if page[:entries]
page[:entries].each_with_index do |alert, index|
puts "%d) Customer ID is '%s', alert type is '%s', severity is '%s'."
[AdwordsApi::Utils.format_id(alert[:client_customer_id]),
alert[:alert_type], alert[:alert_severity]]
alert[:details].each do |detail|
puts "\t- triggered at %s" % detail[:trigger_time]
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 page.include?(:total_num_entries)
puts "\tTotal number of alerts: %d." % page[:total_num_entries]
end
end

if __FILE__ == $0
API_VERSION = :v201406
PAGE_SIZE = 500

begin
get_account_alerts()

# 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 " +
'http://code.google.com/p/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
Loading

0 comments on commit 2da6d98

Please sign in to comment.