google-ads-googleads 1.1.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d909d1d6d9386d5ce00534af05b6ce762f3f981a4242aa501f3a884ed8f82695
-  data.tar.gz: 88cef4570b6123d494d04d13ac64c42abc540e87fbf1426186982480c29f8109
+  metadata.gz: 62470f63d1da981ede9c67986dbd4b2fc78efcf236bc0540a1f673a12b52c224
+  data.tar.gz: 4a46da47d63f825e98030c88b51b3513393311ff3a1050eac62f0d86680b1cb6
 SHA512:
-  metadata.gz: f13b5d6f77f0bb1a9aa061365e9459507a3990301e7d25b5cce1b3ff945b4335c2bbc1f53465aa821b7281e08bac00f987d61d451d120500baf0cfe8f8f92246
-  data.tar.gz: 73d88a624bfdb3ec1dad7772057c8ac9418cea5459e0ed13786f7bee964f3c94823145fe39931f7350e952eb128b2e7a42cfb014bfad66c58f6f3420888e56d6
+  metadata.gz: 75580c687c4c05c0a8e4de4feb771ab8b365e07f3cf355ffa3fdf7c4a9d6bdea14763a041c3a85aacb5d467f0b5ce249aa114af1e7768aa5764bf11a00466e95
+  data.tar.gz: ba392c6f51965d2a2ee97addde1be08348461be66ddede838abb1909a11d0a8e118463d7a8f0475ccbadc69669b02a7f0200036ca9acf6e3faa597e314c2f528

data/ChangeLog

@@ -1,3 +1,7 @@
+2.0.0:
+  - Adding support for Google Ads API v1_2.
+  - Removing support for Google Ads API v0.
+
 1.1.1:
   - Add `ExtensionFeedItem` as an operation look up
   - Fixes various broken resource types

data/README.md

@@ -8,58 +8,77 @@ easy-to-use client library for the [Google Ads API][].
 
 # Documentation for Users
 
+**For thorough documentation of all features and utilities, visit our
+[Developers site Ruby guide][].**
+
+[Developers site Ruby guide]: https://developers.google.com/google-ads/api/docs/client-libs/ruby/
+
 ## Getting started
 
 `google-ads-googleads` will allow you to connect to the
 [Google Ads API][] and access all its methods.
 
-In order to achieve so you need to set up authentication as well as install the
-library locally.
-
 ## Installation
 
-Install this library using gem:
+The recommended way to install is using [bundler][].
 
-    $ [sudo] gem install google-ads-googleads
+Add a line to your `Gemfile`:
 
-Alternatively, if you prefer not to or can't use the hosted gem on RubyGems, you
-can download the gem from the [Releases][] page and install it from the local
-file:
+    gem "google-ads-googleads", "~> x.y.z"
+
+Then run:
+
+    $ bundle install
+    
+This will cause bundler to update your `Gemfile.lock` locking to the exact
+version of the gem, and all dependencies of the gem that were installed.
+Using the pessimistic version operator `"~> x.y.z"` will cause `bundle
+update` to only install new versions in the `x.y.*` series, which will
+make it so you must manually opt into new versions.
+
+You can then update to a new version of the gem by updating the `Gemfile`.
 
-    $ [sudo] gem install google-ads-googleads-[version].gem
+### Other Installation Options
 
-Or you can build it yourself from the source. After cloning the GitHub repo,
-navigate to the `google-ads-ruby` folder and run:
+If you are not using bundler, you can use one of these options.
 
-    $ rake build
-    $ gem install pkg/google-ads-googleads-[version].gem
+1. Install this library using gem:
+
+       $ [sudo] gem install google-ads-googleads
+
+1. Download the gem from the [Releases][] page and install it from the local
+file:
+
+       $ [sudo] gem install google-ads-googleads-[version].gem
 
 [Releases]: https://github.com/googleads/google-ads-ruby/releases
+[bundler]: https://bundler.io/
 
 ## Set Up Authentication
 
 To authenticate your API calls, you need to specify your client ID, client
-secret, refresh token, and developer token to the library in one of a few ways.
+secret, refresh token, and developer token to the library.
 
-If you don't have a client ID or client secret yet, please see the
-[Authorization guide][] to get those set up. Once you have those, the Ruby
-library can help you use those to generate a refresh token.
+1. See the [Developer token guide][] to obtain your developer token, if you
+   don't already have one.
 
-See and run the [Authentication example][] to generate your refresh token.
-Once this is generated, you can provide it to the library in a few different
-ways.
+1. See the [Authorization guide][] to generate a client ID and client secret,
+   if you don't already have them.
 
-The simplest is to copy the [google_ads_config.rb][] to your home directory and
-simply modify it to include the client ID, client secret, and refresh token.
-The library will automatically read it from the home directory if instantiated
+1. Run the [Authentication example][] to generate your refresh token.
+
+1. Copy [google_ads_config.rb][] to your home directory and modify it to include
+the client ID, client secret, and refresh token.
+
+The client will automatically read it from the home directory if instantiated
 with no arguments:
 
     client = Google::Ads::GoogleAds::GoogleAdsClient.new
 
 Alternatively, if you prefer to keep the file elsewhere, you can instantiate the
-library by passing the path to where you keep this file:
+client by passing the path to where you keep this file:
 
-    client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/file.rb')
+    client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')
 
 If you prefer not to store this information in a file at all, and would rather
 pass the information programmatically at runtime, you can accomplish that this
@@ -72,12 +91,13 @@ way:
       config.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
     end
 
-You can also modify these properties after instantiation by using the
-`configure` method on the `GoogleAdsClient`, using the same structure as above.
+Find out more at the [Configuration guide][].
 
+[Developer token guide]: https://developers.google.com/google-ads/api/docs/first-call/dev-token
 [Authorization guide]: https://developers.google.com/google-ads/api/docs/oauth/overview
 [Authentication example]: https://github.com/googleads/google-ads-ruby/blob/master/examples/authentication/authenticate_in_standalone_application.rb
 [google_ads_config.rb]: https://github.com/googleads/google-ads-ruby/blob/master/google_ads_config.rb
+[Configuration guide]: https://developers.google.com/google-ads/api/docs/client-libs/ruby/configuration
 
 ## Usage
 
@@ -97,14 +117,9 @@ library.
 
 ## Logging
 
-See the instructions in
-[google_ads_config.rb](https://github.com/googleads/google-ads-ruby/blob/master/google_ads_config.rb)
-for complete setup.
-
-Logging is set up via the Config object, accessed via `client.config` or specified
-in your default config loaded when instantiating a `GoogleAdsClient`.
+See the [Logging guide][].
 
-You can also specify your own logger by setting `client.logger`.
+[Logging guide]: https://developers.google.com/google-ads/api/docs/client-libs/ruby/logging
 
 # Authors
 

data/lib/google/ads/google_ads.rb

@@ -15,14 +15,14 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 
-require 'google/ads/google_ads/google_ads_client'
 require 'google/ads/google_ads/api_versions'
+require 'google/ads/google_ads/google_ads_client'
 
 module Google
   module Ads
     module GoogleAds
       def self.valid_version?(version)
-        KNOWN_API_VERSIONS.include?(version)
+        known_api_versions.include?(version)
       end
     end
   end

data/lib/google/ads/google_ads/api_versions.rb

@@ -1,8 +1,16 @@
 module Google
   module Ads
     module GoogleAds
-      KNOWN_API_VERSIONS = [:V0, :V1]
+      KNOWN_API_VERSIONS = [:V1]
       DEFAULT_API_VERSION = :V1
+
+      def self.default_api_version
+        DEFAULT_API_VERSION
+      end
+
+      def self.known_api_versions
+        KNOWN_API_VERSIONS
+      end
     end
   end
 end

data/lib/google/ads/google_ads/errors.rb

@@ -34,6 +34,65 @@ module Google
             @failure = failure
           end
         end
+
+        def self.namespaces
+          ERROR_NAMESPACES.values
+        end
+
+        # takes a Google::Ads::GoogleAds::VX::Errors::GoogleAdsError error
+        # and extracts its index in the list of mutations
+        #
+        # Return nil if not found
+        # Return Integer: index of the error
+        def self.index(error)
+          path = error.location.field_path_elements.find {|elt| elt.field_name == OPERATIONS }
+          if path
+            path.index.value
+          else
+            nil
+          end
+        end
+
+        # takes a Google::Ads::GoogleAds::VX::Errors::GoogleAdsError error
+        # and extracts a full error message based on the message and the different paths
+        # describing the source of the error
+        #
+        # Returns a string describing the error
+        def self.message(error)
+          error.location.field_path_elements.inject(error.message) do |string, path|
+            unless MEANINGLESS_PATHS.include?(path.field_name)
+              string = "#{path.field_name} - #{string}"
+            end
+            string
+          end
+        end
+
+        # takes a Google::Ads::GoogleAds::VX::Errors::GoogleAdsError error
+        # and extracts error code in the form of a hash
+        #
+        # Returns a Hash { name:, value:}
+        def self.code(error, version = Google::Ads::GoogleAds.default_api_version)
+          mapping = ERROR_CODES_MAPPING.fetch(version)
+          match = mapping.find do |error_name|
+            error.error_code.send(error_name) != :UNSPECIFIED
+          end
+          if match
+            { name: match, value: error.error_code.send(match) }
+          else
+            {  }
+          end
+        end
+
+        ERROR_NAMESPACES = Google::Ads::GoogleAds.known_api_versions.each_with_object({}) do |v, h|
+          require "google/ads/google_ads/#{v.downcase}/errors/errors_pb"
+          h[v] = const_get("Google::Ads::GoogleAds::#{v}::Errors")
+        end
+
+        ERROR_CODES_MAPPING = ERROR_NAMESPACES.each_with_object({}) do |(version, klass), hash|
+          hash[version] = klass.const_get(:ErrorCode).descriptor.lookup_oneof('error_code').map(&:name)
+        end
+        MEANINGLESS_PATHS = %w(operations create update remove)
+        OPERATIONS = "operations"
       end
     end
   end

data/lib/google/ads/google_ads/google_ads_client.rb

@@ -22,18 +22,6 @@
 module Google
   module Ads
     module GoogleAds
-      module V0
-        module Common
-        end
-        module Enums
-        end
-        module Errors
-        end
-        module Resources
-        end
-        module Services
-        end
-      end
       module V1
         module Common
         end
@@ -60,7 +48,6 @@ require 'google/ads/google_ads/wrapper_util'
 require 'google/ads/google_ads/logging_interceptor'
 
 require 'google/ads/google_ads/errors'
-require 'google/ads/google_ads/v0/errors/errors_pb'
 
 require 'google/gax'
 
@@ -220,7 +207,7 @@ module Google
             gax_error.status_details.each do |detail|
               # If there is an underlying GoogleAdsFailure, throw that one.
               if detail.is_a?(
-                  Google::Ads::GoogleAds::V0::Errors::GoogleAdsFailure)
+                  Google::Ads::GoogleAds::V1::Errors::GoogleAdsFailure)
                 raise Google::Ads::GoogleAds::Errors::GoogleAdsError.new(
                     detail)
               end
@@ -272,7 +259,7 @@ module Google
         end
 
         def default_api_version
-          Google::Ads::GoogleAds::DEFAULT_API_VERSION
+          Google::Ads::GoogleAds.default_api_version
         end
       end
     end

data/lib/google/ads/google_ads/logging_interceptor.rb

@@ -25,10 +25,6 @@ module Google
   module Ads
     module GoogleAds
       class LoggingInterceptor < GRPC::ClientInterceptor
-        INTERESTING_ERROR_CLASSES = ::Google::Ads::GoogleAds::KNOWN_API_VERSIONS.map { |v|
-          require "google/ads/google_ads/#{v.downcase}/errors/errors_pb"
-          const_get("Google::Ads::GoogleAds::#{v}::Errors::GoogleAdsFailure")
-        }
 
         def initialize(logger)
           # Don't propagate args, parens are necessary
@@ -40,17 +36,17 @@ module Google
           begin
             response = yield
 
-            @logger.info(build_summary_message(request, call, method, false))
-            @logger.debug(build_request_message(metadata, request))
-            @logger.debug(build_success_response_message(response))
+            @logger.info { build_summary_message(request, call, method, false) }
+            @logger.debug { build_request_message(metadata, request) }
+            @logger.debug { build_success_response_message(response) }
             if response.respond_to?(:partial_failure_error) && response.partial_failure_error
-              @logger.debug(build_partial_failure_message(response))
+              @logger.debug { build_partial_failure_message(response) }
             end
             response
           rescue Exception
-            @logger.warn(build_summary_message(request, call, method, true))
-            @logger.info(build_request_message(metadata, request))
-            @logger.info(build_error_response_message)
+            @logger.warn { build_summary_message(request, call, method, true) }
+            @logger.info { build_request_message(metadata, request) }
+            @logger.info { build_error_response_message }
             raise
           end
         end
@@ -83,7 +79,7 @@ module Google
             most_recent_error.status_details
           when Array
             most_recent_error.status_details.select { |detail|
-              INTERESTING_ERROR_CLASSES.include?(detail.class)
+              interesting_error_classes.include?(detail.class)
             }.map { |detail|
               response_error_from_detail(detail)
             }.join("\n")
@@ -139,13 +135,38 @@ module Google
         end
 
         def use_bytes_inspect?(request)
+          @cycle_finder = CycleFinder.new
           contains_bytes_field?(request.class.descriptor)
         end
 
         def contains_bytes_field?(descriptor)
           return false if descriptor.nil?
+          return false if @cycle_finder.is_cycle?(descriptor)
+
+          @cycle_finder.add_object(descriptor)
+
           descriptor.map { |x| x.type == :bytes || (x.type == :message && contains_bytes_field?(x.subtype)) }.any?
         end
+
+        def interesting_error_classes
+          @interesting_error_classes ||= Google::Ads::GoogleAds::Errors.namespaces.map do |namespace|
+            namespace.const_get(:GoogleAdsFailure)
+          end
+        end
+
+        class CycleFinder
+          def initialize
+            @objects_seen = Set.new
+          end
+
+          def is_cycle?(object)
+            @objects_seen.include?(object.object_id)
+          end
+
+          def add_object(object)
+            @objects_seen.add(object.object_id)
+          end
+        end
       end
     end
   end

data/lib/google/ads/google_ads/utils/v1/path_lookup_util.rb

@@ -87,6 +87,23 @@ module Google
                   )
             end
 
+            def ad_group_criterion_simulation(customer_id, ad_group_id,
+                criterion_id, type, modification_method, start_date, end_date)
+              @proto_lookup_util.service(:AdGroupCriterionSimulation).
+                  ad_group_criterion_simulation_path(
+                    customer_id.to_s,
+                    sprintf(
+                      '%s~%s~%s~%s~%s~%s',
+                      ad_group_id.to_s,
+                      criterion_id.to_s,
+                      type.to_s,
+                      modification_method.to_s,
+                      start_date.to_s,
+                      end_date.to_s,
+                    )
+                  )
+            end
+
             def ad_group_extension_setting(customer_id, ad_group_id,
                 extension_type)
               @proto_lookup_util.service(:AdGroupExtensionSetting).
@@ -115,6 +132,22 @@ module Google
                   customer_id.to_s, ad_group_id.to_s)
             end
 
+            def ad_group_simulation(customer_id, ad_group_id, type,
+                modification_method, start_date, end_date)
+              @proto_lookup_util.service(:AdGroupSimulation).
+                ad_group_simulation_path(
+                  customer_id.to_s,
+                  sprintf(
+                    '%s~%s~%s~%s~%s',
+                    ad_group_id.to_s,
+                    type.to_s,
+                    modification_method.to_s,
+                    start_date.to_s,
+                    end_date.to_s,
+                  )
+              )
+            end
+
             def ad_parameter(customer_id, ad_group_id, criterion_id,
                 parameter_index)
               @proto_lookup_util.service(:AdParameter).ad_parameter_path(
@@ -184,6 +217,23 @@ module Google
                   )
             end
 
+            def campaign_criterion_simulation(customer_id, campaign_id, criterion_id,
+                type, modification_method, start_date, end_date)
+              @proto_lookup_util.service(:CampaignCriterionSimulation).
+                campaign_criterion_simulation_path(
+                  customer_id.to_s,
+                  sprintf(
+                    '%s~%s~%s~%s~%s~%s',
+                    campaign_id.to_s,
+                    criterion_id.to_s,
+                    type.to_s,
+                    modification_method.to_s,
+                    start_date.to_s,
+                    end_date.to_s,
+                  )
+              )
+            end
+
             def campaign_extension_setting(customer_id, campaign_id,
                 extension_type)
               @proto_lookup_util.service(:CampaignExtensionSetting).
@@ -207,10 +257,12 @@ module Google
               )
             end
 
-            def campaign_shared_set(customer_id, campaign_shared_set_id)
+            def campaign_shared_set(customer_id, campaign_id, shared_set_id)
               @proto_lookup_util.service(:CampaignSharedSet).
-                  campaign_shared_set_path(customer_id.to_s,
-                      campaign_shared_set_id.to_s)
+                  campaign_shared_set_path(
+                    customer_id.to_s,
+                    sprintf('%s~%s', campaign_id.to_s, shared_set_id.to_s)
+                  )
             end
 
             def campaign(customer_id, campaign_id)
@@ -349,6 +401,14 @@ module Google
                   )
             end
 
+            def expanded_landing_page_view(customer_id, expanded_final_url_fingerprint)
+              @proto_lookup_util.service(:ExpandedLandingPageView).
+                expanded_landing_page_view_path(
+                  customer_id.to_s,
+                  expanded_final_url_fingerprint.to_s,
+                )
+            end
+
             def extension_feed_item(customer_id, feed_item_id)
               @proto_lookup_util.service(:ExtensionFeedItem).
                   extension_feed_item_path(