ya-api-direct 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ce703501aca78c8a889a4882c95500b2bb419c30
+  data.tar.gz: 2b2be4b799ae9a28908fd44a362635f76e7cd99d
+SHA512:
+  metadata.gz: 70218a0c73fc096cbee98e6ad145739338cf52e1f6e94143bb8c263f950a8ac781dcef3fdfff1350c57d2e1bb5642cd0c51c8f1df54331efb6875bb1f728fa02
+  data.tar.gz: 7431e2c5e3428697130ad840001c05157813035e4b09465e27ae015f1023ddf5ca069dcbed26e46fec02ccb631ec91757c0f3fd69b6a9412937dc06de6733a63

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 Alexander Teut
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,82 @@
+# ya-api-direct
+A Ruby interface to Yandex Direct API
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'ya-api-direct'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ya_direct_api
+
+Test with rake:
+
+    $ rake
+
+## Usage
+
+OAuth2 Yandex token is needed. Use [omniauth-yandex](https://github.com/evrone/omniauth-yandex/) to receive it. Install it according by following manual: [Rails Authentication with OAuth 2.0 and OmniAuth](https://www.sitepoint.com/rails-authentication-oauth-2-0-omniauth/).
+
+Call methods of Yandex Direct API 5:
+
+```ruby
+request = {
+    "SelectionCriteria" => {
+      "Types" => ["TEXT_CAMPAIGN"]
+    },
+    "FieldNames" => ["Id", "Name"],
+    "TextCampaignFieldNames" => ["BiddingStrategy"]
+}
+
+@direct = Ya::API::Direct::Client.new({ token: Token })
+json = direct.campaigns.get request
+```
+
+Call methods from versions 4 and 4 Live:
+
+```ruby
+@direct = Ya::API::Direct::Client.new({ token: Token })
+json = direct.v4.GetCampaignsList []
+```
+
+All names of controllers and methods are equal to ones from Direct API help. 4 vs 4 Live is autodetected.
+
+## Caching
+
+By default the client class sends request to clients. You can avoid it by turning this option off, like this:
+
+
+```ruby
+@direct = Ya::API::Direct::Client.new({ token: Token, cache: false })
+```
+
+Check [Yandex manuals](https://yandex.ru/adv/edu/direct-api/kak-ispolzovat-api-effektivno-ogranicheniya-i-rekomendatsii) for more info on caching.
+
+Date returned with first call of caching method is stored in ``cache_timestamp`` property.
+
+## Units data
+
+Units data of last request is stored in ``units_data`` property. There're 3 keys in this hash:
+* ``just_used``
+* ``units_left``
+* ``units_limit``
+
+## Useful links
+
+* [Intruduction to Yandex Direct API](https://yandex.ru/adv/edu/direct-api)
+* [Yandex Direct API 5 manual](https://tech.yandex.ru/direct/doc/dg/concepts/about-docpage/)
+* [Yandex Direct API 4 and 4 Live manual](https://tech.yandex.ru/direct/doc/dg-v4/concepts/About-docpage/)
+
+## Contributing
+
+1. Fork it ( http://github.com/rikkimongoose/ya-api-direct/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/lib/ya/api/direct/client.rb

@@ -0,0 +1,91 @@
+require "ya/api/direct/constants"
+require "ya/api/direct/gateway"
+require "ya/api/direct/direct_service_v4"
+require "ya/api/direct/direct_service_v5"
+require "ya/api/direct/exception"
+
+module Ya::API::Direct
+  AllowedAPIVersions = [:v5, :v4]
+
+  # Yandex Direct API client class
+  # @author RikkiMongoose
+  class Client
+    attr_reader :cache_timestamp, :units_data, :gateway,
+                :v4, :v5
+    
+    # Initializes a new Client object
+    #
+    # @param config [Hash]
+    # @return [Ya::API::Direct::Client]
+    def initialize(config = {})
+      @config = {
+        token: nil,
+        app_id: nil,
+        login: '',
+        locale: 'en',
+        mode: :sandbox,
+        format: :json,
+        cache: true,
+        api: :v5,
+        ssl: true
+      }.merge(config)
+
+      @units_data = {
+        just_used: nil,
+        units_left: nil,
+        units_limit: nil
+      }
+
+      raise "Token can't be empty" if @config[:token].nil?
+      raise "Allowed Yandex Direct API versions are #{AllowedVersions}" unless AllowedAPIVersions.include? @config[:api]
+
+      @gateway = Ya::API::Direct::Gateway.new @config
+
+      init_v4
+      init_v5
+      start_cache! if @config[:cache]
+      yield self if block_given?
+    end
+
+    # Update units data.
+    #
+    # @param format [Hash] New units data values
+    # @return [Hash] Updated user data values
+    def update_units_data(units_data = {})
+      @units_data.merge! units_data
+    end
+
+    # Start caching. Executed automatically, if @congif[:cache] is true.
+    #
+    # @return [String] New timestamp value.
+    def start_cache!
+      case @config[:api]
+      when :v4
+        result = @gateway.request("GetChanges", {}, nil, :v4live)
+        timestamp = result[:data]['data']['Timestamp']
+      when :v5
+        result = @gateway.request("checkDictionaries", {}, "changes", :v5)
+        timestamp = result[:data]['result']['Timestamp']
+      end
+      @cache_timestamp = Time.parse(timestamp)
+      update_units_data result[:units_data]
+      @cache_timestamp
+    end
+
+    private
+    
+    def init_v4
+      @v4 = DirectServiceV4.new self, (API_V4 + API_V4_LIVE)
+    end
+
+    def init_v5
+      @v5 = {}
+      API_V5.each do |service, methods|
+        service_item = DirectServiceV5.new(self, service, methods)
+        service_key = service_item.service_url
+        @v5[service_key] = service_item
+        self.class.send :define_method, service_key do @v5[service_key] end
+      end
+    end
+  end
+end

data/lib/ya/api/direct/constants.rb

@@ -0,0 +1,136 @@
+module Ya
+  module API
+    module Direct
+      API_V5 = {
+        "Campaigns" => [
+          "add", "update", "delete", "suspend", "resume", "archive", "unarchive", "get"
+        ],
+        "AdGroups" => [
+        "add", "update", "delete", "get"
+        ],
+        "Ads" => [
+          "add", "update", "delete", "suspend", "resume", "archive", "unarchive", "moderate", "get"
+        ],
+        "Bids" => [
+          "set", "setAuto", "get"
+        ],
+        "BidModifiers" => [
+            "add", "delete", "get", "set", "toggle"
+          ],
+        "Campaigns" => [
+            "add", "update", "delete", "suspend", "resume", "archive", "unarchive", "get"
+          ],
+        "Changes" => [
+            "checkDictionaries", "checkCampaigns", "check"
+          ],
+        "Dictionaries" => [
+            "get"
+        ],
+        "DynamicTextAdTargets" => [
+          "add", "delete", "suspend", "resume", "get", "setBids"
+        ],
+        "Keywords" => [
+          "add", "update", "delete", "suspend", "resume", "get"
+        ],
+        "Sitelinks" => [
+          "add", "get", "delete"
+        ],
+        "VCards" => [
+          "add", "get", "delete"
+        ]
+      }
+      
+      API_V4 = [
+        "GetBalance",
+        "GetSummaryStat",
+        "CreateNewReport",
+        "DeleteReport",
+        "GetReportList",
+
+        "CreateNewWordstatReport",
+        "DeleteWordstatReport",
+        "GetWordstatReport",
+        "GetWordstatReportList",
+
+        "GetKeywordsSuggestion",
+
+        "CreateNewForecast",
+        "DeleteForecastReport",
+        "GetForecast",
+        "GetForecastList",
+
+        "CreateInvoice",
+        "TransferMoney",
+        "GetCreditLimits",
+        "PayCampaigns",
+
+        "GetClientsUnits",
+        "GetSubClients",
+        "GetClientInfo",
+        "UpdateClientInfo",
+        
+        "CreateNewSubclient",
+        "GetClientsList",
+
+        "GetRegions",
+        "GetRubrics",
+        "GetTimeZones",
+        "GetStatGoals",
+
+        "GetAvailableVersions",
+        "GetVersion",
+        "PingAPI",
+      ]
+
+
+      API_V4_LIVE = [
+        "CreateOrUpdateCampaign",
+        "GetCampaignsList",
+        "GetCampaignsListFilter",
+        "GetCampaignsParams",
+        "DeleteCampaign",
+
+        "CreateOrUpdateBanners",
+        "GetBanners",
+        "GetBannerPhrases",
+        "GetBannerPhrasesFilter",
+        "DeleteBanners",
+        "Keyword",
+
+        "ModerateBanners",
+        "ResumeBanners",
+        "StopBanners",
+        "ArchiveBanners",
+        "UnArchiveBanners",
+
+        "SetAutoPrice",
+        "UpdatePrices",
+
+        "GetBannersStat",
+
+        "ResumeCampaign",
+        "StopCampaign",
+        "ArchiveCampaign",
+        "UnArchiveCampaign",
+
+        "GetBannersTags",
+        "UpdateBannersTags",
+        "GetCampaignsTags",
+        "UpdateCampaignsTags",
+
+        "AdImage",
+        "AdImageAssociation",
+
+        "GetRetargetingGoals",
+        "RetargetingCondition",
+        "Retargeting",
+
+        "EnableSharedAccount",
+        "AccountManagement",
+
+        "GetChanges",
+        "GetEventsLog",
+      ]
+    end
+  end
+end

data/lib/ya/api/direct/direct_service_base.rb

@@ -0,0 +1,28 @@
+require "ya/api/direct/constants"
+
+module Ya::API::Direct
+  class DirectServiceBase
+    attr_reader :method_items, :version
+    def initialize(client, methods)
+      @client = client
+      @method_items = methods
+      init_methods
+    end
+
+    protected
+
+    def exec_request(method, request_body)
+      client.gateway.request method, request_body, @version
+    end
+
+    def init_methods
+      @method_items.each do |method|
+        self.class.send :define_method, method do |params = {}|
+          result = exec_request(method, params || {})
+          @client.update_units_data result[:units_data]
+          result[:data]
+        end
+      end
+    end
+  end
+end

data/lib/ya/api/direct/direct_service_v4.rb

@@ -0,0 +1,16 @@
+require "ya/api/direct/constants"
+require "ya/api/direct/direct_service_base"
+
+module Ya::API::Direct
+  class DirectServiceV4 < DirectServiceBase
+
+    def initialize(client, methods, version = :v4)
+      super(client, methods)
+      @version = version
+    end
+
+    def exec_request(method, request_body = {})
+      @client.gateway.request method, request_body, nil, (API_V4_LIVE.include?(method) ? :v4live : @version)
+    end
+  end
+end

data/lib/ya/api/direct/direct_service_v5.rb

@@ -0,0 +1,19 @@
+require "ya/api/direct/constants"
+require "ya/api/direct/direct_service_base"
+
+module Ya::API::Direct
+  class DirectServiceV5 < DirectServiceBase
+    attr_reader :service, :service_url
+
+    def initialize(client, service, methods)
+      super(client, methods)
+      @service = service
+      @service_url = service.downcase
+      @version = :v5
+    end
+
+    def exec_request(method, request_body={})
+      @client.gateway.request method, request_body, @service_url, @version
+    end
+  end
+end

data/lib/ya/api/direct/exception.rb

@@ -0,0 +1,17 @@
+require "ya/api/direct/constants"
+
+module Ya::API::Direct
+  class Exception < StandardError
+    attr_reader :error_detail, :error_code, :error_str
+
+    def initialize(error_detail, error_str, error_code)
+      @error_detail = error_detail
+      @error_str = error_str
+      @error_code = error_code
+    end
+
+    def to_s
+      "#{@error_str} : #{@error_detail} : #{@error_code}"
+    end
+  end
+end

data/lib/ya/api/direct/gateway.rb

@@ -0,0 +1,59 @@
+require "net/http"
+require "openssl"
+require "json"
+
+require "ya/api/direct/constants"
+require "ya/api/direct/url_helper"
+
+module Ya::API::Direct
+  class Gateway
+    attr_reader :config
+    def initialize(config)
+      @config = config
+    end
+
+    def request(method, params, service = "", version = nil)
+      ver = version || (service.nil? ? :v4 : :v5)
+      url = UrlHelper.direct_api_url @config[:mode], ver, service
+      header = generate_header ver
+      body = generate_body method, params, ver
+      uri = URI.parse url
+      request = Net::HTTP::Post.new(uri.path, initheader = header)
+      request.body = body.to_json
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.verify_mode = @config[:ssl] ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+      response = http.request(request)
+      if response.kind_of? Net::HTTPSuccess
+        UrlHelper.parse_data response
+      else
+        raise response.inspect
+      end
+    end
+
+    def generate_header(ver)
+      header = {}
+      if ver == :v5
+        header.merge!({
+          'Client-Login' => @config[:login],
+          'Accept-Language' => @config[:locale],
+          'Authorization' => "Bearer %{token}" % @config
+        })
+      end
+    end
+
+    def generate_body(method, params, ver)
+      body = {
+          "method" => method,
+          "params" => params
+        }
+      if [:v4, :v4live].include? ver
+        body.merge!({
+          "locale" => @config[:locale],
+          "token" => @config[:token]
+        })
+      end
+      body
+    end
+  end
+end

data/lib/ya/api/direct/url_helper.rb

@@ -0,0 +1,82 @@
+require "json"
+
+require "ya/api/direct/constants"
+require "ya/api/direct/exception"
+
+module Ya::API::Direct
+  RegExUnits = Regexp.new /(\d+)\/(\d+)\/(\d+)/
+  # Static class with helping functions for url formatting.
+  #
+  # @author Rikki Mongoose
+	class UrlHelper
+      # Generate Yandex Direct API url for a call
+      # 
+      # @param mode [Symbol] Direct API mode, `:sandbox` or `:production`
+      # @param mode [Symbol] Direct API version, `:v5` or `:v4` or `:v4live`
+      # @param mode [Symbol] Direct API service to use
+      # @return [String] Generated Yandex Direct API URL
+  		def self.direct_api_url(mode = :sandbox, version = :v5, service = "")
+        format = :json
+  			protocol = "https"
+  			api_prefixes = {
+  				sandbox: "api-sandbox",
+  				production: "api"
+  			}
+        api_prefix = api_prefixes[mode || :sandbox]
+        site = "%{api}.direct.yandex.ru" % {api: api_prefix}
+  			api_urls = {
+  				v4: {
+  					json: '%{protocol}://%{site}/v4/json',
+  					soap: '%{protocol}://%{site}/v4/soap',
+  					wsdl: '%{protocol}://%{site}/v4/wsdl',
+  					},
+  				v4live: {
+  					json: '%{protocol}://%{site}/live/v4/json',
+  					soap: '%{protocol}://%{site}/live/v4/soap',
+  					wsdl: '%{protocol}://%{site}/live/v4/wsdl',
+  					},
+  				v5: {
+  					json: '%{protocol}://%{site}/json/v5/%{service}',
+  					soap: '%{protocol}://%{site}/v5/%{service}',
+  					wsdl: '%{protocol}://%{site}/v5/%{service}?wsdl',
+  				    }
+  				}
+        api_urls[version][format] % {
+          protocol: protocol,
+          site: site,
+          service: service
+        }
+  	end
+
+    # Extract Yandex Direct API units values from responce HTTP header
+    # 
+    # @param responce_header [Hash] Yandex Direct API response header
+    # @return [Hash] Units data, extracted from header
+    def self.extract_response_units(response_header)
+      matched = RegExUnits.match response_header["Units"]
+      {
+        just_used: matched[1].to_i,
+        units_left: matched[2].to_i,
+        units_limit: matched[3].to_i
+      }
+    end
+
+    private
+
+    def self.parse_data(response)
+      response_body = JSON.parse(response.body)
+      validate_response! response_body
+      {
+         data: response_body,
+         units_data: self.extract_response_units(response)
+      }
+    end
+
+    def self.validate_response!(response_body)
+      if response_body.has_key? 'error'
+        response_error = response_body['error']
+        raise Exception.new(response_error['error_detail'], response_error['error_string'], response_error['error_code'])
+      end
+    end
+	end
+end

data/lib/ya/api/direct/version.rb

@@ -0,0 +1,49 @@
+module Ya
+  module API
+    module Direct
+      module Version
+      	module_function
+
+        # @return [Integer]
+        def major
+          0
+        end
+
+        # @return [Integer]
+        def minor
+          2
+        end
+
+        # @return [Integer]
+        def patch
+          0
+        end
+
+        # @return [Integer, NilClass]
+        def pre
+          nil
+        end
+
+        # @return [Hash]
+        def to_h
+          {
+            major: major,
+            minor: minor,
+            patch: patch,
+            pre: pre,
+          }
+        end
+
+        # @return [Array]
+        def to_a
+          [major, minor, patch, pre].compact
+        end
+
+        # @return [String]
+        def to_s
+          to_a.join('.')
+        end
+      end
+    end
+  end
+end

data/ya-api-direct.gemspec

@@ -0,0 +1,18 @@
+# coding: utf-8
+$:.push File.expand_path("../lib", __FILE__)
+
+require 'ya/api/direct/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'ya-api-direct'
+  s.version     = '0.0.1'
+  s.date        = '2016-09-05'
+  s.summary     = "Yandex Direct API v5"
+  s.description = "Ruby implementation for Yandex Direct API of versions 5, 4 and 4 Live"
+  s.authors     = %w("Alexander Teut")
+  s.email       = 'alexander.a.teut@gmail.com'
+  s.files       = %w(LICENSE README.md ya-api-direct.gemspec) + Dir['lib/ya/api/direct/*.rb']
+  s.homepage    = 'http://rubygems.org/gems/ya-api-direct'
+  s.license     = 'MIT'
+  s.version     = Ya::API::Direct::Version
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: ya-api-direct
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- '"Alexander'
+- Teut"
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-09-05 00:00:00.000000000 Z
+dependencies: []
+description: Ruby implementation for Yandex Direct API of versions 5, 4 and 4 Live
+email: alexander.a.teut@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- ya-api-direct.gemspec
+- lib/ya/api/direct/client.rb
+- lib/ya/api/direct/constants.rb
+- lib/ya/api/direct/direct_service_base.rb
+- lib/ya/api/direct/direct_service_v4.rb
+- lib/ya/api/direct/direct_service_v5.rb
+- lib/ya/api/direct/exception.rb
+- lib/ya/api/direct/gateway.rb
+- lib/ya/api/direct/url_helper.rb
+- lib/ya/api/direct/version.rb
+homepage: http://rubygems.org/gems/ya-api-direct
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14.1
+signing_key: 
+specification_version: 4
+summary: Yandex Direct API v5
+test_files: []