google-dfp-api 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2c39e1d31ae64f6e6beab6d065790bad6b39c904
-  data.tar.gz: a01a5e853c6c4ce4e4d36355160a335b9bc4a603
+  metadata.gz: 76dcba9593eb8099843bdbfd4f5e0667fe68083b
+  data.tar.gz: e34fe0017255d433493d10a7490b32b167ee054b
 SHA512:
-  metadata.gz: 9c29297d56691d1ad0b93943c6bf28e4add3040b3fa812717a96d81fa4a4427ce4488817fda8c3b8bb21407daf7724a4f68ad1fdef5fc6f0dc37da8e3001254d
-  data.tar.gz: 1e0f7af46183d3a1932c38ae92b51b3cd7da0d004ffb170345d4a094ddd541053d49a6c1315616033f90409018fa077744fe91c96f4b9659607a0bde8a8c19ff
+  metadata.gz: ef6fa87936a5079b73923bc26f9d10441586ce19e76672004f8a3c16af79d407b436a094cf39506465baa146d86c65dd95afdf792f9e43f19dff124fc388b1fc
+  data.tar.gz: 71117d2b974fd3e351ee58d8038057addaa8a722d64a3c765399b8e514fe7d681dd409d29440ac316b63f9c1301a27d9d1098e4c4f51fa639811ef961bcda521

data/ChangeLog

@@ -1,7 +1,16 @@
+1.2.0:
+  - Added support for v201802.
+  - Removed support for v201702.
+  - Removed examples for v201705.
+  - Added StatementBuilder for easier PQL statement generation.
+  - Added DfpDate and DfpDateTime to make using Date and Time objects easier
+    in the DFP API.
+  - Deprecated FilterStatement.
+
 1.1.0:
-  - Added support for v201711
-  - Removed support for v201611
-  - Removed examples for v201702
+  - Added support for v201711.
+  - Removed support for v201611.
+  - Removed examples for v201702.
 
 1.0.0:
   - Major version bump. The library has been stable and feature complete for

data/dfp_api.yml

@@ -47,3 +47,5 @@
   #: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/dfp_api.rb

@@ -23,6 +23,9 @@ require 'dfp_api/api_config'
 require 'dfp_api/credential_handler'
 require 'dfp_api/errors'
 require 'dfp_api/dfp_api_statement'
+require 'dfp_api/dfp_api_datetime'
+require 'dfp_api/pql_statement_utils'
+require 'dfp_api/utils_reporter'
 
 # Main namespace for all the client library's modules and classes.
 module DfpApi
@@ -32,10 +35,13 @@ module DfpApi
   # 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 = DfpApi::CredentialHandler.new(@config)
+      @utils_reporter = DfpApi::UtilsReporter.new(@credential_handler)
     end
 
     # Getter for the API service configurations.
@@ -43,6 +49,45 @@ module DfpApi
       DfpApi::ApiConfig
     end
 
+    # Returns an instance of StatementBuilder object.
+    def new_statement_builder(&block)
+      return DfpApi::StatementBuilder.new(self, &block)
+    end
+
+    def new_report_statement_builder(&block)
+      statement = DfpApi::StatementBuilder.new(self) do |sb|
+        sb.limit = nil
+        sb.offset = nil
+      end
+      statement.configure(&block)
+      return statement
+    end
+
+    # Returns an instance of DfpDate.
+    def date(*args)
+      return DfpApi::DfpDate.new(self, *args)
+    end
+
+    # Returns an instance of DfpDate representing the current day.
+    def today(*args)
+      return DfpApi::DfpDate.today(self, *args)
+    end
+
+    # Returns an instance of DfpDateTime.
+    def datetime(*args)
+      return DfpApi::DfpDateTime.new(self, *args)
+    end
+
+    # Returns an instance of DfpDateTime representing the current time.
+    def now(*args)
+      return DfpApi::DfpDateTime.now(self, *args)
+    end
+
+    # Returns an instance of DfpDateTime in the UTC timezone.
+    def utc(*args)
+      return DfpApi::DfpDateTime.utc(self, *args)
+    end
+
     private
 
     # Retrieve DFP HeaderHandler per credential.

data/lib/dfp_api/api_config.rb

@@ -31,8 +31,8 @@ module DfpApi
     end
 
     # Set defaults
-    DEFAULT_VERSION = :v201711
-    LATEST_VERSION = :v201711
+    DEFAULT_VERSION = :v201802
+    LATEST_VERSION = :v201802
 
     # Set other constants
     API_NAME = 'DfpApi'
@@ -40,30 +40,6 @@ module DfpApi
 
     # Configure the services available to each version
     @@service_config = {
-      :v201702 => [:ActivityGroupService, :ActivityService,
-                   :AdExclusionRuleService, :AdRuleService,
-                   :AudienceSegmentService, :BaseRateService, :CompanyService,
-                   :ContactService, :ContentBundleService,
-                   :ContentMetadataKeyHierarchyService, :ContentService,
-                   :CreativeService, :CreativeSetService,
-                   :CreativeTemplateService, :CreativeWrapperService,
-                   :CustomFieldService, :CustomTargetingService,
-                   :ExchangeRateService, :ForecastService, :InventoryService,
-                   :LabelService, :LineItemCreativeAssociationService,
-                   :LineItemService, :LineItemTemplateService,
-                   :LiveStreamEventService, :MobileApplicationService,
-                   :NativeStyleService, :NetworkService, :OrderService,
-                   :PackageService, :ProductPackageService,
-                   :ProductPackageItemService, :PlacementService,
-                   :PremiumRateService, :ProductService,
-                   :ProductTemplateService, :ProposalLineItemService,
-                   :ProposalService, :PublisherQueryLanguageService,
-                   :RateCardService, :ReconciliationOrderReportService,
-                   :ReconciliationLineItemReportService,
-                   :ReconciliationReportRowService,
-                   :ReconciliationReportService, :ReportService,
-                   :SuggestedAdUnitService, :TeamService, :UserService,
-                   :UserTeamAssociationService, :WorkflowRequestService],
       :v201705 => [:ActivityGroupService, :ActivityService,
                    :AdExclusionRuleService, :AdRuleService,
                    :AudienceSegmentService, :BaseRateService, :CompanyService,
@@ -136,7 +112,7 @@ module DfpApi
                    :ReconciliationReportService, :ReportService,
                    :SuggestedAdUnitService, :TeamService, :UserService,
                    :UserTeamAssociationService, :WorkflowRequestService],
-      :v201711 => [:ActivityGroupService, :ActivityService,
+      :v201802 => [:ActivityGroupService, :ActivityService,
                    :AdExclusionRuleService, :AdRuleService,
                    :AudienceSegmentService, :BaseRateService, :CompanyService,
                    :CdnConfigurationService, :ContactService,
@@ -159,17 +135,17 @@ module DfpApi
                    :ReconciliationReportRowService,
                    :ReconciliationReportService, :ReportService,
                    :SuggestedAdUnitService, :TeamService, :UserService,
-                   :UserTeamAssociationService, :WorkflowRequestService],
+                   :UserTeamAssociationService, :WorkflowRequestService]
     }
 
     # Configure the base URL for each version and scope.
     @@config = {
       :oauth_scope => 'https://www.googleapis.com/auth/dfp',
       :header_ns => 'https://www.google.com/apis/ads/publisher/',
-      :v201702 => 'https://ads.google.com/apis/ads/publisher/',
       :v201705 => 'https://ads.google.com/apis/ads/publisher/',
       :v201708 => 'https://ads.google.com/apis/ads/publisher/',
-      :v201711 => 'https://ads.google.com/apis/ads/publisher/'
+      :v201711 => 'https://ads.google.com/apis/ads/publisher/',
+      :v201802 => 'https://ads.google.com/apis/ads/publisher/'
     }
 
     public

data/lib/dfp_api/credential_handler.rb

@@ -19,6 +19,7 @@
 
 require 'ads_common/credential_handler'
 require 'dfp_api/api_config'
+require 'dfp_api/utils'
 
 module DfpApi
 
@@ -31,17 +32,21 @@ module DfpApi
     def credentials(credentials_override = nil)
       result = super(credentials_override)
       validate_headers_for_server(result)
+      include_utils = @config.read('library.include_utilities_in_user_agent',
+          true)
       result[:extra_headers] = {
-          'applicationName' => generate_user_agent(),
+          'applicationName' => generate_user_agent([], include_utils),
           'networkCode' => result[:network_code]
       }
       return result
     end
 
     # Generates string to use as user agent in headers.
-    def generate_user_agent(extra_ids = [])
+    def generate_user_agent(extra_ids = [], include_utilities = true)
       agent_app = @config.read('authentication.application_name')
       extra_ids << ["DfpApi-Ruby/%s" % DfpApi::ApiConfig::CLIENT_LIB_VERSION]
+      utility_registry = DfpApi::Utils::UtilityRegistry.instance
+      extra_ids += utility_registry.extract!.to_a if include_utilities
       super(extra_ids, agent_app)
     end
 

data/lib/dfp_api/dfp_api_datetime.rb

@@ -0,0 +1,182 @@
+# 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.
+#
+# DfpDate and DfpDateTime convert between native ruby Date and Time objects and
+# the DFP API's Date and DateTime objects.
+
+require 'date'
+require 'tzinfo'
+
+
+module DfpApi
+  class DfpDate
+    # Create a new DfpDate, a utility class that allows for interoperability
+    # between the DFP 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
+    #     - (dfp_date), a DFP Date hash representation
+    # Returns:
+    #   - dfp_date: an instance of DfpDate
+    def initialize(api, *args)
+      @api = api
+      @api.utils_reporter.dfp_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 a DfpDate object denoting the present day.
+    def self.today(api, *args)
+      self.new(api, Date.today(*args))
+    end
+
+    # When an unrecognized method is applied to DfpDate, 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 DfpDate into a hash representation which can be consumed by
+    # the DFP API. E.g., a hash that can be passed as PQL Date variables.
+    #
+    # Returns:
+    #   - dfp_datetime: a DFP Date hash representation
+    def to_h()
+      return {:year => @date.year, :month => @date.month, :day => @date.day}
+    end
+  end
+
+  class DfpDateTime
+    attr_accessor :timezone
+
+    # Create a new DfpDateTime, a utility class that allows for interoperability
+    # between the DFP 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
+    #     - (dfp_datetime), a DFP DateTime hash representation
+    #
+    # Returns:
+    #   - dfp_datetime: an instance of DfpDateTime
+    def initialize(api, *args)
+      @api = api
+      @api.utils_reporter.dfp_date_time_used()
+
+      # Handle special cases when a DFP 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 DfpDateTime, 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 DfpDateTime 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 a DfpDateTime for the current time in the specified timezone.
+    #
+    # Args:
+    #   - timezone: a valid timezone identifier, e.g. "America/New_York"
+    #
+    # Returns:
+    #   - dfp_datetime: an instance of DfpDateTime
+    def self.now(api, timezone)
+      new(api, TZInfo::Timezone.get(timezone).now, timezone)
+    end
+
+    # Create a DfpDateTime in the "UTC" timezone. Calls the DfpDateTime
+    # contstructor with timezone identifier "UTC".
+    #
+    # Args:
+    #   - ([year, [month, [day, [hour, [minute, [second]]]]]])
+    #
+    # Returns:
+    #   - dfp_datetime: an instance of DfpDateTime
+    def self.utc(api, *args)
+      new(api, *args + ['UTC'])
+    end
+
+    # Convert DfpDateTime into a hash representation which can be consumed by
+    # the DFP API. E.g., a hash that can be passed as PQL DateTime variables.
+    #
+    # Returns:
+    #   - dfp_datetime_hash: a hash representation of a DfpDateTime
+    def to_h
+      {
+        :date => DfpApi::DfpDate.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 DfpDateTime, 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 DfpDateTime 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

data/lib/dfp_api/dfp_api_statement.rb

@@ -23,6 +23,7 @@ module DfpApi
   SUGGESTED_PAGE_LIMIT = 500
 
   # A statement object for PQL and get*ByStatement queries.
+  # Deprecated. Use StatementBuilder instead.
   class FilterStatement
     # Constructor for a Filter Statement.
     def initialize(query_statement='', values=[], limit=SUGGESTED_PAGE_LIMIT,
@@ -37,17 +38,25 @@ module DfpApi
     attr_accessor :offset
 
     def toStatement()
+      register_filter_statement_util()
       statement = @query_statement + ' LIMIT %d OFFSET %d' % [@limit, @offset]
       return {:query => statement, :values => @values}
     end
 
     def toStatementForAction()
+      register_filter_statement_util()
       return {:query => @query_statement.dup(), :values => @values}
     end
 
     def toStatementWithoutOffset()
+      register_filter_statement_util()
       statement = @query_statement + ' LIMIT %d' % [@limit]
       return {:query => statement, :values => @values}
     end
+
+    private
+    def register_filter_statement_util()
+      DfpApi::Utils::UtilityRegistry.instance.add('FilterStatement')
+    end
   end
 end

data/lib/dfp_api/pql_statement_utils.rb

@@ -0,0 +1,193 @@
+# 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.
+#
+# StatementBuilder object to allow for simpler PQL statement generation.
+
+require 'dfp_api/dfp_api_datetime'
+
+
+module DfpApi
+  # Default page size to use with the StatementBuilder.
+  SUGGESTED_PAGE_LIMIT = 500
+
+  # Query class used by StatementBuilder.
+  class PQLQuery
+    # Create a new query.
+    def initialize(query = nil)
+      @query = (query.nil?) ? nil : query.dup()
+    end
+
+    # Concatenate a new clause onto the current query.
+    def <<(clause)
+      @query = (@query.nil?) ? clause : @query << ' ' << clause
+    end
+
+    # Return the query string for a PQLQuery
+    def to_s()
+      @query.dup()
+    end
+  end
+
+  # Values class used by StatementBuilder.
+  class PQLValues
+    VALUE_TYPES = {
+      Numeric => 'NumberValue',
+      Integer => 'NumberValue',
+      Float => 'NumberValue',
+      String => 'TextValue',
+      TrueClass => 'BooleanValue',
+      FalseClass => 'BooleanValue',
+      Array => 'SetValue',
+      DfpApi::DfpDate => 'DateValue',
+      DfpApi::DfpDateTime => 'DateTimeValue'
+    }
+
+    # Create a new values object.
+    def initialize(values = {})
+      @values = values || {}
+    end
+
+    # Add a value to the current values object on the provided key.
+    def add_value(key, value)
+      @values[key.to_sym] = generate_value_object(value)
+    end
+
+    # Get values as an array, the format the DFP API expects.
+    def values()
+      # values_array is a DFP compliant list of values of the following form:
+      # [:key => ..., :value => {:xsi_type => ..., :value => ...}]
+      values_array = @values.map do |key, value|
+        raise 'Missing value in StatementBuilder.' if value.nil?
+        raise 'Value cannot be nil on StatementBuilder.' if value[:value].nil?
+        raise 'Missing value type for %s.' % key if value[:xsi_type].nil?
+        unless VALUE_TYPES.values.include?(value[:xsi_type])
+          raise 'Unknown value type for %s.' % key
+        end
+        if value[:xsi_type] == 'SetValue'
+          if value[:value].map {|v| v.class}.to_set.size > 1
+            raise 'Cannot pass more than one type in set variable, %s.' % key
+          end
+        end
+        if value[:xsi_type] == 'DateTimeValue'
+          unless value[:value][:time_zone_id]
+            raise 'Missing timezone on DateTimeValue variable, %s.' %key
+          end
+        end
+        {:key => key.to_s(), :value => value}
+      end
+      return values_array
+    end
+
+    # Create an individual value object by inferring the xsi_type. If the value
+    # type isn't recognized, return the original value parameter.
+    def generate_value_object(value)
+      type = VALUE_TYPES[value.class]
+      if [DfpApi::DfpDate, DfpApi::DfpDateTime].include?(value.class)
+        value = value.to_h
+      end
+      return value if type.nil?
+      return {:xsi_type => type, :value => value}
+    end
+  end
+
+  # A utility class for building PQL statements, used by the
+  # PublisherQueryLanguageService and other services' get*ByStatement and
+  # perform*Action requsts.
+  #
+  # Example usage:
+  # sb = DfpApi::StatementBuilder.new do |b|
+  #   b.select = 'ChangeDateTime, EntityId, EntityType, Operation'
+  #   b.from = 'Change_History'
+  #   b.where = 'ChangeDateTime < :start_date_time ' +
+  #             'AND ChangeDateTime > :end_date_time'
+  #   b.with_bind_variable('start_date_time', DfpApi::DfpDate.today-1)
+  #   b.with_bind_variable('end_date_time', DfpApi::Date.today)
+  #   b.order_by = 'ChangeDateTime'
+  #   b.ascending = false
+  # end
+  # sb.to_statement()
+  #
+  class StatementBuilder
+    SELECT = 'SELECT %s'
+    FROM = 'FROM %s'
+    WHERE = 'WHERE %s'
+    ORDER = 'ORDER BY %s %s'
+    LIMIT = 'LIMIT %d'
+    OFFSET = 'OFFSET %d'
+
+    attr_accessor :select, :from, :where, :order_by, :ascending, :limit, :offset
+
+    # Create a StatementBuilder object.
+    def initialize(api, &block)
+      @api = api
+      @select = nil
+      @from = nil
+      @where = nil
+      @order_by = nil
+      @ascending = true
+      @limit = SUGGESTED_PAGE_LIMIT
+      @offset = 0
+      @pql_values = PQLValues.new
+      yield self if block_given?
+    end
+
+    # Edit a StatmentBuilder object with a block.
+    def configure(&block)
+      yield self
+    end
+
+    # Add a value to be matched to bind a variable in WHERE conditions.
+    def with_bind_variable(key, value)
+      @pql_values.add_value(key, value)
+      return self
+    end
+
+    # Return a list of validation errors.
+    def validate()
+      if !@select.to_s.strip.empty? and @from.to_s.strip.empty?
+        raise 'FROM clause is required with SELECT'
+      end
+      if !@from.to_s.strip.empty? and @select.to_s.strip.empty?
+        raise 'SELECT clause is required with FROM'
+      end
+      if !@offset.nil? and @limit.nil?
+        raise 'LIMIT clause is required with OFFSET'
+      end
+      unless @limit.is_a? Integer or @limit.nil?
+        raise 'LIMIT must be an integer'
+      end
+      unless @offset.is_a? Integer or @offset.nil?
+        raise 'OFFSET must be an integer'
+      end
+    end
+
+    # Create a statement object that can be sent in a DFP API request.
+    def to_statement()
+      @api.utils_reporter.statement_builder_used()
+      validate()
+      ordering = @ascending ? 'ASC' : 'DESC'
+      pql_query = PQLQuery.new
+      pql_query << SELECT % @select unless @select.to_s.empty?
+      pql_query << FROM % @from unless @from.to_s.empty?
+      pql_query << WHERE % @where unless @where.to_s.empty?
+      pql_query << ORDER % [@order_by, ordering] unless @order_by.to_s.empty?
+      pql_query << LIMIT % @limit unless @limit.nil?
+      pql_query << OFFSET % @offset unless @offset.nil?
+      return {:query => pql_query.to_s(), :values => @pql_values.values}
+    end
+  end
+end