Add support for Google Ads API v0_5. (#12)

ChangeLog

@@ -1,3 +1,6 @@
+0.6.0:
+  - Adding support for Google Ads API v0_5.
+
 0.5.0:
   - Adding support for Google Ads API v0_4.
   - The namespace Googleads, with the path pattern "googleads", has changed to

examples/billing/get_account_budgets.rb

@@ -0,0 +1,166 @@
+#!/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 retrieves all account budgets for a Google Ads customer.
+
+require 'optparse'
+require 'google/ads/google_ads'
+
+def get_account_budgets(customer_id)
+  # GoogleAdsClient will read a config file from
+  # ENV['HOME']/google_ads_config.rb when called without parameters
+  client = Google::Ads::GoogleAds::GoogleAdsClient.new
+
+  ga_service = client.service(:GoogleAds)
+
+  search_query = <<~QUERY
+    SELECT
+      account_budget.status,
+      account_budget.billing_setup,
+      account_budget.approved_spending_limit_micros,
+      account_budget.approved_spending_limit_type,
+      account_budget.proposed_spending_limit_micros,
+      account_budget.proposed_spending_limit_type,
+      account_budget.approved_start_date_time,
+      account_budget.proposed_start_date_time,
+      account_budget.approved_end_date_time,
+      account_budget.approved_end_time_type,
+      account_budget.proposed_end_date_time,
+      account_budget.proposed_end_time_type
+    FROM account_budget
+  QUERY
+
+  response = ga_service.search(
+    customer_id,
+    search_query,
+    page_size: PAGE_SIZE
+  )
+
+  # Iterates over all rows in all pages and prints the requested field values
+  # for the account budget in each row.
+  response.each do |row|
+    account_budget = row.account_budget
+
+    total_adjustments_micros = 0
+    unless account_budget.total_adjustments_micros.nil?
+      total_adjustments_micros =
+          account_budget.total_adjustments_micros.value / 1_000_000.0
+    end
+
+    amount_served_micros = 0
+    unless account_budget.amount_served_micros.nil?
+      amount_served_micros =
+          account_budget.amount_served_micros.value / 1_000_000.0
+    end
+
+    approved_spending_limit_micros = account_budget.approved_spending_limit_type
+    unless account_budget.approved_spending_limit_micros.nil?
+      approved_spending_limit_micros =
+          account_budget.approved_spending_limit_micros.value / 1_000_000.0
+    end
+
+    proposed_spending_limit_micros = account_budget.proposed_spending_limit_type
+    unless account_budget.proposed_spending_limit_micros.nil?
+      proposed_spending_limit_micros =
+          account_budget.proposed_spending_limit_micros.value / 1_000_000.0
+    end
+
+    approved_end_date_time = account_budget.approved_end_time_type
+    unless account_budget.approved_end_date_time.nil?
+      approved_end_date_time = account_budget.approved_end_date_time
+    end
+
+    proposed_end_date_time = account_budget.proposed_end_time_type
+    unless account_budget.proposed_end_date_time.nil?
+      proposed_end_date_time = account_budget.proposed_end_date_time
+    end
+
+    puts sprintf('Account budget "%s" with status "%s", billing_setup "%s", '\
+        'amount served %.2f, total adjustments %.2f, '\
+        'approved spending limit "%s" (proposed "%s"), '\
+        'approved start time "%s" (proposed "%s"), '\
+        'approved end time "%s" (proposed "%s")',
+        account_budget.resource_name,
+        account_budget.status,
+        account_budget.billing_setup,
+        amount_served_micros,
+        total_adjustments_micros,
+        approved_spending_limit_micros,
+        proposed_spending_limit_micros,
+        account_budget.approved_start_date_time,
+        account_budget.proposed_start_date_time,
+        approved_end_date_time,
+        proposed_end_date_time
+    )
+  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_account_budgets(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

examples/billing/get_billing_setup.rb

@@ -16,7 +16,7 @@
 # limitations under the License.
 #
 #
-# This example gets all BillingSetup objects available for the specified
+# This example retrieves all BillingSetup objects available for the specified
 # customerId.
 
 require 'optparse'
@@ -32,11 +32,12 @@ def get_billing_setup(customer_id)
   search_query = <<~QUERY
     SELECT billing_setup.id,
       billing_setup.status,
-      billing_setup.payments_account_id,
-      billing_setup.payments_account_name,
-      billing_setup.payments_profile_id,
-      billing_setup.payments_profile_name,
-      billing_setup.secondary_payments_profile_id
+      billing_setup.payments_account,
+      billing_setup.payments_account_info.payments_account_id,
+      billing_setup.payments_account_info.payments_account_name,
+      billing_setup.payments_account_info.payments_profile_id,
+      billing_setup.payments_account_info.payments_profile_name,
+      billing_setup.payments_account_info.secondary_payments_profile_id
     FROM billing_setup
   QUERY
 
@@ -48,17 +49,20 @@ def get_billing_setup(customer_id)
 
   response.each do |row|
     billing_setup = row.billing_setup
+    payments_account_info = billing_setup.payments_account_info
 
-    puts sprintf('Billing setup with ID %s, status %s, payments_account_id %s,'\
-        ' payments_account_name %s, payments_profile_id %s,'\
-        ' payments_profile_name %s, secondary_payments_profile_id %s',
+    puts sprintf('Billing setup with ID "%s", status "%s",'\
+        ' payments_account "%s", payments_account_id "%s",'\
+        ' payments_account_name "%s", payments_profile_id "%s",'\
+        ' payments_profile_name "%s", secondary_payments_profile_id "%s"',
         billing_setup.id,
         billing_setup.status,
-        billing_setup.payments_account_id,
-        billing_setup.payments_account_name,
-        billing_setup.payments_profile_id,
-        billing_setup.payments_profile_name,
-        billing_setup.secondary_payments_profile_id
+        billing_setup.payments_account,
+        payments_account_info.payments_account_id,
+        payments_account_info.payments_account_name,
+        payments_account_info.payments_profile_id,
+        payments_account_info.payments_profile_name,
+        payments_account_info.secondary_payments_profile_id
     )
   end
 end

examples/targeting/add_campaign_targeting_criteria.rb

@@ -20,14 +20,67 @@
 require 'optparse'
 require 'google/ads/google_ads'
 
-def add_campaign_targeting_criteria(customer_id, campaign_id, keyword)
+def add_campaign_targeting_criteria(
+    customer_id, campaign_id, keyword, location_id)
   # GoogleAdsClient will read a config file from
   # ENV['HOME']/google_ads_config.rb when called without parameters
   client = Google::Ads::GoogleAds::GoogleAdsClient.new
 
   criteria_service = client.service(:CampaignCriterion)
-  campaign_service = client.service(:Campaign)
 
+  negative_keyword = create_negative_keyword(client, customer_id,
+      campaign_id, keyword)
+  location = create_location(client, customer_id, campaign_id, location_id)
+  proximity = create_proximity(client, customer_id, campaign_id)
+
+  operations = [
+    {create: negative_keyword},
+    {create: location},
+    {create: proximity}
+  ]
+
+  response = criteria_service.mutate_campaign_criteria(customer_id, operations)
+  response.results.each do |resource|
+    puts sprintf("Added campaign criterion %s", resource.resource_name)
+  end
+end
+
+def create_proximity(client, customer_id, campaign_id)
+  criterion = client.resource(:CampaignCriterion)
+  criterion.campaign = client.wrapper.string(
+      client.path.campaign(customer_id, campaign_id))
+
+  criterion.proximity = client.resource(:ProximityInfo)
+  criterion.proximity.address = client.resource(:AddressInfo)
+  criterion.proximity.address.street_address =
+      client.wrapper.string("38 avenue de l'Opéra")
+  criterion.proximity.address.city_name = client.wrapper.string("Paris")
+  criterion.proximity.address.postal_code = client.wrapper.string("75002")
+  criterion.proximity.address.country_code = client.wrapper.string("FR")
+  criterion.proximity.radius = client.wrapper.double(10)
+  # Default is kilometers.
+  criterion.proximity.radius_units = client.enum(:ProximityRadiusUnits)::MILES
+
+  return criterion
+end
+
+def create_location(client, customer_id, campaign_id, location_id)
+  criterion = client.resource(:CampaignCriterion)
+  criterion.campaign = client.wrapper.string(
+      client.path.campaign(customer_id, campaign_id))
+
+  criterion.location = client.resource(:LocationInfo)
+  # Besides using location_id, you can also search by location names from
+  # GeoTargetConstantService.suggest_geo_target_constants() and directly
+  # apply GeoTargetConstant.resource_name here. An example can be found
+  # in get_geo_target_constant_by_names.rb.
+  criterion.location.geo_target_constant = client.wrapper.string(
+      client.path.geo_target_constant(location_id))
+
+  return criterion
+end
+
+def create_negative_keyword(client, customer_id, campaign_id, keyword)
   criterion = client.resource(:CampaignCriterion)
   criterion.campaign = client.wrapper.string(
       client.path.campaign(customer_id, campaign_id))
@@ -36,11 +89,7 @@ def add_campaign_targeting_criteria(customer_id, campaign_id, keyword)
   criterion.keyword.text = client.wrapper.string(keyword)
   criterion.keyword.match_type = client.enum(:KeywordMatchType)::BROAD
 
-  operation = {create: criterion}
-  response = criteria_service.mutate_campaign_criteria(customer_id, [operation])
-
-  puts sprintf("Added campaign criterion %s",
-      response.results.first.resource_name)
+  return criterion
 end
 
 if __FILE__ == $PROGRAM_NAME
@@ -57,6 +106,9 @@ def add_campaign_targeting_criteria(customer_id, campaign_id, keyword)
   options[:customer_id] = 'INSERT_ADWORDS_CUSTOMER_ID_HERE'
   options[:campaign_id] = 'INSERT_CAMPAIGN_ID_HERE'
   options[:keyword] = 'jupiter cruise'
+  # For more information on determining location_id value, see:
+  # https://developers.google.com/adwords/api/docs/appendix/geotargeting.
+  options[:location_id] = '21167' # New York
 
   OptionParser.new do |opts|
     opts.banner = sprintf('Usage: ruby %s [options]', File.basename(__FILE__))
@@ -76,6 +128,10 @@ def add_campaign_targeting_criteria(customer_id, campaign_id, keyword)
       options[:keyword] = v
     end
 
+    opts.on('-l', '--location-id LOCATION-ID', String, '(Optional) Location ID') do |v|
+      options[:location_id] = v
+    end
+
     opts.separator ''
     opts.separator 'Help:'
 
@@ -87,7 +143,7 @@ def add_campaign_targeting_criteria(customer_id, campaign_id, keyword)
 
   begin
     add_campaign_targeting_criteria(options[:customer_id],
-        options[:campaign_id], options[:keyword])
+        options[:campaign_id], options[:keyword], options[:location_id])
     rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
       e.failure.errors.each do |error|
         STDERR.printf("Error with message: %s\n", error.message)