google-adwords-api 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7918e647f6e65a7e6dc263b1ace9efaa64374594
-  data.tar.gz: ecba28d77d77bbe7cf7cd60262bcecb5d292f5ca
+  metadata.gz: 8d7cb94ca2d32367dc495517785a534f443f2571
+  data.tar.gz: 3ace7373eeb42580acb914556cb6479a3a93b9ba
 SHA512:
-  metadata.gz: 28d2ad3aedb29c6be059e4f93c31f662fe89b4f01e450fd3ee3f93aab18ae4e1065cecf0dc7c6c1bd109bb89fbce2f99b6371d388df04e0b0d7bea08db46f2f8
-  data.tar.gz: c4130ea29ee7620e73c0a1aeaf8e25ffeabd905cb077a296ce2bd43f7084d1004ed185ac1aca2f91a7b8d412170c37fa6ba848da9a994dfaacbd4507e9e8ef45
+  metadata.gz: d3058ad324f73b0db96ec1e0839fd3bb30db34d15e6472c6bb2b3f8c27c0dbdaf663da97674e9a5711db6578033b92f9bb2358bbe6d86c73faf4e0e8e4ebd211
+  data.tar.gz: 67d37401dd0c7d560167332aa39a7955608cc45eeffa4e8ac9bc4eadf0ae054fc314a9dcc47b2d76d6e07e19e7b49f3c785111a0b99482de700e6501dc730350

data/ChangeLog

@@ -1,3 +1,8 @@
+1.1.0:
+  - Added ReportQueryBuilder and ServiceQueryBuilder to aid in constructing
+    AWQL for both contexts.
+  - Remove deprecated API version v201702.
+
 1.0.1:
   - Support and examples for v201710.
 

data/lib/adwords_api.rb

@@ -25,6 +25,8 @@ require 'adwords_api/errors'
 require 'adwords_api/report_utils'
 require 'adwords_api/batch_job_utils'
 require 'adwords_api/utils_reporter'
+require 'adwords_api/query_utils/report_query_builder'
+require 'adwords_api/query_utils/service_query_builder'
 
 # Main namespace for all the client library's modules and classes.
 module AdwordsApi
@@ -206,6 +208,18 @@ module AdwordsApi
       return AdwordsApi::BatchJobUtils.new(self, version)
     end
 
+    # Returns an instance of ReportQueryBuilder to aid in generating AWQL for
+    # reports.
+    def report_query_builder(&block)
+      return AdwordsApi::ReportQueryBuilder.new(self, &block)
+    end
+
+    # Returns an instance of ServiceQueryBuilder to aid in generating AWQL for
+    # service queries.
+    def service_query_builder(&block)
+      return AdwordsApi::ServiceQueryBuilder.new(self, &block)
+    end
+
     private
 
     # Executes block with a temporary flag set to a given value. Returns block

data/lib/adwords_api/api_config.rb

@@ -42,52 +42,6 @@ module AdwordsApi
 
     # Configure the services available to each version
     @@service_config = {
-      :v201702 => [
-          :AccountLabelService,
-          :AdCustomizerFeedService,
-          :AdGroupAdService,
-          :AdGroupBidModifierService,
-          :AdGroupCriterionService,
-          :AdGroupExtensionSettingService,
-          :AdGroupFeedService,
-          :AdGroupService,
-          :AdParamService,
-          :AdwordsUserListService,
-          :BatchJobService,
-          :BiddingStrategyService,
-          :BudgetOrderService,
-          :BudgetService,
-          :CampaignCriterionService,
-          :CampaignExtensionSettingService,
-          :CampaignFeedService,
-          :CampaignService,
-          :CampaignSharedSetService,
-          :ConstantDataService,
-          :ConversionTrackerService,
-          :CustomerExtensionSettingService,
-          :CustomerFeedService,
-          :CustomerService,
-          :CustomerSyncService,
-          :DataService,
-          :DraftService,
-          :DraftAsyncErrorService,
-          :FeedItemService,
-          :FeedMappingService,
-          :FeedService,
-          :LabelService,
-          :LocationCriterionService,
-          :ManagedCustomerService,
-          :MediaService,
-          :OfflineCallConversionFeedService,
-          :OfflineConversionFeedService,
-          :ReportDefinitionService,
-          :SharedCriterionService,
-          :SharedSetService,
-          :TargetingIdeaService,
-          :TrafficEstimatorService,
-          :TrialService,
-          :TrialAsyncErrorService
-      ],
       :v201705 => [
           :AccountLabelService,
           :AdCustomizerFeedService,
@@ -244,7 +198,6 @@ module AdwordsApi
     @@config = {
       :oauth_scope => 'https://www.googleapis.com/auth/adwords',
       :header_ns => 'https://adwords.google.com/api/adwords/cm/',
-      :v201702 => 'https://adwords.google.com/api/adwords/',
       :v201705 => 'https://adwords.google.com/api/adwords/',
       :v201708 => 'https://adwords.google.com/api/adwords/',
       :v201710 => 'https://adwords.google.com/api/adwords/'
@@ -253,51 +206,6 @@ module AdwordsApi
     # Configure the subdirectories for each version / service pair.
     # A missing pair means that only the base URL is used.
     @@subdir_config = {
-      # v201702
-      [:v201702, :AccountLabelService] => 'mcm/',
-      [:v201702, :AdCustomizerFeedService] => 'cm/',
-      [:v201702, :AdGroupAdService] => 'cm/',
-      [:v201702, :AdGroupBidModifierService] => 'cm/',
-      [:v201702, :AdGroupCriterionService] => 'cm/',
-      [:v201702, :AdGroupExtensionSettingService] => 'cm/',
-      [:v201702, :AdGroupFeedService] => 'cm/',
-      [:v201702, :AdGroupService] => 'cm/',
-      [:v201702, :AdParamService] => 'cm/',
-      [:v201702, :BatchJobService] => 'cm/',
-      [:v201702, :BudgetOrderService] => 'billing/',
-      [:v201702, :CampaignCriterionService] => 'cm/',
-      [:v201702, :CampaignExtensionSettingService] => 'cm/',
-      [:v201702, :CampaignFeedService] => 'cm/',
-      [:v201702, :CampaignService] => 'cm/',
-      [:v201702, :CampaignSharedSetService] => 'cm/',
-      [:v201702, :ConstantDataService] => 'cm/',
-      [:v201702, :ConversionTrackerService] => 'cm/',
-      [:v201702, :CustomerExtensionSettingService] => 'cm/',
-      [:v201702, :CustomerSyncService] => 'ch/',
-      [:v201702, :DataService] => 'cm/',
-      [:v201702, :FeedItemService] => 'cm/',
-      [:v201702, :FeedMappingService] => 'cm/',
-      [:v201702, :FeedService] => 'cm/',
-      [:v201702, :LocationCriterionService] => 'cm/',
-      [:v201702, :MediaService] => 'cm/',
-      [:v201702, :OfflineCallConversionFeedService] => 'cm/',
-      [:v201702, :OfflineConversionFeedService] => 'cm/',
-      [:v201702, :ReportDefinitionService] => 'cm/',
-      [:v201702, :SharedCriterionService] => 'cm/',
-      [:v201702, :SharedSetService] => 'cm/',
-      [:v201702, :TargetingIdeaService] => 'o/',
-      [:v201702, :TrafficEstimatorService] => 'o/',
-      [:v201702, :ManagedCustomerService] => 'mcm/',
-      [:v201702, :CustomerService] => 'mcm/',
-      [:v201702, :CustomerFeedService] => 'cm/',
-      [:v201702, :BudgetService] => 'cm/',
-      [:v201702, :BiddingStrategyService] => 'cm/',
-      [:v201702, :AdwordsUserListService] => 'rm/',
-      [:v201702, :LabelService] => 'cm/',
-      [:v201702, :DraftService] => 'cm/',
-      [:v201702, :DraftAsyncErrorService] => 'cm/',
-      [:v201702, :TrialService] => 'cm/',
-      [:v201702, :TrialAsyncErrorService] => 'cm/',
       # v201705
       [:v201705, :AccountLabelService] => 'mcm/',
       [:v201705, :AdCustomizerFeedService] => 'cm/',

data/lib/adwords_api/query_utils/query_builder.rb

@@ -0,0 +1,41 @@
+# Encoding: utf-8
+#
+# Copyright:: Copyright 2018, 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.
+#
+# Base class with common methods used across both report and service queries.
+
+require 'adwords_api/query_utils/where_builder'
+
+module AdwordsApi
+  class QueryBuilder
+    def initialize(api)
+      @api = api
+      @where = []
+    end
+
+    def where(field)
+      clause = WhereBuilder.new(field)
+      @where << clause
+      return clause
+    end
+
+    def build_where()
+      return '' if @where.empty?
+      wheres = @where.map {|w| w.awql}
+      return sprintf(' WHERE %s', wheres.join(' AND '))
+    end
+  end
+end

data/lib/adwords_api/query_utils/report_query.rb

@@ -0,0 +1,30 @@
+# Encoding: utf-8
+#
+# Copyright:: Copyright 2018, 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.
+#
+# Class to hold a generated AWQL query for reports.
+
+module AdwordsApi
+  class ReportQuery
+    def initialize(query)
+      @query = query
+    end
+
+    def to_s()
+      return @query
+    end
+  end
+end

data/lib/adwords_api/query_utils/report_query_builder.rb

@@ -0,0 +1,82 @@
+# Encoding: utf-8
+#
+# Copyright:: Copyright 2018, 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.
+#
+# Class with methods to aid in building AWQL for reports.
+
+require 'adwords_api/query_utils/query_builder'
+require 'adwords_api/query_utils/report_query'
+
+module AdwordsApi
+  class ReportQueryBuilder < QueryBuilder
+    def initialize(api)
+      super(api)
+      @select = nil
+      @from = nil
+      @during_range = nil
+      @during_start = nil
+      @during_end = nil
+      yield self if block_given?
+    end
+
+    def configure()
+      yield self
+    end
+
+    def select(*fields)
+      @select = fields
+    end
+
+    def from(report_name)
+      @from = report_name
+    end
+
+    def during_date_range(date_range)
+      @during_range = date_range
+    end
+
+    def during(start_date, end_date)
+      @during_start = start_date
+      @during_end = end_date
+    end
+
+    def build()
+      raise ArgumentError,
+          'Must specify SELECT clause for valid AWQL' if @select.nil?
+      raise ArgumentError,
+          'Must specify FROM clause for valid AWQL' if @from.nil?
+      if !@during_range.nil? && (!@during_start.nil? || !@during_end.nil?)
+        raise ArgumentError,
+            'Cannot specify both date range and start/end dates.'
+      end
+      result = sprintf('SELECT %s', @select.join(', '))
+      result += sprintf(' FROM %s', @from)
+      result += build_where()
+      if !@during_range.nil?
+        result += sprintf(' DURING %s', @during_range)
+      elsif !@during_start.nil? || !@during_end.nil?
+        if @during_start.nil?
+          raise ArgumentError, 'Cannot specify end date without start date.'
+        elsif @during_end.nil?
+          raise ArgumentError, 'Cannot specify start date without end date.'
+        end
+        result += sprintf(' DURING %s,%s', @during_start, @during_end)
+      end
+      @api.utils_reporter.report_query_builder_used()
+      return ReportQuery.new(result)
+    end
+  end
+end

data/lib/adwords_api/query_utils/service_query.rb

@@ -0,0 +1,61 @@
+# Encoding: utf-8
+#
+# Copyright:: Copyright 2018, 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.
+#
+# Class to hold a generated AWQL query and aid in paging for services.
+
+module AdwordsApi
+  class ServiceQuery
+    def initialize(query, start_index, page_size)
+      @query = query
+      @start_index = start_index
+      @page_size = page_size
+    end
+
+    def has_next(page)
+      raise ArgumentError,
+          'Cannot page through query with no LIMIT clause.' if @start_index.nil?
+      return @start_index + @page_size < page[:total_num_entries]
+    end
+
+    # Determining whether another page exists when dealing with bid landscapes
+    # is different from other types of queries. Use this method for those cases.
+    def has_next_landscape_page(page)
+      raise ArgumentError,
+          'Cannot page through query with no LIMIT clause.' if @start_index.nil?
+      total_landscape_points_in_page = 0
+      page[:entries].each do |landscape|
+        total_landscape_points_in_page += landscape[:landscape_points].size
+      end
+      return total_landscape_points_in_page >= @page_size
+    end
+
+    def next_page()
+      raise ArgumentError,
+          'Cannot page through query with no LIMIT clause.' if @start_index.nil?
+      @start_index += @page_size
+      return self
+    end
+
+    def to_s()
+      query = @query
+      unless @start_index.nil?
+        query += sprintf(' LIMIT %s,%s', @start_index, @page_size)
+      end
+      return query
+    end
+  end
+end

data/lib/adwords_api/query_utils/service_query_builder.rb

@@ -0,0 +1,83 @@
+# Encoding: utf-8
+#
+# Copyright:: Copyright 2018, 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.
+#
+# Class with methods to aid in building AWQL for services.
+
+require 'adwords_api/query_utils/query_builder'
+require 'adwords_api/query_utils/service_query'
+require 'set'
+
+module AdwordsApi
+  class ServiceQueryBuilder < QueryBuilder
+    def initialize(api)
+      super(api)
+      @select = nil
+      @order = []
+      @start_index = nil
+      @page_size = nil
+      yield self if block_given?
+    end
+
+    def configure()
+      yield self
+    end
+
+    def select(*fields)
+      @select = Set[*fields]
+    end
+
+    def order_by_asc(field)
+      @order << {
+        :field => field,
+        :direction => 'ASC'
+      }
+    end
+
+    def order_by_desc(field)
+      @order << {
+        :field => field,
+        :direction => 'DESC'
+      }
+    end
+
+    def limit(start_index, page_size)
+      @start_index = start_index
+      @page_size = page_size
+    end
+
+    def build()
+      raise ArgumentError,
+          'Must specify SELECT clause for valid AWQL' if @select.nil?
+      if !@start_index.nil? && @page_size.nil?
+        raise ArgumentError, 'Cannot specify start index without page size.'
+      end
+      if !@page_size.nil? && @start_index.nil?
+        raise ArgumentError, 'Cannot specify page size without start index.'
+      end
+      result = sprintf('SELECT %s', @select.to_a.join(', '))
+      result += build_where()
+      unless @order.empty?
+        orders = @order.map do |o|
+          sprintf('%s %s', o[:field], o[:direction])
+        end
+        result += sprintf(' ORDER BY %s', orders.join(', '))
+      end
+      @api.utils_reporter.service_query_builder_used()
+      return ServiceQuery.new(result, @start_index, @page_size)
+    end
+  end
+end