google-dfp-api 1.3.1 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a3c01ee377e07ccef8f553742f6b1cb77cf86ef0
-  data.tar.gz: c1d57cd2cac378111b4fe6398f08dbb5b51efb71
+  metadata.gz: cca4a5007163eed6eb420e5bcd596aad6a8e46da
+  data.tar.gz: 55450e9031c53c1fa17dde0758e698a57b6c6d3c
 SHA512:
-  metadata.gz: ce7b6a4e5fd4abb8442aa089a761d8ccb80f576e987159e8f5805dd76a901933fb6234fee8bf74ddd874bbb40a8125e0804732b62fd4ab6891838172e3caa32c
-  data.tar.gz: 87a194fd8b18ab97a791439a4be2c24f9182c1fd41187f10f8bd264bdc8041e90b91cfc7768893bcf15e3d525ce3b380b389df32d0948d7ef704d5d6d9922519
+  metadata.gz: e94b98c96ec7dcdafc1de8957a8859640ac79b164588aa37d46c80992731c254e3a387981de9d702d4af48dc9242e0551469d6a9c2ca3a4e014e626ac19e9179
+  data.tar.gz: 259c9606bfc434285eafadc0219559813bf23251c8dfc11c60dfe47eb2787efe980843685ccdd0a5a050613071d7d629344908421ab78b3a8347cbf30537cf73

data/ChangeLog

@@ -1,3 +1,11 @@
+1.4.0:
+  - Changed all DFP references to Ad Manager (for information on migrating, see
+    https://github.com/googleads/google-api-ads-ruby/wiki/DFP-to-Ad-Manager-rebrand-guide).
+  - Added support for v201808.
+  - Removed support for v201708.
+  - Removed examples for v201711.
+  - Updated examples with minor fixes.
+
 1.3.1:
   - Added support for LineItem.userConsentEligibility.
 

data/README.md

@@ -1,24 +1,24 @@
-# Google's DoubleClick For Publishers API Ruby Client Library
+# Google Ad Manager 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,
+The Google Ad Manager API lets developers design computer programs that
+interact directly with the Ad Manager platform. With these applications,
 advertisers and third parties can more efficiently -- and creatively -- manage
-their large or complex DoubleClick for Publishers accounts.
+their large or complex Ad Manager accounts.
 
-The DFP API Ruby Client Library makes it easy to write Ruby clients to
-programmatically access DoubleClick for Publishers accounts. The client library
-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.
+The Ad Manager API Ruby Client Library makes it easy to write Ruby clients to
+programmatically access Ad Manager accounts. The client library 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?
 
 The client library provides full access to all the functionality of the
-DoubleClick For Publishers API web services plus more. It includes:
+Ad Manager API web services plus more. It includes:
 
-  - DfpApi::Api class: The Api class provides methods for setting credentials
-    for accessing DFP accounts as well as for creating instances of the DFP
-    Service classes.
+  - AdManagerApi::Api class: The Api class provides methods for setting
+    credentials for accessing Ad Manager accounts as well as for creating
+    instances of the Ad Manager Service classes.
 
   - Ruby native objects support: All data is accepted and returned as Ruby
     hashes and arrays. No complex types are required!
@@ -39,7 +39,8 @@ DoubleClick For Publishers API web services plus more. It includes:
   - Examples: The Ruby client library comes with code samples in the "examples/"
     directory. We encourage you to use code samples to get started writing your
     own application. All the code samples are runnable out of the box, but you
-    will have to set your credentials in the "~/dfp_api.yml" configuration file.
+    will have to set your credentials in the "~/ad_manager_api.yml"
+    configuration file.
 
 
 # How to get started
@@ -68,22 +69,22 @@ You can do this with:
 
 In order to use the library you need to include its modules:
 
-    require 'dfp_api'
+    require 'ad_manager_api'
 
 Then, library object could be instantiated:
 
-    dfp = DfpApi::Api.new
+    ad_manager = AdManagerApi::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:
+The default constructor will load library configuration from
+`~/ad_manager_api.yml` file. Alternatively, you can pass a configuration hash
+directly to the constructor:
 
-    dfp = DfpApi::Api.new({
+    ad_manager = AdManagerApi::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',
+          :application_name => 'Ruby Ad Manager Sample',
           :network_code => 123456
       }
     })
@@ -119,17 +120,18 @@ In order to use OAuth you just need to:
   - handle OAuth2VerificationRequired error and pass verification code to the
     library.
 
-See 'dfp_api.yml' configuration file and 'common/oauth2_handling.rb' example for
-more details.
+See 'ad_manager_api.yml' configuration file and 'common/oauth2_handling.rb'
+example for more details.
 
 ## Accessing services
 
 Once the library object is created you can request services with a 'service'
 method:
 
-    user_service = dfp.service(:UserService, <API_VERSION>)
+    user_service = ad_manager.service(:UserService, <API_VERSION>)
 
-where <API_VERSION> is required version of DFP API as symbol, e.g. :v201403.
+where <API_VERSION> is required version of Ad Manager API as symbol,
+e.g. :v201403.
 
 Then you should be able to execute service methods:
 
@@ -155,8 +157,8 @@ converted to symbols in Ruby native snake_case format:
 
 ## Running examples
 
-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
+Before running examples, please ensure that your `ad_manager_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:
@@ -193,8 +195,8 @@ 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
+    ad_manager = AdManagerApi::Api.new
+    ad_manager.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
@@ -299,6 +301,7 @@ specific language governing permissions and limitations under the License.
 
 Author:
     Danial Klimkin
+    Donovan McMurray
 
 Maintainer:
-    Danial Klimkin
+    Donovan McMurray

data/ad_manager_api.yml

@@ -0,0 +1,51 @@
+---
+# This is an example configuration file for the Ruby Ad Manager API client
+# library. Please fill in the required fields, and copy it over to your home
+# directory. Detailed descriptions of these properties can be found at:
+# https://developers.google.com/ad-manager/docs/soap_xml
+:authentication:
+  # Authentication method, methods currently supported:
+  # OAUTH2, OAUTH2_SERVICE_ACCOUNT
+  :method: OAUTH2_SERVICE_ACCOUNT
+
+  # Auth parameters for OAUTH2_SERVICE_ACCOUNT method. See:
+  #   https://developers.google.com/accounts/docs/OAuth2ServiceAccount
+  # You can provide path to a file with 'oauth2_keyfile' or the key itself with
+  # 'oauth2_key' option.
+  :oauth2_keyfile: INSERT_OAUTH2_KEYFILE_HERE
+  # Specify the issuer only if you are using a key directly with no key file.
+  #:oauth2_key: INSERT_OAUTH2_KEY_HERE
+  #:oauth2_issuer: INSERT_OAUTH2_ISSUER_HERE
+  # To impersonate a user set prn to an email address.
+  #:oauth2_prn: INSERT_OAUTH2_PRN_HERE
+
+  # Auth parameters for OAUTH2 method.
+  # Set the OAuth2 client id and secret. Register your application here to
+  # obtain these values:
+  #   https://console.developers.google.com/
+  #:oauth2_client_id: INSERT_OAUTH2_CLIENT_ID_HERE
+  #:oauth2_client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
+  # Optional, see: https://developers.google.com/accounts/docs/OAuth2WebServer
+  #:oauth2_callback: INSERT_OAUTH2_CALLBACK_URL_HERE
+  #:oauth2_state: INSERT_OAUTH2_STATE_HERE
+  #:oauth2_access_type: INSERT_OAUTH2_ACCESS_TYPE_HERE
+  #:oauth2_prompt: INSERT_OAUTH2_PROMPT_HERE
+  # You can define extra scopes so that you can reuse your refresh token for
+  # other APIs.
+  #:oauth2_extra_scopes: [INSERT_EXTRA_SCOPES_HERE]
+
+  # Other parameters.
+  :application_name: INSERT_APPLICATION_NAME_HERE
+
+  # Required for all calls other than GetAllNetworks and MakeTestNetwork.
+  :network_code: INSERT_NETWORK_CODE_HERE
+:connection:
+  # Enable to request all responses to be compressed.
+  :enable_gzip: false
+  # If your proxy connection requires authentication, make sure to include it in
+  # the URL, e.g.: http://user:password@proxy_hostname:8080
+  #:proxy: INSERT_PROXY_HERE
+:library:
+  :log_level: INFO
+  # Optional: uncomment to disable user agent showing used utilities.
+  #:include_utilities_in_user_agent: false

data/lib/ad_manager_api.rb

@@ -0,0 +1,107 @@
+# 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.
+#
+# Contains the main classes for the client library.
+
+require 'ads_common/api'
+require 'ads_common/savon_headers/oauth_header_handler'
+require 'ad_manager_api/api_config'
+require 'ad_manager_api/credential_handler'
+require 'ad_manager_api/errors'
+require 'ad_manager_api/ad_manager_api_statement'
+require 'ad_manager_api/ad_manager_api_datetime'
+require 'ad_manager_api/pql_statement_utils'
+require 'ad_manager_api/utils_reporter'
+
+# Main namespace for all the client library's modules and classes.
+module AdManagerApi
+
+  # Wrapper class that serves as the main point of access for all the API usage.
+  #
+  # Holds all the services, as well as login credentials.
+  #
+  class Api < AdsCommon::Api
+    attr_reader :utils_reporter
+
+    # Constructor for API.
+    def initialize(provided_config = nil)
+      super(provided_config)
+      @credential_handler = AdManagerApi::CredentialHandler.new(@config)
+      @utils_reporter = AdManagerApi::UtilsReporter.new(@credential_handler)
+    end
+
+    # Getter for the API service configurations.
+    def api_config
+      AdManagerApi::ApiConfig
+    end
+
+    # Returns an instance of StatementBuilder object.
+    def new_statement_builder(&block)
+      return AdManagerApi::StatementBuilder.new(self, &block)
+    end
+
+    def new_report_statement_builder(&block)
+      statement = AdManagerApi::StatementBuilder.new(self) do |sb|
+        sb.limit = nil
+        sb.offset = nil
+      end
+      statement.configure(&block)
+      return statement
+    end
+
+    # Returns an instance of AdManagerDate.
+    def date(*args)
+      return AdManagerApi::AdManagerDate.new(self, *args)
+    end
+
+    # Returns an instance of AdManagerDate representing the current day.
+    def today(*args)
+      return AdManagerApi::AdManagerDate.today(self, *args)
+    end
+
+    # Returns an instance of AdManagerDateTime.
+    def datetime(*args)
+      return AdManagerApi::AdManagerDateTime.new(self, *args)
+    end
+
+    # Returns an instance of AdManagerDateTime representing the current time.
+    def now(*args)
+      return AdManagerApi::AdManagerDateTime.now(self, *args)
+    end
+
+    # Returns an instance of AdManagerDateTime in the UTC timezone.
+    def utc(*args)
+      return AdManagerApi::AdManagerDateTime.utc(self, *args)
+    end
+
+    private
+
+    # Retrieve Ad Manager HeaderHandler per credential.
+    def soap_header_handler(auth_handler, version, header_ns, default_ns)
+      auth_method = @config.read('authentication.method', :OAUTH2)
+      handler_class  = case auth_method
+        when :OAUTH2, :OAUTH2_SERVICE_ACCOUNT
+          AdsCommon::SavonHeaders::OAuthHeaderHandler
+        else
+          raise AdsCommon::Errors::AuthError,
+              "Unknown auth method: %s" % auth_method
+      end
+      return handler_class.new(@credential_handler, auth_handler, header_ns,
+                               default_ns, version)
+    end
+  end
+end

data/lib/ad_manager_api/ad_manager_api_datetime.rb

@@ -0,0 +1,188 @@
+# Encoding: utf-8
+#
+# Copyright:: Copyright 2017, 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.
+#
+# AdManagerDate and AdManagerDateTime convert between native ruby Date and Time
+# objects and the Ad Manager API's Date and DateTime objects.
+
+require 'date'
+require 'tzinfo'
+
+
+module AdManagerApi
+  class AdManagerDate
+    # Create a new AdManagerDate, a utility class that allows for
+    # interoperability between the Ad Manager API's Date objects and ruby's
+    # Date class.
+    #
+    # Args:
+    #   - args:
+    #     - ([year, [month, [day]]]), integer values, uses Date defaults
+    #     - (date), a native ruby Date object
+    #     - (ad_manager_date), an Ad Manager Date hash representation
+    # Returns:
+    #   - ad_manager_date: an instance of AdManagerDate
+    def initialize(api, *args)
+      @api = api
+      @api.utils_reporter.ad_manager_date_used()
+
+      case args.first
+      when Hash
+        hash = args.first
+        date_args = [hash[:year], hash[:month], hash[:day]]
+      when Date
+        date = args.first
+        date_args = [date.year, date.month, date.day]
+      else
+        date_args = args
+      end
+      @date = Date.new(*date_args)
+    end
+
+    # Creates an AdManagerDate object denoting the present day.
+    def self.today(api, *args)
+      self.new(api, Date.today(*args))
+    end
+
+    # When an unrecognized method is applied to AdManagerDate, pass it through
+    # to the internal ruby Date.
+    def method_missing(name, *args, &block)
+      result = @date.send(name, *args, &block)
+      return self.class.new(@api, result) if result.is_a? Date
+      return result
+    end
+
+    # Convert AdManagerDate into a hash representation which can be consumed by
+    # the Ad Manager API. E.g., a hash that can be passed as PQL Date variables.
+    #
+    # Returns:
+    #   - ad_manager_datetime: an Ad Manager Date hash representation
+    def to_h()
+      return {:year => @date.year, :month => @date.month, :day => @date.day}
+    end
+  end
+
+  class AdManagerDateTime
+    attr_accessor :timezone
+
+    # Create a new AdManagerDateTime, a utility class that allows for
+    # interoperability between the Ad Manager API's DateTime objects and ruby's
+    # Time class. The last argument must be a valid timezone identifier,
+    # e.g. "America/New_York".
+    #
+    # Args:
+    #   - args:
+    #     - ([year, [month, [day, [hour, [minute, [second,]]]]]] timezone)
+    #     - (time, timezone), a native Time object and a timezone identifier
+    #     - (ad_manager_datetime), an Ad Manager DateTime hash representation
+    #
+    # Returns:
+    #   - ad_manager_datetime: an instance of AdManagerDateTime
+    def initialize(api, *args)
+      @api = api
+      @api.utils_reporter.ad_manager_date_time_used()
+
+      # Handle special cases when an Ad Manager DateTime hash or ruby Time
+      # instance are passed as the first argument to the constructor.
+      case args.first
+      when Hash
+        hash = args.first
+        datetime_args = [hash[:date][:year], hash[:date][:month],
+            hash[:date][:day], hash[:hour], hash[:minute], hash[:second],
+            hash[:time_zone_id]]
+      when AdManagerDateTime, Time, DateTime
+        time = args.first
+        datetime_args = [args.last]
+        [:sec, :min, :hour, :day, :month, :year].each do |duration|
+          datetime_args.unshift(time.send(duration))
+        end
+      else
+        datetime_args = args
+      end
+      # Check the validity of the timezone parameter, which is required.
+      if not TZInfo::Timezone.all_identifiers.include?(datetime_args.last)
+        raise "Last argument to AdManagerDateTime constructor must be valid" +
+            "timezone"
+      end
+      # Set timezone attribute and pass its utc offset into the Time
+      # constructor.
+      @timezone = TZInfo::Timezone.get(datetime_args.pop)
+      @time = Time.new(*datetime_args,
+          utc_offset=@timezone.current_period.utc_offset)
+    end
+
+    # Create an AdManagerDateTime for the current time in the specified
+    # timezone.
+    #
+    # Args:
+    #   - timezone: a valid timezone identifier, e.g. "America/New_York"
+    #
+    # Returns:
+    #   - ad_manager_datetime: an instance of AdManagerDateTime
+    def self.now(api, timezone)
+      new(api, TZInfo::Timezone.get(timezone).now, timezone)
+    end
+
+    # Create an AdManagerDateTime in the "UTC" timezone. Calls the
+    # AdManagerDateTime contstructor with timezone identifier "UTC".
+    #
+    # Args:
+    #   - ([year, [month, [day, [hour, [minute, [second]]]]]])
+    #
+    # Returns:
+    #   - ad_manager_datetime: an instance of AdManagerDateTime
+    def self.utc(api, *args)
+      new(api, *args + ['UTC'])
+    end
+
+    # Convert AdManagerDateTime into a hash representation which can be consumed
+    # by the Ad Manager API. E.g., a hash that can be passed as PQL DateTime
+    # variables.
+    #
+    # Returns:
+    #   - ad_manager_datetime_hash: a hash representation of an
+    #     AdManagerDateTime
+    def to_h
+      {
+        :date => AdManagerApi::AdManagerDate.new(
+            @api, @time.year, @time.month, @time.day
+        ).to_h,
+        :hour => @time.hour,
+        :minute => @time.min,
+        :second => @time.sec,
+        :time_zone_id => @timezone.identifier
+      }
+    end
+
+    # When an unrecognized method is applied to AdManagerDateTime, pass it
+    # through to the internal ruby Time.
+    def method_missing(name, *args, &block)
+      # Restrict time zone related functions from being passed to internal ruby
+      # Time attribute, since AdManagerDateTime handles timezones its own way.
+      restricted_functions = [:dst?, :getgm, :getlocal, :getutc, :gmt,
+          :gmtime, :gmtoff, :isdst, :localtime, :utc]
+      if restricted_functions.include? name
+        raise NoMethodError, 'undefined method %s for %s' % [name, self]
+      end
+      result = @time.send(name, *args, &block)
+      if result.is_a? Time
+        return self.class.new(@api, result, @timezone.identifier)
+      else
+        return result
+      end
+    end
+  end
+end