google-dfp-api 0.7.1 → 0.8.0

data/ChangeLog

@@ -1,3 +1,8 @@
+0.8.0:
+  - Added support and examples for v201403.
+  - Removed support for all non-bulk method calls.
+  - Removed support for ClientLogin for versions > v201311.
+
 0.7.1:
   - Added support and examples for v201311.
   - Require google-ads-common 0.9.4 or later from now on.

data/README

@@ -1,4 +1,4 @@
-= Google's DoubleClick For Publishers API Ruby Client Library
+# Google's DoubleClick For Publishers API Ruby Client Library
 
 Google's DoubleClick For Publishers API service lets developers design computer
 programs that interact directly with the DFP platform. With these applications,
@@ -11,7 +11,7 @@ is available as a Ruby gem or gzipped tarball. It depends on the
 google-ads-common library which is base for all Google Ads APIs for Ruby.
 
 
-== What's in the client library?
+## What's in the client library?
 
 The client library provides full access to all the functionality of the
 DoubleClick For Publishers API web services plus more. It includes:
@@ -42,59 +42,68 @@ DoubleClick For Publishers API web services plus more. It includes:
     will have to set your credentials in the "~/dfp_api.yml" configuration file.
 
 
-= How to get started
+# How to get started
 
-== Installation
+## Installation
 
-google-dfp-api is a Ruby gem. See http://docs.rubygems.org/read/book/1
+`google-dfp-api` is a Ruby gem. See
+
+> [http://docs.rubygems.org/read/book/1]()
 
 Install it using the gem install command:
-  $ gem install google-dfp-api
+
+    $ gem install google-dfp-api
 
 or if you downloaded the gem package manually, use:
-  $ gem install --local google-dfp-api-VERSION.gem
+
+    $ gem install --local google-dfp-api-VERSION.gem
 
 
-== Using the library
+## Using the library
 
 In order to use the library you need to include its modules:
-  require 'dfp_api'
+
+    require 'dfp_api'
 
 Then, library object could be instantiated:
-  dfp = DfpApi::Api.new
 
-The default constructor will load library configuration from '~/dfp_api.yml'
+    dfp = DfpApi::Api.new
+
+The default constructor will load library configuration from `~/dfp_api.yml`
 file. Alternatively, you can pass a configuration hash directly to the
 constructor:
-  dfp = DfpApi::Api.new({
-     :authentication => {
-         :method => 'OAuth2',
-         :oauth2_client_id: 'INSERT_OAUTH2_CLIENT_ID_HERE',
-         :oauth2_client_secret: 'INSERT_OAUTH2_CLIENT_SECRET_HERE',
-         :application_name => 'Ruby DFP Sample',
-         :network_code => 123456
-     }
-   })
 
-To obtain OAuth2 client credentials, follow instructions on the wiki:
+    dfp = DfpApi::Api.new({
+      :authentication => {
+          :method => 'OAuth2',
+          :oauth2_client_id: 'INSERT_OAUTH2_CLIENT_ID_HERE',
+          :oauth2_client_secret: 'INSERT_OAUTH2_CLIENT_SECRET_HERE',
+          :application_name => 'Ruby DFP Sample',
+          :network_code => 123456
+      }
+    })
 
-  http://code.google.com/p/google-api-ads-ruby/wiki/OAuth2
+To obtain OAuth2 client credentials, follow instructions
+[on the wiki](http://github.com/googleads/google-api-ads-ruby/wiki/OAuth2).
 
 An example of configuration file is available as part of this library.
 
 *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
 
 
-== Using OAuth2.0
+## Using OAuth2.0
 
 It is recommended to use OAuth2.0 authentication method instead of ClientLogin
 (explicit email/password combination). OAuth2.0 support is almost transparent to
@@ -110,61 +119,66 @@ the library user. In order to use OAuth you just need to:
 See 'dfp_api.yml' configuration file and 'common/oauth2_handling.rb' example for
 more details.
 
-== Accessing services
+## Accessing services
 
 Once the library object is created you can request services with a 'service'
 method:
-  user_service = dfp.service(:UserService, <API_VERSION>)
 
-where <API_VERSION> is required version of DFP API as symbol, e.g. :v201311.
+    user_service = dfp.service(:UserService, <API_VERSION>)
+
+where <API_VERSION> is required version of DFP API as symbol, e.g. :v201403.
 
 Then you should be able to execute service methods:
 
-  # Create statement for all users up to 500 max.
-  statement = {:query => "LIMIT 500"}
+    # Create statement for all users up to 500 max.
+    statement = {:query => "LIMIT 500"}
 
-  # Execute request and get the response.
-  page = user_service.get_users_by_statement(statement)
+    # Execute request and get the response.
+    page = user_service.get_users_by_statement(statement)
 
-In case of paged results, the requested objects are available as ':results' key:
+In case of paged results, the requested objects are available as `:results` key:
 
-  # Print details about each user in results page.
-  page[:results].each_with_index do |user|
-    puts "[%d] name: %s, email: %s" % [user[:id], user[:name], user[:email]]
-  end
+    # Print details about each user in results page.
+    page[:results].each_with_index do |user|
+      puts "[%d] name: %s, email: %s" % [user[:id], user[:name], user[:email]]
+    end
 
 All object fields are automatically parsed by the library to convert types to
 native ones (Integer, Float etc.) where applicable. The field names are also
 converted to symbols in Ruby native snake_case format:
-  "displayName" -> :display_name
+
+    "displayName" -> :display_name
 
 
-== Running examples
+## Running examples
 
-Before running examples, please ensure that your 'dfp_api.yml' is filled in and
+Before running examples, please ensure that your `dfp_api.yml` is filled in and
 placed in your home directory. You can find the examples as part of the
 installed gem, download them as a tarball or view them online.
 
 Examples can be run by executing by running:
-  $ ruby <example_name>
 
-from the "examples/<version>/<service_name>" directory i.e.
+    $ ruby <example_name>
 
-  $ cd examples/v201311/user_service
-  $ ruby get_all_users.rb
+from the `examples/<version>/<service_name>` directory i.e.
+
+    $ cd examples/v201403/user_service
+    $ ruby get_all_users.rb
 
 Some examples require modification to be functional, like create_order example
 needs Advertiser, Trafficker and Salesperson IDs to be filled in.
 
 
-== How do I enable logging?
+## How do I enable 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'
-   }
+the `library.log_level` configuration variable to 'DEBUG':
+
+    config[:library] = {
+      :log_level => 'DEBUG'
+    }
+
 or via configuration file (see example).
 
 This will output the SOAP XML to STDOUT, which will usually show up in your
@@ -172,42 +186,43 @@ 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
-   dfp = DfpApi::Api.new
-   dfp.logger = logger
+
+    require 'logger'
+    logger = Logger.new('path/to/log_filename')
+    logger.level = Logger::DEBUG
+    dfp = DfpApi::Api.new
+    dfp.logger = logger
 
 Request details 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.
 
 
-== What if I am behind an HTTP Proxy server?
+## What if I am behind an HTTP Proxy server?
 
 You can specify a proxy server to be used for all requests as part of
 configuration hash:
 
-   config[:connection] = {
-     :proxy => 'http://user:password@proxy_hostname:8080'
-   }
+    config[:connection] = {
+      :proxy => 'http://user:password@proxy_hostname:8080'
+    }
 
 or via configuration file (see example).
 
-== How do I enable GZip responses compression?
+## How do I enable GZip responses 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.
 
 
-= External dependencies:
+# External dependencies:
 
 External dependencies should be pulled automatically on gem install. Here is the
 list though:
@@ -216,33 +231,29 @@ list though:
   - Savon 'the heavy metal Ruby SOAP client' (savon).
 
 
-= Where do I submit bug reports and feature requests?
-
-Bug reports and feature requests can be posted on the library page:
+# Where do I submit bug reports and feature requests?
 
-  http://code.google.com/p/google-api-ads-ruby/issues
+Bug reports and feature requests can be posted
+[on the library page](http://github.com/googleads/google-api-ads-ruby/issues).
 
-Questions can be asked on forum
+Questions can be asked
+[on the forum](http://groups.google.com/group/google-doubleclick-for-publishers-api/).
 
-  http://groups.google.com/group/google-doubleclick-for-publishers-api/
+Make sure to subscribe to our
+[Google Plus page](https://plus.google.com/+GoogleAdsDevelopers) for API change
+announcements and other news.
 
-Make sure to subscribe to our Google Plus page for API change announcements and
-other news:
+# Copyright/License Info
 
-  https://plus.google.com/+GoogleAdsDevelopers
+## License
 
-
-= Copyright/License Info
-
-== License
-
-Copyright 2011-2013, Google Inc. All Rights Reserved.
+Copyright 2011-2014, 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
 
-  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, WITHOUT WARRANTIES OR
@@ -250,10 +261,10 @@ CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
 
 
-== Authors
+## Authors
 
 Author:
     api.dklimkin@gmail.com (Danial Klimkin)
 
 Maintainer:
-    api.dklimkin@gmail.com (Danial Klimkin)
+    api.nicholaschen@gmail.com (Nicholas Chen)

data/examples/v201211/common/oauth2_jwt_handling.rb

@@ -18,8 +18,12 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example shows how to use OAuth2.0 authorization method with JWT (Service
-# Account).
+# This example illustrates how to use OAuth2.0 authentication method with
+# Service Account (JWT). For this example to work, your Service Account must be
+# a Google Apps for Business Account.
+#
+# See https://developers.google.com/doubleclick-publishers/docs/service_accounts
+# for more information.
 #
 # Tags: UserService.getUsersByStatement
 

data/examples/v201302/common/oauth2_jwt_handling.rb

@@ -18,8 +18,12 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example shows how to use OAuth2.0 authorization method with JWT (Service
-# Account).
+# This example illustrates how to use OAuth2.0 authentication method with
+# Service Account (JWT). For this example to work, your Service Account must be
+# a Google Apps for Business Account.
+#
+# See https://developers.google.com/doubleclick-publishers/docs/service_accounts
+# for more information.
 #
 # Tags: UserService.getUsersByStatement
 

data/examples/v201306/common/oauth2_jwt_handling.rb

@@ -18,8 +18,12 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example shows how to use OAuth2.0 authorization method with JWT (Service
-# Account).
+# This example illustrates how to use OAuth2.0 authentication method with
+# Service Account (JWT). For this example to work, your Service Account must be
+# a Google Apps for Business Account.
+#
+# See https://developers.google.com/doubleclick-publishers/docs/service_accounts
+# for more information.
 #
 # Tags: UserService.getUsersByStatement
 

data/examples/v201308/common/oauth2_jwt_handling.rb

@@ -18,8 +18,12 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example shows how to use OAuth2.0 authorization method with JWT (Service
-# Account).
+# This example illustrates how to use OAuth2.0 authentication method with
+# Service Account (JWT). For this example to work, your Service Account must be
+# a Google Apps for Business Account.
+#
+# See https://developers.google.com/doubleclick-publishers/docs/service_accounts
+# for more information.
 #
 # Tags: UserService.getUsersByStatement
 

data/examples/v201311/common/oauth2_jwt_handling.rb

@@ -18,8 +18,12 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example shows how to use OAuth2.0 authorization method with JWT (Service
-# Account).
+# This example illustrates how to use OAuth2.0 authentication method with
+# Service Account (JWT). For this example to work, your Service Account must be
+# a Google Apps for Business Account.
+#
+# See https://developers.google.com/doubleclick-publishers/docs/service_accounts
+# for more information.
 #
 # Tags: UserService.getUsersByStatement
 

data/examples/{v201302 → v201403}/activity_group_service/create_activity_groups.rb

@@ -25,7 +25,7 @@
 
 require 'dfp_api'
 
-API_VERSION = :v201302
+API_VERSION = :v201403
 
 def create_activity_groups()
   # Get DfpApi instance and load configuration from ~/dfp_api.yml.

data/examples/{v201306 → v201403}/activity_group_service/get_active_activity_groups.rb

@@ -25,7 +25,7 @@
 
 require 'dfp_api'
 
-API_VERSION = :v201306
+API_VERSION = :v201403
 PAGE_SIZE = 500
 
 def get_active_activity_groups()

data/examples/{v201306 → v201403}/activity_group_service/get_all_activity_groups.rb

@@ -25,7 +25,7 @@
 
 require 'dfp_api'
 
-API_VERSION = :v201306
+API_VERSION = :v201403
 PAGE_SIZE = 500
 
 def get_all_activity_groups()

data/examples/{v201306 → v201403}/activity_group_service/update_activity_groups.rb

@@ -21,12 +21,12 @@
 # This example updates activity groups by adding a company. To determine which
 # activity groups exist, run get_all_activity_groups.rb.
 #
-# Tags: ActivityGroupService.getActivityGroup
+# Tags: ActivityGroupService.getActivityGroupsByStatement
 # Tags: ActivityGroupService.updateActivityGroups
 
 require 'dfp_api'
 
-API_VERSION = :v201306
+API_VERSION = :v201403
 
 def update_activity_groups()
   # Get DfpApi instance and load configuration from ~/dfp_api.yml.
@@ -43,26 +43,35 @@ def update_activity_groups()
   activity_group_id = 'INSERT_ACTIVITY_GROUP_ID_HERE'
   advertiser_company_id = 'INSERT_ADVERTISER_COMPANY_ID_HERE'
 
-  # Get the activity group.
-  activity_group = activity_group_service.get_activity_group(activity_group_id)
+  # Create statement to select a single activity group.
+  statement = {
+     :query => 'WHERE id = :id ORDER BY id ASC LIMIT 1',
+     :values => [
+         {:key => 'id',
+          :value => {:value => activity_group_id, :xsi_type => 'NumberValue'}}
+     ]
+  }
 
-  # Update the companies.
-  activity_group[:company_ids] << advertiser_company_id
+  page = activity_group_service.get_activity_groups_by_statement(statement)
 
-  # Update the activity groups on the server.
-  return_activity_groups = activity_group_service.update_activity_groups([
-      activity_group])
+  if page[:results]
+    # Get the activity groups.
+    activity_groups = page[:results]
+
+    activity_groups.each do |activity_group|
+      # Update the companies.
+      activity_group[:company_ids] << advertiser_company_id
+    end
+
+    # Update the activity groups on the server.
+    return_activity_groups = activity_group_service.update_activity_groups(
+        activity_groups)
 
-  # Display results.
-  if return_activity_groups
     return_activity_groups.each do |updates_activity_group|
       puts "Activity group with ID: %d and name: %s was updated." %
           [updates_activity_group[:id], updates_activity_group[:name]]
     end
-  else
-    raise 'No activity groups were updated.'
   end
-
 end
 
 if __FILE__ == $0