google-dfp-api 1.3.1 → 1.4.0

data/lib/ad_manager_api/ad_manager_api_statement.rb

@@ -0,0 +1,62 @@
+# Encoding: utf-8
+#
+# Copyright:: Copyright 2014, 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.
+#
+# FilterStatement object to allow for simpler query pagination logic.
+
+module AdManagerApi
+
+  # Default page size to use with the FilterStatement.
+  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,
+                   offset=0)
+      @query_statement = query_statement.dup()
+      @values = values
+      @limit = limit
+      @offset = offset
+    end
+
+    attr_accessor :limit
+    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()
+      AdManagerApi::Utils::UtilityRegistry.instance.add('FilterStatement')
+    end
+  end
+end

data/lib/ad_manager_api/api_config.rb

@@ -0,0 +1,182 @@
+# 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.
+#
+# Helper methods for loading and managing the available services in the DFP API.
+
+require 'ads_common/api_config'
+
+require 'ad_manager_api/version'
+
+module AdManagerApi
+
+  # Contains helper methods for loading and managing the available services.
+  module ApiConfig
+
+    class << ApiConfig
+      include AdsCommon::ApiConfig
+    end
+
+    # Set defaults
+    DEFAULT_VERSION = :v201808
+    LATEST_VERSION = :v201808
+
+    # Set other constants
+    API_NAME = 'AdManagerApi'
+    DEFAULT_CONFIG_FILENAME = 'ad_manager_api.yml'
+
+    # Configure the services available to each version
+    @@service_config = {
+      :v201711 => [:ActivityGroupService, :ActivityService,
+                   :AdExclusionRuleService, :AdRuleService,
+                   :AudienceSegmentService, :BaseRateService, :CompanyService,
+                   :CdnConfigurationService, :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],
+      :v201802 => [:ActivityGroupService, :ActivityService,
+                   :AdExclusionRuleService, :AdRuleService,
+                   :AudienceSegmentService, :BaseRateService, :CompanyService,
+                   :CdnConfigurationService, :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],
+      :v201805 => [:ActivityGroupService, :ActivityService,
+                   :AdExclusionRuleService, :AdRuleService,
+                   :AudienceSegmentService, :BaseRateService, :CompanyService,
+                   :CdnConfigurationService, :ContactService,
+                   :ContentBundleService, :ContentMetadataKeyHierarchyService,
+                   :ContentService, :CreativeService, :CreativeSetService,
+                   :CreativeTemplateService, :CreativeWrapperService,
+                   :CustomFieldService, :CustomTargetingService,
+                   :DaiAuthenticationKeyService, :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],
+      :v201808 => [:ActivityGroupService, :ActivityService,
+                   :AdExclusionRuleService, :AdRuleService,
+                   :AudienceSegmentService, :BaseRateService, :CompanyService,
+                   :CdnConfigurationService, :ContactService,
+                   :ContentBundleService, :ContentMetadataKeyHierarchyService,
+                   :ContentService, :CreativeService, :CreativeSetService,
+                   :CreativeTemplateService, :CreativeWrapperService,
+                   :CustomFieldService, :CustomTargetingService,
+                   :DaiAuthenticationKeyService, :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]
+    }
+
+    # 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/',
+      :v201711 => 'https://ads.google.com/apis/ads/publisher/',
+      :v201802 => 'https://ads.google.com/apis/ads/publisher/',
+      :v201805 => 'https://ads.google.com/apis/ads/publisher/',
+      :v201808 => 'https://ads.google.com/apis/ads/publisher/'
+    }
+
+    public
+
+    # Getters for constants and module variables.
+    def self.default_version
+      DEFAULT_VERSION
+    end
+
+    def self.latest_version
+      LATEST_VERSION
+    end
+
+    def self.api_name
+      API_NAME
+    end
+
+    def self.service_config
+      @@service_config
+    end
+
+    def self.config(key)
+      @@config[key]
+    end
+
+    def self.subdir_config
+      nil
+    end
+
+    def self.default_config_filename
+      DEFAULT_CONFIG_FILENAME
+    end
+  end
+end

data/lib/ad_manager_api/credential_handler.rb

@@ -0,0 +1,74 @@
+# 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.
+#
+# Ad-Manager-specific credential handler.
+
+require 'ads_common/credential_handler'
+require 'ad_manager_api/api_config'
+require 'ad_manager_api/utils'
+
+module AdManagerApi
+
+  LEGACY_DEFAULT_APPLICATION_NAME = 'dfp_ruby_examples'
+  DEFAULT_APPLICATION_NAME = 'INSERT_APPLICATION_NAME_HERE'
+
+  class CredentialHandler < AdsCommon::CredentialHandler
+    # Create the list of credentials to be used by the auth handler for header
+    # generation.
+    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([], include_utils),
+          'networkCode' => result[:network_code]
+      }
+      return result
+    end
+
+    # Generates string to use as user agent in headers.
+    def generate_user_agent(extra_ids = [], include_utilities = true)
+      agent_app = @config.read('authentication.application_name')
+      extra_ids << ["AdManagerApi-Ruby/%s" %
+          AdManagerApi::ApiConfig::CLIENT_LIB_VERSION]
+      utility_registry = AdManagerApi::Utils::UtilityRegistry.instance
+      extra_ids += utility_registry.extract!.to_a if include_utilities
+      super(extra_ids, agent_app)
+    end
+
+    # Returns the network code specified in the current credentials.
+    def identifier()
+      return credentials[:extra_headers]['networkCode']
+    end
+
+    private
+
+    # Validates that the right credentials are being used for the chosen
+    # environment.
+    def validate_headers_for_server(credentials)
+      application_name = credentials[:application_name]
+      if (application_name.nil? or application_name.empty? or
+          application_name.include?(DEFAULT_APPLICATION_NAME) or
+          application_name.include?(LEGACY_DEFAULT_APPLICATION_NAME))
+        raise AdsCommon::Errors::AuthError, (
+            'Application name must be specified and cannot be the default')
+      end
+      return nil
+    end
+  end
+end

data/lib/ad_manager_api/errors.rb

@@ -0,0 +1,62 @@
+# Encoding: utf-8
+#
+# Copyright:: Copyright 2010, 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.
+#
+# Specific error handling for the Ad Manager API.
+
+require 'ads_common/errors'
+
+module AdManagerApi
+  module Errors
+
+    # This class encapsulates base class for API exceptions. More specific
+    # exceptions are generated based on Service WSDL.
+    class ApiException < AdsCommon::Errors::ApiException
+      attr_reader :array_fields
+
+      def initialize(exception_fault, registry)
+        @array_fields ||= []
+        extractor = AdsCommon::ResultsExtractor.new(registry)
+        exception_type = exception_fault[:application_exception_type]
+        exception_data = (exception_type.nil?) ? exception_fault :
+            extractor.extract_exception_data(exception_fault, exception_type)
+        exception_data.each { |key, value| set_field(key, value) }
+        super(exception_data[:message])
+      end
+
+      private
+
+      # Sets instance's property to a value if it is defined
+      def set_field(field, value)
+        if respond_to?(field)
+          value = arrayize(value) if is_array_field(field)
+          instance_variable_set("@#{field}", value)
+        end
+      end
+
+      # Makes sure object is an array
+      def arrayize(object)
+        return [] if object.nil?
+        return object.is_a?(Array) ? object : [object]
+      end
+
+      # Should a field be forced to be an array
+      def is_array_field(field)
+        return @array_fields.include?(field.to_s)
+      end
+    end
+  end
+end

data/lib/ad_manager_api/pql_statement_utils.rb

@@ -0,0 +1,194 @@
+# 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 'ad_manager_api/ad_manager_api_datetime'
+
+
+module AdManagerApi
+  # 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',
+      AdManagerApi::AdManagerDate => 'DateValue',
+      AdManagerApi::AdManagerDateTime => '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 Ad Manager API expects.
+    def values()
+      # values_array is a Ad Manger 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]
+      dateTypes = [AdManagerApi::AdManagerDate, AdManagerApi::AdManagerDateTime]
+      if dateTypes.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 = AdManagerApi::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',
+  #                        AdManagerApi::AdManagerDate.today-1)
+  #   b.with_bind_variable('end_date_time', AdManagerApi::Date.today)
+  #   b.order_by = 'ChangeDateTime'
+  #   b.ascending = false
+  # end
+  # sb.to_statement()
+  #
+  class StatementBuilder
+    SUGGESTED_PAGE_LIMIT = 500
+
+    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 Ad Manager 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