google-adwords-api 0.11.0 → 0.11.1

data/ChangeLog

@@ -1,3 +1,7 @@
+0.11.1:
+  - Support and examples for v201402.
+  - Removed support for ClientLogin for versions > v201309.
+
 0.11.0:
   - Removed deprecated API version v201302.
 

data/README

@@ -1,4 +1,4 @@
-= Google AdWords and DoubleClick Ad Exchange Buyer Client Library
+# Google AdWords and DoubleClick Ad Exchange Buyer Client Library
 
 Welcome to the next generation Google-developed Ruby client library for the
 AdWords and DoubleClick Ad Exchange Buyer API!
@@ -8,216 +8,230 @@ programming interface that lets you handle everything in native Ruby
 collections.
 
 
-= Docs for Users
+# Docs for Users
 
-== 1 - Installation:
+## 1 - Installation
 
-google-adwords-api and google-adx-buyer-api are ruby gems.
-  See http://docs.rubygems.org/read/book/1
+`google-adwords-api` and `google-adx-buyer-api` are ruby gems. See
+[http://docs.rubygems.org/read/book/1]().
 
 Install them using the gem install command:
-   $ gem install --remote google-adwords-api
-   $ gem install --remote google-adx-buyer-api
+
+    $ 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.
 
 The following gem libraries are required:
-  - savon;
-  - google-ads-common.
+
+ - savon
+ - google-ads-common
 
 
-== 2 - Using the client library:
+## 2 - Using the client library
 
 Include the library with 'require':
-   require 'adwords_api'
+
+    require 'adwords_api'
 
 Then create an API instance:
-   adwords = AdwordsApi::Api.new
+
+    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.
+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.
 
 There is an example configuration file shipped with these libraries.
 
 You can also pass API a manually constructed config hash like:
-   adwords = AdwordsApi::Api.new({
-     :authentication => {
-         :method => 'OAuth2',
-         :oauth2_client_id: 'INSERT_OAUTH2_CLIENT_ID_HERE'
-         :oauth2_client_secret: 'INSERT_OAUTH2_CLIENT_SECRET_HERE'
-         :developer_token => 'DEVELOPER_TOKEN',
-         :client_customer_id => '012-345-6789',
-         :user_agent => 'Ruby Sample'
-     },
-     :service => {
-       :environment => 'PRODUCTION'
-     }
-   })
-
-To obtain OAuth2 client credentials, follow instructions on the wiki:
-
-  http://code.google.com/p/google-api-ads-ruby/wiki/OAuth2
-
-Once the library instance is create, specify which service you're looking to
+
+    adwords = AdwordsApi::Api.new({
+      :authentication => {
+          :method => 'OAuth2',
+          :oauth2_client_id => 'INSERT_OAUTH2_CLIENT_ID_HERE',
+          :oauth2_client_secret => 'INSERT_OAUTH2_CLIENT_SECRET_HERE',
+          :developer_token => 'DEVELOPER_TOKEN',
+          :client_customer_id => '012-345-6789',
+          :user_agent => 'Ruby Sample'
+      },
+      :service => {
+        :environment => 'PRODUCTION'
+      }
+    })
+
+To obtain OAuth2 client credentials, follow the instructions
+[on the wiki](https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2).
+
+Once the library instance is created, specify which service you're looking to
 use, and which version:
-   campaign_srv = adwords.service(:CampaignService, :v201309)
 
-and you should now be able to just use the API methods in the object you were
+    campaign_srv = adwords.service(:CampaignService, :v201309)
+
+You should now be able to just use the API methods in the object you were
 returned:
-   # Get 'Id', 'Name' and 'Status' fields of all campaigns.
-   campaigns = campaign_srv.get({:fields => ['Id', 'Name', 'Status']})
+
+    # 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 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. E.g.:
-   config[:connection] = {
-     :proxy => 'http://user:password@proxy_hostname:8080'
-   }
+*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.
+For example:
 
-*Note*: if you are using Ruby 1.8 you may need to include RubyGems to be able
+    config[:connection] = {
+      :proxy => 'http://user:password@proxy_hostname:8080'
+    }
+
+*Note*: If you are using Ruby 1.8 you may need to include RubyGems to be able
 to require other gems code. There are several ways to do it, the easiest one is
 to pass '-rubygems' parameter to the ruby interpreter:
-   $ ruby -rubygems my_program_that_uses_gems
+
+    $ ruby -rubygems my_program_that_uses_gems
 
 you can also set this up in the environment:
-   $ export RUBYOPT="rubygems"
+
+    $ export RUBYOPT="rubygems"
 
 or add it to the bash configuration file:
-   $ echo 'export RUBYOPT="rubygems"' >> ~/.bashrc
+
+    $ echo 'export RUBYOPT="rubygems"' >> ~/.bashrc
 
 
-=== 2.1 - Ruby names for a Ruby library:
+### 2.1 - Ruby names for a Ruby library
 
 In order to make things more Ruby-like for our Ruby developers, we've renamed
 API objects and methods to more closely match Ruby conventions. This means using
 snake_case for methods and parameters, and UpperCamelCase for class names.
 
-For example, the 'startDate' field of the Campaign object is named 'start_date'
-in the client library. The 'get' method, returns a CampaignPage object which has
-an 'entries' and a 'total_num_entries' field. So, to access the return
+For example, the `startDate` field of the Campaign object is named `start_date`
+in the client library. The `get` method, returns a CampaignPage object which has
+`entries` and `total_num_entries` fields. So, to access the return
 values, you would do this:
 
-   response = campaign_srv.get(selector)
-   num_entries = response[:total_num_entries]
+    response = campaign_srv.get(selector)
+    num_entries = response[:total_num_entries]
 
 Essentially, all you have to do is follow Ruby conventions, and the library will
 do the rest. All of the examples are written following this standard.
 
 
-=== 2.2 - Using the Test Account:
+### 2.2 - Using the Test Account
 
 For testing purposes, obtain a Test Account in the production environment. Any
-request against a Test Account inccurs no API units charge. See this guide for
-more details:
+request against a Test Account inccurs no API units charge. See
+[this guide](https://developers.google.com/adwords/api/docs/test-accounts) for
+more details.
 
-  https://developers.google.com/adwords/api/docs/test-accounts
-
-To use the library against a Test Account, set client_customer_id property in
+To use the library against a Test Account, set the `client_customer_id` property in
 the configuration file to its client customer ID.
 
 
-=== 2.3 - Logging:
+### 2.3 - Logging
 
 It is often useful to see a trace of the raw SOAP XML being sent and received.
 The quickest way of achieving this when debugging your application is by setting
-the library.log_level configuration variable to 'DEBUG':
-   config[:library] = {
-     :log_level => 'DEBUG'
-   }
-or via configuration file (see example).
+the `library.log_level` configuration variable to DEBUG.
+
+    config[:library] = {
+      :log_level => 'DEBUG'
+    }
+
+This can alternatively be done via a configuration file.
 
-This will output the SOAP XML to stderr, which will usually show up in your
+This will output the SOAP XML to `stderr`, which will usually show up in your
 terminal window.
 
 There's also an option of logging requests and XML to a file. In order to enable
 this, you should create a standard Logger object and pass it to the library:
-   require 'logger'
-   logger = Logger.new('path/to/log_filename')
-   logger.level = Logger::DEBUG
-   adwords = AdwordsApi::Api.new
-   adwords.logger = logger
+
+    require 'logger'
+    logger = Logger.new('path/to/log_filename')
+    logger.level = Logger::DEBUG
+    adwords = AdwordsApi::Api.new
+    adwords.logger = logger
 
 Request details and units spend are logged at the INFO log level, while raw HTTP
 headers and XML dumps are logged at the DEBUG log level. For more details on
 using Logger refer to the Ruby Logger documentation.
 
-=== 2.4 - Calculating operations usage
 
-Each AdWords API operation performed consumes a certain number of operations as
-described in the rate sheet:
+### 2.4 - Calculating operations usage
 
-  https://developers.google.com/adwords/api/docs/ratesheet
+Each AdWords API operation performed consumes a certain number of operations as
+described in the
+[rate sheet](https://developers.google.com/adwords/api/docs/ratesheet).
 
 The amount of operations consumed is returned in the header part of the SOAP
 response. This information can be obtained by passing a user block during the
 method call:
 
-  response = campaign_srv.get(selector) do |header|
-    puts "Operations consumed: %d" % header[:operations]
-  end
+    response = campaign_srv.get(selector) do |header|
+      puts "Operations consumed: %d" % header[:operations]
+    end
 
 You can also retrieve the response body as the second block parameter:
-  campaign_srv.get(selector) {|header, body| ... }
 
-=== 2.5 - GZip compression
+    campaign_srv.get(selector) {|header, body| ... }
+
+
+### 2.5 - GZip compression
 
 The library offers a transparent compression option which can be enabled in the
 configuration file or by the following setting:
 
-   config[:connection] = {
-     :enable_gzip => true
-   }
+    config[:connection] = {
+      :enable_gzip => true
+    }
 
 Enabling this option will set the headers required to request the server to
 respond in gzipped format. All requests are sent uncompressed regardless.
 
 
-= Docs for Developers
+# Docs for Developers
 
-== Rake targets
+## Rake targets
 
- $ rake generate
-to regenerate the stubs if needed
+    $ rake generate
 
- $ gem build google-adwords-api.gemspec
- $ gem build google-adx-buyer-api.gemspec
-to build the gems
+to regenerate the stubs if needed
 
- $ rake test
-to run unit tests on the library
+    $ gem build google-adwords-api.gemspec
+    $ gem build google-adx-buyer-api.gemspec
 
+to build the gems
 
-== Where do I submit bug reports and feature requests?
+    $ rake test
 
-Bug reports and feature requests can be posted on the library page:
+to run unit tests on the library
 
-  http://code.google.com/p/google-api-ads-ruby/issues
 
-Questions can be asked on forum
+## Where do I submit bug reports and feature requests?
 
-  http://groups.google.com/group/adwords-api
+Bug reports and feature requests can be posted
+[on the library page](https://github.com/googleads/google-api-ads-ruby/issues).
 
-Make sure to subscribe to our Google Plus page for API change announcements and
-other news:
+Questions can be asked [on the forum](http://groups.google.com/group/adwords-api).
 
-  https://plus.google.com/+GoogleAdsDevelopers
+Make sure to subscribe to our
+[Google Plus page](https://plus.google.com/+GoogleAdsDevelopers) for API change 
+announcements and other news.
 
 
-= Copyright/License Info
+# Copyright/License Info
 
-== Licence
+## Licence
 
 Copyright 2010-2013, Google Inc. All Rights Reserved.
 
 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
+You may obtain a copy of the License at:
 
-    http://www.apache.org/licenses/LICENSE-2.0
+> [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,
@@ -225,11 +239,14 @@ 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.
 
-== Authors
+## Authors
 
 Authors:
-    api.sgomes (Sérgio Gomes)
-    api.dklimkin@gmail.com (Danial Klimkin)
+
+ - api.sgomes (Sérgio Gomes)
+ - api.dklimkin@gmail.com (Danial Klimkin)
+ - api.mcloonan@gmail.com (Michael Cloonan)
 
 Maintainer:
-    api.dklimkin@gmail.com (Danial Klimkin)
+
+ - api.mcloonan@gmail.com (Michael Cloonan)

data/examples/v201306/misc/use_oauth2_jwt.rb

@@ -19,7 +19,11 @@
 #           limitations under the License.
 #
 # This example illustrates how to use OAuth2.0 authentication method with
-# Service Account (JWT).
+# Service Account (JWT). For this example to work, your Service Account must be
+# a Google Apps for Business Account.
+#
+# See https://developers.google.com/adwords/api/docs/guides/service-accounts
+# for more information.
 #
 # Tags: CampaignService.get
 

data/examples/v201309/misc/use_oauth2_jwt.rb

@@ -19,7 +19,11 @@
 #           limitations under the License.
 #
 # This example illustrates how to use OAuth2.0 authentication method with
-# Service Account (JWT).
+# Service Account (JWT). For this example to work, your Service Account must be
+# a Google Apps for Business Account.
+#
+# See https://developers.google.com/adwords/api/docs/guides/service-accounts
+# for more information.
 #
 # Tags: CampaignService.get
 

data/examples/v201402/account_management/create_account.rb

@@ -0,0 +1,95 @@
+#!/usr/bin/env ruby
+# Encoding: utf-8
+#
+# 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 create an account. Note by default this
+# account will only be accessible via parent MCC.
+#
+# 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: 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 = :v201402
+
+  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