three-sixty 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3357b6f308efd6f848d6c5cee39547780b32dc2b
+  data.tar.gz: 3ad95ad642210362e42b440278ec98d7d9f8b75f
+SHA512:
+  metadata.gz: 97e80e12364c3a079c33c5f6e07abf23d2056eeacf6b60490d8341f5f339c825880779a42950024d4acc974e73aa4b90944cc9e3c18e3d0a15df1480afa8f670
+  data.tar.gz: 9385af23b6f6187947b989fc1e0d2feed8b99b678cf629b8f21416b3468ff08699439fa3c6c93e6d73caf408fada0c5e54d3718d9734fb257cc513d081bd8f5e

data/.gitignore

@@ -0,0 +1,4 @@
+documentation/*
+Gemfile*
+.bundle/*
+.ruby*

data/README.md

@@ -0,0 +1,95 @@
+# 360
+A Ruby gem for connecting to the 360 Dianjing AD system, using the Open API Platform
+
+## Install
+
+    gem 'three-sixty', github: 'forward3d/three-sixty'
+
+
+## Configuration
+
+    require 'three-sixty'
+    ThreeSixty.configure(logger: Logger.new($stdout))
+
+
+## Authenticate
+
+    require 'three-sixty'
+
+    client = ThreeSixty::Client.new(api_key, api_secret)
+    client.authenticate!(username, password)
+
+  You can specify a hash of optional parameters when initializing the client. These include
+
+    :endpoint - The 360 api endpoint (This is unlikely to change)
+    :version  - The 360 api version number
+    :format   - The api reponse format (Currently JSON or XML and is only useful when using the core library)
+    :logger   - The client logger
+
+
+## Get Campaign Ids
+
+    require 'three-sixty'
+
+    client = ThreeSixty::Client.new(api_key, api_secret)
+    client.authenticate!(username, password)
+
+    account = ThreeSixty::Account.new(client, opts)
+    campaign_ids = account.download_campaign_ids
+
+  You can specify a hash of optional parameters when initializing the account. These include
+
+    :logger                    - Attach a local logger
+    :report_generating_backoff - Create a lambda for your backoff strategy when polling the report generate e.g. lambda { |retry_number| [1 30 60 300].index(retry_number) }
+
+## Streaming Campaign Ids to a File
+
+    File.open('campaign_ids.csv', 'w') do |file|
+      account.download_campaigns(campaign_ids) do |content|
+        file.write content
+      end
+    end
+
+## Download Campaign Ids to a File
+
+    file = account.download_campaigns_to_file(campaign_ids, opts)
+
+  You can specify a hash of optional parameters, which includes
+
+    :download_dir - The directory to download the file
+    :filename     - The full path of the file you wish to create
+    :encoding     - The encoding used when downloading the file
+
+## Download Campaign Info
+
+    campaign = ThreeSixty::Campaign.new(client)
+    campaign_info = campaign.download_all_campaigns
+
+
+## Download All Ad Groups for a Campaign
+
+    group = ThreeSixty::Group.new(client)
+    group_info = group.download_campaign_all_ad_groups(campaigns_id)
+
+## Download All Creatives for a Campaign
+
+    group = ThreeSixty::Group.new(client)
+    ad_group_ids = group.download_campaign_ad_group_ids(campaign_id)
+
+    creatives = []
+    creative = ThreeSixty::Creative.new(client)
+    ad_group_ids.each do |ad_group_id|
+      creatives += creative.download_ad_group_all_creatives(ad_group_id)
+    end
+
+
+## Downlod All Keywords for a Campaign
+
+    group = ThreeSixty::Group.new(client)
+    ad_group_ids = group.download_campaign_ad_group_ids(campaign_id)
+
+    keywords = []
+    keyword = ThreeSixty::Keyword.new(client)
+    ad_group_ids.each do |ad_group_id|
+      keywords += keyword.download_ad_group_all_keywords(ad_group_id)
+    end

data/lib/three-sixty/account.rb

@@ -0,0 +1,90 @@
+require 'net/http'
+require 'securerandom'
+
+require_relative 'core/account'
+
+module ThreeSixty
+  class Account < ThreeSixty::Core::Account
+
+    attr_reader :report_generating_backoff, :logger
+
+    def initialize(client, opts = {})
+      opts = default_options.update(opts)
+
+      @report_generating_backoff  = opts[:report_generating_backoff]
+      @logger                     = opts[:logger] || client.logger
+
+      super(client)
+    end
+
+    def download_campaign_ids
+      get_campaign_id_list["campaignIdList"]
+    end
+
+    def download_campaigns(campaign_ids)
+      file_id = get_all_objects(campaign_ids)['fileId']
+
+      retry_number = 0
+      file_state = get_file_state(file_id)
+      while report_generating?(file_state["isGenerated"])
+        begin
+          @logger.debug "Waiting for report #{file_id} on retry number #{retry_number}"
+          sleep report_generating_backoff.call(retry_number)
+          retry_number += 1
+          file_state = get_file_state(file_id)
+        rescue TypeError => e
+          e.message = "Waiting too long to generate the report #{file_id}" # Re-raise with a better error message
+          raise e
+        end
+      end
+
+      @logger.info "Found file #{file_state["filePath"]} with size #{"%.2f" % (file_state["fileSize"] / 2**20)} MB"
+      download_filestream(file_state["filePath"]) { |chunk| yield chunk }
+      @logger.info "Finished downloading file #{file_state["filePath"]}"
+    end
+
+    def download_campaigns_to_file(campaign_ids, opts = {})
+      download_dir = opts[:download_dir] || "/tmp"
+      file = opts[:filename] || File.join(download_dir, "306_campaigns_" << SecureRandom.uuid << ".csv")
+
+      filemode = opts[:encoding].nil? ? 'w' : "w:#{opts[:encoding]}"
+
+      @logger.debug "Creating file #{file} with filemode #{filemode}"
+      File.open(file, filemode) do |fs|
+        download_campaigns(campaign_ids) do |content|
+          fs.write content
+        end
+      end
+
+      @logger.info "Finished downloading file to #{file}"
+      file
+    end
+
+    def exclude_ip_list
+      get_exclude_ip["excludeIpList"]
+    end
+
+
+    private
+
+    def report_generating?(status)
+      [ 'pending', 'process'].include?(status)
+    end
+
+    def download_filestream(file)
+      uri = URI(file)
+      Net::HTTP.start(uri.host, uri.port) do |http|
+        http.request_get(file) do |response|
+          response.read_body { |chunk| yield chunk }
+        end
+      end
+    end
+
+    def default_options
+      {
+        report_generating_backoff: lambda { |retry_number| retry_number < 5 ? 2**retry_number : nil }
+       }
+    end
+
+  end
+end

data/lib/three-sixty/campaign.rb

@@ -0,0 +1,14 @@
+require_relative 'core/campaign'
+require_relative 'account'
+
+module ThreeSixty
+  class Campaign < ThreeSixty::Core::Campaign
+
+    def download_all_campaigns
+      account = ThreeSixty::Account.new(@client)
+      campaign_ids = account.download_campaign_ids
+      get_info_by_id_list(campaign_ids)["campaignList"]
+    end
+
+  end
+end

data/lib/three-sixty/client.rb

@@ -0,0 +1,105 @@
+require 'openssl'
+require 'digest'
+require 'base64'
+require 'json'
+
+require_relative 'core/account'
+
+module ThreeSixty
+  class Client
+
+    attr_reader :api_key, :endpoint, :version, :logger
+    attr_reader :access_token, :session_token
+
+    def initialize(api_key, api_secret, opts = {})
+      opts        = default_options.update(opts)
+
+      @api_key    = api_key
+      @api_secret = api_secret
+      @endpoint   = opts[:endpoint]
+      @version    = opts[:version]
+      @format     = opts[:format]
+      @logger     = opts[:logger]
+    end
+
+    def authenticate!(username, password)
+      account = ThreeSixty::Core::Account.new(self)
+      tokens = account.client_login(username, generate_passwd(password))
+      @access_token = tokens['accessToken']
+      @session_token = tokens['sessionToken']
+    end
+
+    def request(resource_url, params = {})
+      params[:format] = @format
+      uri = URI(generate_url(resource_url, params))
+      @logger.debug "Resquest url #{uri.to_s}"
+      req = Net::HTTP::Post.new(uri, headers = generate_headers)
+      @logger.debug "Sending headers #{headers}"
+      res = Net::HTTP.start(uri.host) do |http|
+        http.request(req)
+      end
+      process_response(res)
+    end
+
+    private
+
+    def default_options
+      {
+        endpoint: ThreeSixty.configuration[:endpoint],
+        version:  ThreeSixty.configuration[:version],
+        format:   ThreeSixty.configuration[:format],
+        logger:   ThreeSixty.configuration[:logger]
+       }
+    end
+
+    def serveToken
+      DateTime.now.strftime("%Y%m%d%H%M%S%L")
+    end
+
+    def process_response(res)
+      case res.content_type
+      when 'application/json'
+        process_json_response(res.body)
+      else
+        # raise "Unable to process response of type #{res.content_type}"
+        res.body
+      end
+    end
+
+    def process_json_response(content)
+      JSON.parse(content)
+    end
+
+    def generate_headers
+      headers = { 'serveToken' => serveToken, 'apiKey' => @api_key }
+      headers['accessToken']  = @access_token unless @access_token.nil?
+      headers['sessionToken'] = @session_token unless @session_token.nil?
+      headers
+    end
+
+    def generate_passwd(password)
+      encrypt(password).unpack("H2"*32).join
+    end
+
+    def encrypt(password)
+      cipher = OpenSSL::Cipher::AES128.new(:CBC)
+      cipher.encrypt
+      cipher.key, cipher.iv = generate_key_and_vector(@api_secret)
+      cipher.update(Digest::MD5.hexdigest(password)) + cipher.final
+    end
+
+    def generate_key_and_vector(secret)
+      secret.scan(/.{16}/m).map { |s| Base64.decode64(Base64.encode64(s)) }
+    end
+
+    def generate_url(resource_url, query_params = {})
+      endpoint = @endpoint + (resource_url.split("/")[1] == 'clientLogin' ? '/' : '/' << version) # client login doesn't contain version in the url
+      [endpoint, resource_url].join('/') << '?' << querystring(query_params)
+    end
+
+    def querystring(query_params)
+      query_params.map { |key, value| key.to_s << '=' << URI.escape(value.to_s) }.join('&')
+    end
+
+  end
+end

data/lib/three-sixty/configuration.rb

@@ -0,0 +1,21 @@
+require 'logger'
+
+module ThreeSixty
+
+  DEFAULT_ENDPOINT = "https://api.e.360.cn"
+  DEFAULT_VERSION  = "1.6"
+  DEFAULT_FORMAT   = 'json'
+
+  @@configuration = {}
+
+  def self.configure(opts = {})
+    @@configuration[:endpoint] = opts[:endpoint] || DEFAULT_ENDPOINT
+    @@configuration[:version]  = opts[:version] || DEFAULT_VERSION
+    @@configuration[:format]   = opts[:format] || DEFAULT_FORMAT
+    @@configuration[:logger]   = opts[:logger] || Logger.new(nil)
+  end
+
+  def self.configuration
+    @@configuration
+  end
+end

data/lib/three-sixty/core/account.rb

@@ -0,0 +1,43 @@
+module ThreeSixty
+  module Core
+    class Account
+
+      SERVICE_URL = 'account'
+
+      def initialize(client)
+        @client = client
+      end
+
+      def client_login(username, password)
+        @client.request(resource_url("clientLogin"), username: username, passwd: password)
+      end
+
+      def get_campaign_id_list
+        @client.request(resource_url("getCampaignIdList"))
+      end
+
+      def get_info
+        @client.request(resource_url("getInfo"))
+      end
+
+      def get_all_objects(campaign_ids)
+        @client.request(resource_url("getAllObjects"), idList: campaign_ids)
+      end
+
+      def get_file_state(file_id)
+        @client.request(resource_url("getFileState"), fileId: file_id)
+      end
+
+      def get_exclude_ip
+        @client.request(resource_url("getExcludeIp"))
+      end
+
+      private
+
+      def resource_url(service)
+        [SERVICE_URL, service].join("/")
+      end
+
+    end
+  end
+end

data/lib/three-sixty/core/campaign.rb

@@ -0,0 +1,27 @@
+module ThreeSixty
+  module Core
+    class Campaign
+
+      SERVICE_URL = 'campaign'
+
+      def initialize(client)
+        @client = client
+      end
+
+      def get_info_by_id(campaign_id)
+        @client.request(resource_url("getInfoById"), id: campaign_id)
+      end
+
+      def get_info_by_id_list(campaign_ids)
+        @client.request(resource_url("getInfoByIdList"), idList: campaign_ids)
+      end
+
+      private
+
+      def resource_url(service)
+        [SERVICE_URL, service].join("/")
+      end
+
+    end
+  end
+end

data/lib/three-sixty/core/creative.rb

@@ -0,0 +1,40 @@
+module ThreeSixty
+  module Core
+    class Creative
+
+      SERVICE_URL = 'creative'
+
+      def initialize(client)
+        @client = client
+      end
+
+      def get_id_list_by_group_id(ad_group_id, opts = {})
+        opts.merge!(groupId: ad_group_id)
+        @client.request(resource_url("getIdListByGroupId"), opts)
+      end
+
+      def get_info_by_id(creative_id)
+        @client.request(resource_url("getInfoById"), id: creative_id)
+      end
+
+      def get_info_by_id_list(creative_ids)
+        @client.request(resource_url("getInfoByIdList"), idList: creative_ids)
+      end
+
+      def get_status_by_id_list(creative_ids)
+        @client.request(resource_url("getStatusByIdList"), idList: creative_ids)
+      end
+
+      def get_changed_id_list(from_time)
+        @client.request(resource_url("getChangedIdList"), fromTime: from_time)
+      end
+
+      private
+
+      def resource_url(service)
+        [SERVICE_URL, service].join("/")
+      end
+
+    end
+  end
+end

data/lib/three-sixty/core/group.rb

@@ -0,0 +1,32 @@
+module ThreeSixty
+  module Core
+    class Group
+
+      SERVICE_URL = 'group'
+
+      def initialize(client)
+        @client = client
+      end
+
+      def get_id_list_by_campaign_id(campaign_id, opts = {})
+        opts.merge!(campaignId: campaign_id)
+        @client.request(resource_url("getIdListByCampaignId"), opts)
+      end
+
+      def get_info_by_id(adgroup_id)
+        @client.request(resource_url("getInfoById"), id: adgroup_id)
+      end
+
+      def get_info_by_id_list(adgroup_ids)
+        @client.request(resource_url("getInfoByIdList"), idList: adgroup_ids)
+      end
+
+      private
+
+      def resource_url(service)
+        [SERVICE_URL, service].join("/")
+      end
+
+    end
+  end
+end

data/lib/three-sixty/core/keyword.rb

@@ -0,0 +1,40 @@
+module ThreeSixty
+  module Core
+    class Keyword
+
+      SERVICE_URL = 'keyword'
+
+      def initialize(client)
+        @client = client
+      end
+
+      def get_id_list_by_group_id(ad_group_id, opts = {})
+        opts.merge!(groupId: ad_group_id)
+        @client.request(resource_url("getIdListByGroupId"), opts)
+      end
+
+      def get_info_by_id(keyword_id)
+        @client.request(resource_url("getInfoById"), id: keyword_id)
+      end
+
+      def get_status_by_id_list(keyword_ids)
+        @client.request(resource_url("getStatusByIdList"), idList: keyword_ids)
+      end
+
+      def get_info_by_id_list(keyword_ids)
+        @client.request(resource_url("getInfoByIdList"), idList: keyword_ids)
+      end
+
+      def get_changed_id_list(from_time)
+        @client.request(resource_url("getChangedIdList"), fromTime: from_time)
+      end
+
+      private
+
+      def resource_url(service)
+        [SERVICE_URL, service].join("/")
+      end
+
+    end
+  end
+end

data/lib/three-sixty/core/report.rb

@@ -0,0 +1,49 @@
+module ThreeSixty
+  module Core
+    class Report
+
+      SERVICE_URL = 'report'
+
+      def initialize(client)
+        @client = client
+      end
+
+      def keyword_count(start_date, level, opts = {})
+        opts.merge!({startDate: start_date, level: level})
+        @client.request(resource_url("keywordCount"), opts)
+      end
+
+      def keyword(start_date, level, opts = {})
+        opts.merge!({startDate: start_date, level: level})
+        @client.request(resource_url("keyword"), opts)
+      end
+
+      def creative_count(start_date, level, opts = {})
+        opts.merge!({startDate: start_date, level: level})
+        @client.request(resource_url("creativeCount"), opts)
+      end
+
+      def creative(start_date, level, opts = {})
+        opts.merge!({startDate: start_date, level: level})
+        @client.request(resource_url("creative"), opts)
+      end
+
+      def region_count(start_date, level, opts = {})
+        opts.merge!({startDate: start_date, level: level})
+        @client.request(resource_url("regionCount"), opts)
+      end
+
+      def region(start_date, level, opts = {})
+        opts.merge!({startDate: start_date, level: level})
+        @client.request(resource_url("region"), opts)
+      end
+
+      private
+
+      def resource_url(service)
+        [SERVICE_URL, service].join("/")
+      end
+
+    end
+  end
+end

data/lib/three-sixty/creative.rb

@@ -0,0 +1,27 @@
+require_relative 'core/creative'
+
+module ThreeSixty
+  class Creative < ThreeSixty::Core::Creative
+
+    def download_ad_group_creative_ids(ad_group_id, opts = {})
+      get_id_list_by_group_id(ad_group_id, opts)["creativeIdList"]
+    end
+
+    def download_ad_group_all_creatives(ad_group_id, opts = {})
+      creative_ids = download_ad_group_creative_ids(ad_group_id, opts = {})
+      return [] if creative_ids.empty?
+      get_info_by_id_list(creative_ids)["creativeList"]
+    end
+
+    def download_ad_group_all_creative_statuses(ad_group_id, opts = {})
+      creative_ids = download_ad_group_creative_ids(ad_group_id, opts = {})
+      return [] if creative_ids.empty?
+      get_status_by_id_list(creative_ids)["creativeList"]
+    end
+
+    def download_changed_creative_ids(from_time)
+      get_changed_id_list(from_time)["creativeIdList"]
+    end
+
+  end
+end

data/lib/three-sixty/group.rb

@@ -0,0 +1,17 @@
+require_relative 'core/group'
+require_relative 'account'
+
+module ThreeSixty
+  class Group < ThreeSixty::Core::Group
+
+    def download_campaign_ad_group_ids(campaign_id, opts = {})
+      get_id_list_by_campaign_id(campaign_id, opts)["groupIdList"]
+    end
+
+    def download_campaign_all_ad_groups(campaign_id, opts = {})
+      ad_group_ids = download_campaign_ad_group_ids(campaign_id)
+      get_info_by_id_list(ad_group_ids)["groupList"]
+    end
+
+  end
+end

data/lib/three-sixty/keyword.rb

@@ -0,0 +1,27 @@
+require_relative 'core/keyword'
+
+module ThreeSixty
+  class Keyword < ThreeSixty::Core::Keyword
+
+    def download_ad_group_keyword_ids(ad_group_id, opts = {})
+      get_id_list_by_group_id(ad_group_id, opts)["keywordIdList"]
+    end
+
+    def download_ad_group_all_keywords(ad_group_id, opts = {})
+      keyword_ids = download_ad_group_keyword_ids(ad_group_id)
+      return [] if keyword_ids.empty?
+      get_info_by_id_list(keyword_ids)["keywordList"]
+    end
+
+    def download_ad_group_all_keyword_statuses(ad_group_id, opts = {})
+      keyword_ids = download_ad_group_keyword_ids(ad_group_id)
+      return [] if keyword_ids.empty?
+      get_status_by_id_list(keyword_ids)["keywordList"]
+    end
+
+    def download_changed_keyword_ids(from_time)
+      get_changed_id_list(from_time)["keywordIdList"]
+    end
+
+  end
+end

data/lib/three-sixty/level.rb

@@ -0,0 +1,9 @@
+module ThreeSixty
+  module Level
+
+    ACCOUNT = :account
+    PLAN    = :plan
+    GROUP   = :group
+
+  end
+end

data/lib/three-sixty/report.rb

@@ -0,0 +1,7 @@
+require_relative 'core/report'
+
+module ThreeSixty
+  class Report < ThreeSixty::Core::Report
+
+  end
+end

data/lib/three-sixty/version.rb

@@ -0,0 +1,3 @@
+module ThreeSixty
+  VERSION = "0.0.1"
+end

data/lib/three-sixty.rb

@@ -0,0 +1,13 @@
+require_relative 'three-sixty/level'
+require_relative 'three-sixty/configuration'
+require_relative 'three-sixty/campaign'
+require_relative 'three-sixty/account'
+require_relative 'three-sixty/client'
+require_relative 'three-sixty/group'
+require_relative 'three-sixty/creative'
+require_relative 'three-sixty/keyword'
+require_relative 'three-sixty/report'
+
+module ThreeSixty
+  ThreeSixty.configure
+end

data/three-sixty.gemspec

@@ -0,0 +1,17 @@
+require File.join(File.expand_path('../lib', __FILE__), 'three-sixty', 'version')
+
+Gem::Specification.new do |gem|
+  gem.name          = "three-sixty"
+  gem.version       = ThreeSixty::VERSION
+  gem.authors       = ["Daniel Padden"]
+  gem.email         = ["daniel.padden@forward3d.com"]
+  gem.description   = %q{Connecting to the 360 api}
+  gem.summary       = %q{Gathering data from the 360 api}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files -z`.split("\x0")
+  gem.executables   = gem.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: three-sixty
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Daniel Padden
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-06-17 00:00:00.000000000 Z
+dependencies: []
+description: Connecting to the 360 api
+email:
+- daniel.padden@forward3d.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- README.md
+- lib/three-sixty.rb
+- lib/three-sixty/account.rb
+- lib/three-sixty/campaign.rb
+- lib/three-sixty/client.rb
+- lib/three-sixty/configuration.rb
+- lib/three-sixty/core/account.rb
+- lib/three-sixty/core/campaign.rb
+- lib/three-sixty/core/creative.rb
+- lib/three-sixty/core/group.rb
+- lib/three-sixty/core/keyword.rb
+- lib/three-sixty/core/report.rb
+- lib/three-sixty/creative.rb
+- lib/three-sixty/group.rb
+- lib/three-sixty/keyword.rb
+- lib/three-sixty/level.rb
+- lib/three-sixty/report.rb
+- lib/three-sixty/version.rb
+- three-sixty.gemspec
+homepage: ''
+licenses: []
+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.2.1
+signing_key: 
+specification_version: 4
+summary: Gathering data from the 360 api
+test_files: []