Release v0_1 (#3)

Adding support for Google Ads API v0_1.

ChangeLog

@@ -1,2 +1,5 @@
+0.2.0:
+  - Adding support for Google Ads API v0_1.
+
 0.1.0:
-  - Initial release with support for Google Ads API V0.
+  - Initial release with support for Google Ads API v0.

examples/recommendations/apply_recommendation.rb

@@ -0,0 +1,119 @@
+#!/usr/bin/env ruby
+# Encoding: utf-8
+#
+# Copyright 2018 Google LLC
+#
+# 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
+#
+#     https://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.
+#
+# This example applies a given recommendation. To retrieve recommendations for
+# text ads, run get_text_ad_recommendations.rb.
+
+require 'optparse'
+require 'google/ads/googleads'
+
+def apply_recommendation(customer_id, recommendation_id)
+  # GoogleadsClient will read a config file from ENV['HOME']/googleads_config.rb
+  # when called without parameters
+  client = Google::Ads::Googleads::GoogleadsClient.new
+
+  recommendation_resource =
+      client.path.recommendation(customer_id, recommendation_id)
+  apply_recommendation_operation = client.operation(:ApplyRecommendation)
+  apply_recommendation_operation.resource_name = recommendation_resource
+
+  # Each recommendation type has optional parameters to override the recommended
+  # values. This is an example to override a recommended ad when a
+  # TextAdRecommendation is applied.
+  # For details, please read
+  # https://developers.google.com/google-ads/api/reference/rpc/google.ads.googleads.v0.services#google.ads.googleads.v0.services.ApplyRecommendationOperation
+  #
+  # overriding_ad = client.resource(:Ad)
+  # overriding_ad.id = client.wrapper.int64('INSERT_AD_ID_AS_INTEGER_HERE')
+  # text_ad_parameters = client.resource(:TextAdParameters)
+  # text_ad_parameters.ad = overriding_ad
+  # apply_recommendation_operation.text_ad = text_ad_parameters
+
+  # Issues a mutate request to apply the recommendation.
+  recommendation_service = client.service(:Recommendation)
+  response = recommendation_service.apply_recommendation(customer_id,
+      [apply_recommendation_operation])
+  applied_recommendation = response.results.first
+
+  puts sprintf('Applied recommendation with resource name: "%s".',
+      applied_recommendation.resource_name)
+end
+
+if __FILE__ == $0
+  PAGE_SIZE = 1000
+
+  options = {}
+  # The following parameter(s) should be provided to run the example. You can
+  # either specify these by changing the INSERT_XXX_ID_HERE values below, or on
+  # the command line.
+  #
+  # Parameters passed on the command line will override any parameters set in
+  # code.
+  #
+  # Running the example with -h will print the command line usage.
+  options[:customer_id] = 'INSERT_CUSTOMER_ID_HERE'
+  # Recommendation ID is the last alphanumeric portion of the value from the
+  # resource_name field of a Recommendation, which has the format of
+  # customers/<customer_id>/recommendations/<recommendation_id>.
+  # Its example can be retrieved from get_text_ad_recommendations.rb.
+  options[:recommendation_id] = 'INSERT_RECOMMENDATION_ID_HERE'
+
+  OptionParser.new do |opts|
+    opts.banner = sprintf('Usage: %s [options]', File.basename(__FILE__))
+
+    opts.separator ''
+    opts.separator 'Options:'
+
+    opts.on('-C', '--customer-id CUSTOMER-ID', String, 'Customer ID') do |v|
+      options[:customer_id] = v
+    end
+
+    opts.on('-r', '--recommendation-id RECOMMENDATION-ID', String,
+        'Recommendation ID') do |v|
+      options[:recommendation_id] = v
+    end
+
+    opts.separator ''
+    opts.separator 'Help:'
+
+    opts.on_tail('-h', '--help', 'Show this message') do
+      puts opts
+      exit
+    end
+  end.parse!
+
+  begin
+    apply_recommendation(options[:customer_id], options[:recommendation_id])
+  rescue Google::Ads::Googleads::Errors::GoogleAdsError => e
+    e.failure.errors.each do |error|
+      STDERR.printf("Error with message: %s\n", error.message)
+      if error.location
+        error.location.field_path_elements.each do |field_path_element|
+          STDERR.printf("\tOn field: %s\n", field_path_element.field_name)
+        end
+      end
+      error.error_code.to_h.each do |k, v|
+        next if v == :UNSPECIFIED
+        STDERR.printf("\tType: %s\n\tCode: %s\n", k, v)
+      end
+    end
+  rescue Google::Gax::RetryError => e
+    STDERR.printf("Error: '%s'\n\tCause: '%s'\n\tCode: %d\n\tDetails: '%s'\n" \
+        "\tRequest-Id: '%s'\n", e.message, e.cause.message, e.cause.code,
+                  e.cause.details, e.cause.metadata['request-id'])
+  end
+end

examples/recommendations/get_text_ad_recommendations.rb

@@ -0,0 +1,116 @@
+#!/usr/bin/env ruby
+# Encoding: utf-8
+#
+# Copyright 2018 Google LLC
+#
+# 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
+#
+#     https://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.
+#
+# This example gets all TEXT_AD recommendations.
+
+require 'optparse'
+require 'google/ads/googleads'
+
+def get_text_ad_recommendations(customer_id)
+  # GoogleadsClient will read a config file from ENV['HOME']/googleads_config.rb
+  # when called without parameters
+  client = Google::Ads::Googleads::GoogleadsClient.new
+
+  ga_service = client.service(:GoogleAds)
+
+  query = <<~QUERY
+    SELECT recommendation.type, recommendation.campaign,
+        recommendation.text_ad_recommendation
+    FROM recommendation
+    WHERE recommendation.type = TEXT_AD
+  QUERY
+
+  response = ga_service.search(customer_id, query, page_size: PAGE_SIZE)
+
+  response.each do |row|
+    recommendation = row.recommendation
+    recommended_ad = recommendation.text_ad_recommendation.ad
+
+    puts sprintf('Recommendation ("%s") was found for campaign "%s".',
+        recommendation.resource_name, recommendation.campaign)
+    if recommended_ad.expanded_text_ad
+      eta = recommended_ad.expanded_text_ad
+      puts sprintf("\tHeadline 1 = '%s'\n\tHeadline2 = '%s'\n" +
+          "\tDescription = '%s'", eta.headline_part1, eta.headline_part2,
+          eta.description)
+    end
+    if recommended_ad.display_url
+      puts sprintf("\tDisplay URL = '%s'", recommended_ad.display_url)
+    end
+    recommended_ad.final_urls.each do |url|
+      puts sprintf("\tFinal Url = '%s'", url)
+    end
+    recommended_ad.final_mobile_urls.each do |url|
+      puts sprintf("\tFinal Mobile Url = '%s'", url)
+    end
+  end
+end
+
+if __FILE__ == $0
+  PAGE_SIZE = 1000
+
+  options = {}
+  # The following parameter(s) should be provided to run the example. You can
+  # either specify these by changing the INSERT_XXX_ID_HERE values below, or on
+  # the command line.
+  #
+  # Parameters passed on the command line will override any parameters set in
+  # code.
+  #
+  # Running the example with -h will print the command line usage.
+  options[:customer_id] = 'INSERT_CUSTOMER_ID_HERE'
+
+  OptionParser.new do |opts|
+    opts.banner = sprintf('Usage: %s [options]', File.basename(__FILE__))
+
+    opts.separator ''
+    opts.separator 'Options:'
+
+    opts.on('-C', '--customer-id CUSTOMER-ID', String, 'Customer ID') do |v|
+      options[:customer_id] = v
+    end
+
+    opts.separator ''
+    opts.separator 'Help:'
+
+    opts.on_tail('-h', '--help', 'Show this message') do
+      puts opts
+      exit
+    end
+  end.parse!
+
+  begin
+    get_text_ad_recommendations(options[:customer_id])
+  rescue Google::Ads::Googleads::Errors::GoogleAdsError => e
+    e.failure.errors.each do |error|
+      STDERR.printf("Error with message: %s\n", error.message)
+      if error.location
+        error.location.field_path_elements.each do |field_path_element|
+          STDERR.printf("\tOn field: %s\n", field_path_element.field_name)
+        end
+      end
+      error.error_code.to_h.each do |k, v|
+        next if v == :UNSPECIFIED
+        STDERR.printf("\tType: %s\n\tCode: %s\n", k, v)
+      end
+    end
+  rescue Google::Gax::RetryError => e
+    STDERR.printf("Error: '%s'\n\tCause: '%s'\n\tCode: %d\n\tDetails: '%s'\n" \
+        "\tRequest-Id: '%s'\n", e.message, e.cause.message, e.cause.code,
+                  e.cause.details, e.cause.metadata['request-id'])
+  end
+end

lib/google/ads/googleads/v0/services/credentials.rb → lib/google/ads/googleads/credentials.rb

@@ -17,16 +17,12 @@
 module Google
   module Ads
     module Googleads
-      module V0
-        module Services
-          class Credentials < Google::Auth::Credentials
-            SCOPE = [
-            ].freeze
-            PATH_ENV_VARS = %w(GOOGLEADS_KEYFILE GOOGLE_CLOUD_KEYFILE GCLOUD_KEYFILE)
-            JSON_ENV_VARS = %w(GOOGLEADS_KEYFILE_JSON GOOGLE_CLOUD_KEYFILE_JSON GCLOUD_KEYFILE_JSON)
-            DEFAULT_PATHS = ["~/.config/gcloud/application_default_credentials.json"]
-          end
-        end
+      class Credentials < Google::Auth::Credentials
+        SCOPE = [
+        ].freeze
+        PATH_ENV_VARS = %w(GOOGLEADS_KEYFILE GOOGLE_CLOUD_KEYFILE GCLOUD_KEYFILE)
+        JSON_ENV_VARS = %w(GOOGLEADS_KEYFILE_JSON GOOGLE_CLOUD_KEYFILE_JSON GCLOUD_KEYFILE_JSON)
+        DEFAULT_PATHS = ["~/.config/gcloud/application_default_credentials.json"]
       end
     end
   end

lib/google/ads/googleads/path_lookup_util.rb

@@ -29,6 +29,14 @@ def ad_group_ad(customer_id, ad_group_id, ad_id)
               customer_id.to_s, sprintf('%s_%s', ad_group_id.to_s, ad_id.to_s))
         end
 
+        def ad_group_bid_modifier(customer_id, ad_group_id, criterion_id)
+          @proto_lookup_util.service(:AdGroupBidModifier).
+              ad_group_bid_modifier_path(
+                customer_id.to_s,
+                sprintf('%s_%s', ad_group_id.to_s, criterion_id.to_s)
+              )
+        end
+
         def ad_group_criterion(customer_id, ad_group_id, criterion_id)
           @proto_lookup_util.service(:AdGroupCriterion).ad_group_criteria_path(
             customer_id.to_s,
@@ -67,6 +75,11 @@ def customer(customer_id)
           @proto_lookup_util.service(:Customer).customer_path(customer_id.to_s)
         end
 
+        def geo_target_constant(geo_target_constant_id)
+          @proto_lookup_util.service(:GeoTargetConstant).
+              geo_target_constant_path(geo_target_constant_id.to_s)
+        end
+
         def google_ads_field(google_ads_field)
           @proto_lookup_util.service(:GoogleAdsField).google_ads_field_path(
               google_ads_field.to_s)
@@ -78,6 +91,11 @@ def keyword_view(customer_id, ad_group_id, criterion_id)
             sprintf('%s_%s', ad_group_id.to_s, criterion_id.to_s)
           )
         end
+
+        def recommendation(customer_id, recommendation_id)
+          @proto_lookup_util.service(:Recommendation).recommendation_path(
+            customer_id.to_s, recommendation_id.to_s)
+        end
       end
     end
   end