google-ads-googleads 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 786e9754852be58af6ed81928f5c2eb75784d4d24090479912ad3dd376a57d57
+  data.tar.gz: 21ef46bf2d76bc7085ca8ed1f2b6a63eb4becf92d61c0a8d970f926156c3cf4d
+SHA512:
+  metadata.gz: 55349a21aad338d63dcce98df2511a4372e7f36a00a9d25b74f83feba241c074579a29b22061ccb013afad1184e68737f1cd76b3167802fd80c482eda9fb1793
+  data.tar.gz: '0178da13bafbfd1c9b61e684397d76e2d02065f3ba53f2fd5345cc1d6f0a0ab29b30a8bdb0bbd70185515ea3875996b00824f6a97c9a73134746f541f32d055c'

data/ChangeLog

@@ -0,0 +1,2 @@
+0.1.0:
+  - Initial release with support for Google Ads API V0.

data/README.md

@@ -0,0 +1,107 @@
+# Google Ads Client Library for Ruby
+
+`google-ads-googleads` uses [Google API extensions][google-gax] to provide an
+easy-to-use client library for the [Google Ads API][].
+
+[google-gax]: https://github.com/googleapis/gax-ruby
+[Google Ads API]: https://developers.google.com/google-ads/api
+
+# Documentation for Users
+
+## 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:
+
+    $ [sudo] gem install google-ads-googleads
+
+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:
+
+    $ [sudo] gem install google-ads-googleads-[version].gem
+
+Or you can build it yourself from the source. After cloning the GitHub repo,
+navigate to the `google-ads-ruby` folder and run:
+
+    $ rake build
+    $ gem install pkg/google-ads-googleads-[version].gem
+
+[Releases]: https://github.com/googleads/google-ads-ruby/releases
+
+## 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.
+
+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.
+
+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.
+
+The simplest is to copy the [adwords_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
+with no arguments:
+
+    adwords = 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:
+
+    adwords = Google::Ads::Googleads::GoogleadsClient.new('path/to/file.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
+way:
+
+    adwords = Google::Ads::Googleads::GoogleadsClient.new do |config|
+      config.client_id = 'INSERT_CLIENT_ID_HERE'
+      config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
+      config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
+      config.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
+    end
+
+You can also modify these properties after instantiation by using the
+`configure` method on the `AdwordsClient`, using the same structure as above.
+
+[Authorization guide]: https://developers.google.com/google-ads/api/docs/oauth/
+[Authentication example]: https://github.com/googleads/google-ads-ruby/blob/master/examples/authentication/authenticate_in_standalone_application.rb
+[adwords_config.rb]: https://github.com/googleads/google-ads-ruby/blob/master/googleads_config.rb
+
+## Usage
+
+To include the gem in your code:
+
+    require 'google/ads/googleads'
+
+To fetch a specific service, for example CampaignService:
+
+    adwords = Google::Ads::Googleads::GoogleadsClient.new
+    campaign_service = adwords.service(:Campaign)
+
+See the provided [examples][] for more detailed demonstrations of how to use the
+library.
+
+[examples]: https://github.com/googleads/google-ads-ruby/blob/master/examples
+
+# Authors
+
+Author:
+
+ - Danial Klimkin
+ - Michael Cloonan
+
+Maintainer:
+
+ - Michael Cloonan

data/Rakefile

@@ -0,0 +1,7 @@
+# -*- ruby -*-
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/**/test_*.rb']
+end

data/googleads_config.rb

@@ -0,0 +1,10 @@
+# This is an example configuration file for the Google Ads API Ruby client
+# library.
+# Please fill in the required fields and copy it to your home directory.
+
+Google::Ads::Googleads::Config.new do |c|
+  c.client_id = 'INSERT_CLIENT_ID_HERE'
+  c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
+  c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
+  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
+end

data/lib/google/ads/googleads.rb

@@ -0,0 +1,25 @@
+# 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.
+
+require 'google/ads/googleads/googleads_client'
+
+module Google
+  module Ads
+    module Googleads
+    end
+  end
+end

data/lib/google/ads/googleads/config.rb

@@ -0,0 +1,42 @@
+# 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.
+#
+# Configuration setup for and storage for the API.
+
+module Google
+  module Ads
+    module Googleads
+      class Config
+        attr_accessor :refresh_token
+        attr_accessor :client_id
+        attr_accessor :client_secret
+        attr_accessor :developer_token
+
+        def initialize(&block)
+          @refresh_token = nil
+          @client_id = nil
+          @client_secret = nil
+          @developer_token = nil
+          yield self if block_given?
+        end
+
+        def configure(&block)
+          yield self
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# 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.
+#
+# File for all errors that will be used by the Google Ads API Library.
+
+module Google
+  module Ads
+    module Googleads
+      module Errors
+
+        # Generic error class for non-specific errors.
+        class Error < ::StandardError
+        end
+
+        # Raised when encountering an API-specific error, such as an entity
+        # not found or a malformed query.
+        class GoogleAdsError < Error
+          attr_reader :failure
+
+          def initialize(failure)
+            @failure = failure
+          end
+        end
+      end
+    end
+  end
+end

data/lib/google/ads/googleads/field_mask_util.rb

@@ -0,0 +1,159 @@
+# 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.
+#
+# Utility for constructing field masks, which are necessary for update
+# operations.
+
+require "google/protobuf"
+
+module Google
+  module Ads
+    module Googleads
+      # Utility for constructing FieldMask objects.
+      #
+      # Copied from C# implementation courtesy of jonskeet@google.com
+      class FieldMaskUtil
+        # Construct a field mask containing any changes to the object made
+        # in the given block.
+        #
+        # Example:
+        #
+        #   obj = MyObject.new
+        #   obj.some_property = 1
+        #
+        #   mask = FieldMaskUtil.with obj do
+        #     obj.other_property = 2
+        #   end
+        #
+        #   # the mask will contain the changed property "other_property"
+        #   api_client.mutate obj, mask
+        #
+        # @param obj [Object] the object to watch
+        # @yield block used for determining changes to the object
+        # @return [Google::Protobuf::FieldMask] the computed mask
+        def self.with(obj)
+          raise 'nil cannot be compared' if obj.nil?
+          original = obj.class.decode(obj.class.encode(obj))
+          yield
+          compare original, obj
+        end
+
+        # Construct a field mask containing any fields set on the given object.
+        #
+        # Example:
+        #
+        #   obj = MyObject.new
+        #   obj.some_property = 1
+        #   obj.other_property = 2
+        #
+        #   mask = FieldMaskUtil.all_set_fields_of obj
+        #
+        #   # the mask will contain the present properties "some_property" and
+        #   # "other_property"
+        #   api_client.mutate obj, mask
+        #
+        # @param obj [Object] the object to watch
+        # return [Google::Protobuf::FieldMask] the computed mask
+        def self.all_set_fields_of(obj)
+          new_instance = obj.class.new
+          compare_obj(Google::Protobuf::FieldMask.new, '', new_instance, obj)
+        end
+
+        # Creates Google::Protobuf::FieldMask objects based on the
+        # difference between two objects.
+        #
+        # @param original
+        # @param modified
+        # @return [Google::Protobuf::FieldMask] the computed mask
+        def self.compare(original, modified)
+          raise 'nil cannot be compared' if original.nil? || modified.nil?
+          raise 'objects of different types cannot be compared' if original.class != modified.class
+          compare_obj(Google::Protobuf::FieldMask.new, '', original, modified)
+        end
+
+        def self.compare_obj(mask, current_field, original, modified)
+          descriptor = original.class.descriptor
+
+          descriptor.entries.each do |field|
+            field_path = get_path current_field, field.name
+
+            # extract values
+            original_value = original[field.name]
+            modified_value = modified[field.name]
+
+            if is_repeated?(original_value) || is_repeated?(modified_value)
+              # repeated fields - must match exactly or add the field
+              mask.paths << field_path unless original_value == modified_value
+            else
+              case field.type
+              when :message
+                if original_value != modified_value
+                  # wrappers - do not include the .value part of the path
+                  if is_wrapper? [original_value, modified_value]
+                    mask.paths << field_path
+                  elsif original_value.nil?
+                    # new message, make a blank instance and then compare
+                    # against it
+                    original_value = modified[field.name].class.new
+                    compare_obj mask, field_path, original_value, modified_value
+                  elsif modified_value.nil?
+                    # just emit the deleted field name
+                    mask.paths << field_path
+                  else
+                    compare_obj mask, field_path, original_value, modified_value
+                  end
+                end
+              else # primitive types
+                mask.paths << field_path unless original_value == modified_value
+              end
+            end
+          end
+
+          mask
+        end
+
+        # Construts path string
+        def self.get_path(path, field)
+          path.nil? || path == '' ? field : "#{path}.#{field}"
+        end
+
+        WRAPPER_TYPES = [Google::Protobuf::DoubleValue,
+                          Google::Protobuf::FloatValue,
+                          Google::Protobuf::Int64Value,
+                          Google::Protobuf::UInt64Value,
+                          Google::Protobuf::Int32Value,
+                          Google::Protobuf::UInt32Value,
+                          Google::Protobuf::BoolValue,
+                          Google::Protobuf::StringValue,
+                          Google::Protobuf::BytesValue].freeze
+
+        # Checks if the object is a wrapper type
+        def self.is_wrapper?(obj)
+          obj = [obj] unless obj.is_a?(Array)
+          obj.any? { |x| WRAPPER_TYPES.count { |klass| klass == x.class } > 0 }
+        end
+
+        # Checks if the object is a repeated field
+        def self.is_repeated?(obj)
+          obj.is_a?(Google::Protobuf::RepeatedField)
+        end
+
+        private_class_method :compare_obj, :get_path, :is_wrapper?,
+            :is_repeated?
+      end
+    end
+  end
+end

data/lib/google/ads/googleads/googleads_client.rb

@@ -0,0 +1,177 @@
+# 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.
+#
+# Googleads client class to configure settings and fetch services.
+
+require 'googleauth'
+
+require 'google/ads/googleads/patches'
+require 'google/ads/googleads/config'
+require 'google/ads/googleads/field_mask_util'
+require 'google/ads/googleads/wrapper_util'
+require 'google/ads/googleads/proto_lookup_util'
+require 'google/ads/googleads/path_lookup_util'
+
+require 'google/ads/googleads/errors'
+require 'google/ads/googleads/v0/errors/errors_pb'
+
+require 'google/gax'
+
+module Google
+  module Ads
+    module Googleads
+      class GoogleadsClient
+        API_VERSION = :V0
+
+        DEFAULT_CONFIG_FILENAME = 'googleads_config.rb'
+
+        def initialize(config_path = nil, &block)
+          if block_given?
+            @config = Google::Ads::Googleads::Config.new
+
+            yield @config
+          else
+            if config_path.nil?
+              config_path = File.join(ENV['HOME'], DEFAULT_CONFIG_FILENAME)
+            end
+
+            unless File.exist?(config_path)
+              raise ArgumentError,
+                  sprintf('No configuration file found at location "%s"',
+                  config_path)
+            end
+            file = File.read(config_path)
+
+            eval_result = eval(file, binding, config_path)
+            unless eval_result.instance_of?(Google::Ads::Googleads::Config)
+              raise ArgumentError, sprintf(
+                  'Configuration file did not produce expected type ' +
+                  'Google::Ads::Googleads::Config, got "%s" instead',
+                  eval_result.class
+              )
+            end
+            @config = eval_result
+          end
+          @proto_lookup_util =
+              Google::Ads::Googleads::ProtoLookupUtil.new(API_VERSION)
+          @path_lookup_util =
+              Google::Ads::Googleads::PathLookupUtil.new(@proto_lookup_util)
+        end
+
+        def configure(&block)
+          yield @config
+        end
+
+        # Return a service for the provided entity type. For example, passing
+        # :Campaign will return an instantiated CampaignServiceClient.
+        #
+        # Raises ArgumentError if no service can be found for the provided type.
+        def service(name)
+          service_path = ENV['GOOGLEADS_SERVICE_PATH']
+
+          class_to_return = @proto_lookup_util.service(name)
+          unless service_path.nil? || service_path.empty?
+            class_to_return = Class.new(class_to_return) do
+              const_set('SERVICE_ADDRESS', service_path.freeze)
+            end
+          end
+
+          return class_to_return.new(
+            credentials: get_updater_proc(),
+            metadata: {:"developer-token" => @config.developer_token},
+            exception_transformer: ERROR_TRANSFORMER
+          )
+        end
+
+        # Return a resource or common entity for the provided entity type. For
+        # example, passing :Campaign will return an instantiated Campaign.
+        #
+        # Raises ArgumentError if no entity can be found for the provided type.
+        def resource(name)
+          @proto_lookup_util.resource(name).new
+        end
+
+        # Return an operation for the provided entity type. For example, passing
+        # :Campaign will return an instantiated CampaignOperation.
+        #
+        # Raises ArgumentError if no entity can be found for the provided type.
+        def operation(name)
+          @proto_lookup_util.operation(name).new
+        end
+
+        # Return a reference to the enum class for the provided enum type. For
+        # example, passing :CampaignStatus will return a reference to the
+        # CampaignStatusEnum.
+        #
+        # Raises ArgumentError if no enum can be found for the provided type.
+        def enum(name)
+          @proto_lookup_util.enum(name)
+        end
+
+        # Returns a reference to the FieldMaskUtil class for ease of access.
+        def field_mask()
+          Google::Ads::Googleads::FieldMaskUtil
+        end
+
+        # Returns a reference to the WrapperUtil class for ease of access.
+        def wrapper()
+          Google::Ads::Googleads::WrapperUtil
+        end
+
+        # Returns a reference to the PathLookupUtil to generate resource names.
+        def path()
+          @path_lookup_util
+        end
+
+        private
+
+        ERROR_TRANSFORMER = Proc.new do |gax_error|
+          begin
+            gax_error.status_details.each do |failure|
+              # If there is an underlying GoogleAdsFailure, throw that one.
+              if failure.is_a?(
+                  Google::Ads::Googleads::V0::Errors::GoogleAdsFailure)
+                raise Google::Ads::Googleads::Errors::GoogleAdsError.new(
+                    failure)
+              end
+            end
+          rescue Google::Ads::Googleads::Errors::GoogleAdsError
+            # If we raised this, bubble it out.
+            raise
+          rescue NoMethodError
+            # Sometimes status_details is just a String; in that case, we should
+            # just raise the original exception.
+          end
+          # If we don't find an error of the correct type, or if we run into an
+          # error while processing, just throw the original.
+          raise gax_error
+        end
+
+        # Provides the service a method by which to obtain an access token to
+        # authenticate API requests.
+        def get_updater_proc()
+          return Signet::OAuth2::Client.new(
+            token_credential_uri: 'https://www.googleapis.com/oauth2/v3/token',
+            client_id: @config.client_id,
+            client_secret: @config.client_secret,
+            refresh_token: @config.refresh_token,
+            scope: ['https://www.googleapis.com/auth/adwords']
+          ).updater_proc
+        end
+      end
+    end
+  end
+end