datasift 1.5.0 → 2.0.0

data/examples/push/view.rb

@@ -0,0 +1,31 @@
+# This script views the details of Push subscriptions in your account.
+#
+# NB: Most of the error handling (exception catching) has been removed for
+# the sake of simplicity. Nearly everything in this library may throw
+# exceptions, and production code should catch them. See the documentation
+# for full details.
+#
+
+# Include the shared Env class
+require File.dirname(__FILE__) + '/env'
+
+# Create the env object. This reads the command line arguments, creates the
+# user object, and provides access to both along with helper functions.
+env = Env.new()
+
+# Make sure we have something to do
+abort('Please specify one or more subscription IDs') unless env.args.size() > 0
+
+for sub_id in env.args
+	begin
+		sub = env.user.getPushSubscription(sub_id)
+		env.displaySubscriptionDetails(sub)
+	rescue DataSift::DataSiftError => err
+		puts 'ERR: [' + err.class.name + '] ' + err.message
+		puts '--'
+	end
+end
+
+if env.user.rate_limit_remaining != -1
+	puts 'Rate limit remainining: ' + String(env.user.rate_limit_remaining)
+end

data/lib/DataSift/apiclient.rb

@@ -1,32 +1,22 @@
-#
-# apiclient.rb - This file contains the ApiClient class.
-#
-# Copyright (C) 2011 MediaSift Ltd
-#
-# == Overview
-#
-# The ApiClient class wraps the functionality that makes calls to the
-# DataSift API.
-
 require 'rest_client'
 require 'yajl'
 
 module DataSift
-	# ApiCLient class.
-	#
-	# == Introduction
-	#
-	# The ApiClient class wraps the functionality that makes calls to the
-	# DataSift API.
-	#
+	#The ApiClient class wraps the functionality that makes calls to the
+	#DataSift API.
 	class ApiClient
-		# Make a call to a DataSift API endpoint.
-		# === Parameters
-		#
-		# * +endpoint+ - The endpoint of the API call.
-		# * +params+ - The parameters to be passed along with the request.
-		# * +username+ - The username for the Auth header
-		# * +api_key+ - The API key for the Auth header
+		#Make a call to a DataSift API endpoint.
+		#=== Parameters
+		#* +endpoint+ - The endpoint of the API call.
+		#* +params+ - The parameters to be passed along with the request.
+		#* +username+ - The username for the Auth header
+		#* +api_key+ - The API key for the Auth header
+		#=== Returns
+		#A Hash contatining...
+		#* +response_code+ - The HTTP response code.
+		#* +data+ - A Hash containing the response data.
+		#* +rate_limit+ - The total API credits you get per hour.
+		#* +rate_limit_remaining+ - The number of API credits you have remaining for this hour.
 		def call(username, api_key, endpoint, params = {}, user_agent = 'DataSiftPHP/0.0')
 			# Build the full endpoint URL
 			url = 'http://' + User::API_BASE_URL + endpoint
@@ -64,11 +54,16 @@ module DataSift
 				retval['data'] = Yajl::Parser.parse(err.response)
 			end
 
-			retval
+			return retval
 		end
 
 	private
 
+		#Convert a Hash to an HTTP query string.
+		#=== Parameters
+		#* +hash+ - The Hash to convert.
+		#=== Returns
+		#A string containing the equivalent query string.
 		def hashToQuerystring(hash)
 			hash.keys.inject('') do |query_string, key|
 				query_string << '&' unless key == hash.keys.first

data/lib/DataSift/definition.rb

@@ -1,50 +1,34 @@
-#
-# definition.rb - This file contains the Definition class.
-#
-# Copyright (C) 2011 MediaSift Ltd
-#
-# == Overview
-#
-# The User class represents a user of the API. Applications should start their
-# API interactions by creating an instance of this class. Once initialised it
-# provides factory methods for all of the functionality in the API.
-
 require 'date'
 
 module DataSift
-
-	# Definition class.
-	#
-	# == Introduction
-	#
-	# The Definition class represents a stream definition.
-	#
+	#The Definition class represents a stream definition.
 	class Definition
-		attr_reader :csdl, :total_dpu, :created_at
-
-		# Constructor. A User object is required, and you can optionally supply a
-		# default CSDL string.
-		# === Parameters
-		#
-		# * +user+ - The DataSift::User object.
-		# * +csdl+ - Optional default CSDL string.
-		# * +hash+ - Optional default hash string.
-		#
+		#The CSDL for this Definition.
+		attr_reader :csdl
+
+		#Constructor. A User object is required, and you can optionally supply a
+		#default CSDL string.
+		#=== Parameters
+		#* +user+ - The DataSift::User object.
+		#* +csdl+ - Optional default CSDL string.
+		#* +hash+ - Optional default hash string.
 		def initialize(user, csdl = '', hash = false)
 			raise InvalidDataError, 'Please supply a valid User object when creating a Definition object.' unless user.is_a? DataSift::User
 			@user = user
 			clearHash()
 			@hash = hash
 			self.csdl = csdl
+			@total_dpu = false
+			@created_at = false
 		end
 
-		# CSDL getter
+		#CSDL getter
 		def csdl
 			raise InvalidDataError, 'The CSDL is not available' unless !@csdl.nil?
-			@csdl
+			return @csdl
 		end
 
-		# CSDL setter. Strips the incoming string and resets the hash if it's changed.
+		#CSDL setter. Strips the incoming string and resets the hash if it's changed.
 		def csdl=(csdl)
 			if csdl.nil?
 				@csdl = nil
@@ -56,18 +40,30 @@ module DataSift
 			end
 		end
 
-		# Hash getter. If the hash has not yet been obtained the CSDL will be
-		# compiled first.
+		#Total DPU getter.
+		def total_dpu
+			compile() unless @total_dpu
+			return @total_dpu
+		end
+
+		#Created at getter.
+		def created_at
+			compile() unless @created_at
+			return @created_at
+		end
+
+		#Hash getter. If the hash has not yet been obtained the CSDL will be
+		#compiled first.
 		def hash
 			if @hash == false
 				compile()
 			end
 
-			@hash
+			return @hash
 		end
 
-		# Reset the hash to false. The effect of this is to mark the definition as
-		# requiring compilation.
+		#Reset the hash to false. The effect of this is to mark the definition as
+		#requiring compilation.
 		def clearHash()
 			@csdl = '' unless !@csdl.nil?
 			@hash = false
@@ -75,8 +71,8 @@ module DataSift
 			@created_at = false
 		end
 
-		# Call the DataSift API to compile this definition. On success it will
-		# store the returned hash.
+		#Call the DataSift API to compile this definition. On success it will
+		#store the returned hash.
 		def compile()
 			raise InvalidDataError, 'Cannot compile an empty definition.' unless @csdl.length > 0
 
@@ -107,28 +103,59 @@ module DataSift
 				when 400
 					raise CompileFailedError, err
 				else
-					raise CompileFailedError, 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.inspect + ']'
+					raise APIError('Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.inspect + ']', err.http_code)
 				end
 			end
 		end
 
-		# Call the DataSift API to get the DPU for this definition. Returns an
-		# array containing...
-		#   detail => The breakdown of running the rule
-		#   dpu => The total DPU of the rule
-		#
+		#Call the DataSift API to validate this definition. On success it will
+		#store the details in the response.
+		def validate()
+			raise InvalidDataError, 'Cannot validate an empty definition.' unless @csdl.length > 0
+
+			begin
+				res = @user.callAPI('validate', { 'csdl' => @csdl })
+
+				if res.has_key?('dpu')
+					@total_dpu = Float(res['dpu'])
+				else
+					raise CompileFailedError, 'Validated successfully but no DPU in the response'
+				end
+
+				if res.has_key?('created_at')
+					@created_at = Date.parse(res['created_at'])
+				else
+					raise CompileFailedError, 'Validated successfully but no created_at in the response'
+				end
+			rescue APIError => err
+				clearHash()
+
+				case err.http_code
+				when 400
+					raise CompileFailedError, err
+				else
+					raise APIError('Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.inspect + ']', err.http_code)
+				end
+			end
+		end
+
+		#Call the DataSift API to get the DPU for this definition. Returns
+		#=== Returns
+		#A Hash containing...
+		#* +detail+ - The breakdown of running the rule
+		#* +dpu+ - The total DPU of the rule
 		def getDPUBreakdown()
 			raise InvalidDataError, "Cannot get the DPU for an empty definition." unless @csdl.length > 0
 
 			@user.callAPI('dpu', { 'hash' => self.hash })
 		end
 
-		# Call the DataSift API to get buffered interactions.
-		# === Parameters
-		#
-		# * +count+ - Optional number of interactions to return (max 200).
-		# * +from_id+ - Optional start ID.
-		#
+		#Call the DataSift API to get buffered interactions.
+		#=== Parameters
+		#* +count+ - Optional number of interactions to return (max 200).
+		#* +from_id+ - Optional start ID.
+		#=== Returns
+		#An array of Hashes where each Hash is an interaction.
 		def getBuffered(count = false, from_id = false)
 			raise InvalidDataError, "Cannot get buffered interactions for an empty definition." unless @csdl.length > 0
 
@@ -146,15 +173,28 @@ module DataSift
 
 			raise APIError, 'No data in the response' unless retval.has_key?('stream')
 
-			retval['stream']
+			return retval['stream']
+		end
+
+		#Create a Historics query based on this Definition.
+		#=== Parameters
+		#* +start_date+ - The start date for a new Historics query.
+		#* +end_date+ - The end date for a new Historics query.
+		#* +sources+ - An array of sources for a new Historics query.
+		#* +name+ - The name for a new Historics query.
+		#* +sample+ - The sample rate for the new Historics query.
+		#=== Returns
+		#A Historic object.
+		def createHistoric(start_date, end_date, sources, sample, name)
+			return Historic.new(@user, hash, start_date, end_date, sources, sample, name)
 		end
 
-		# Returns a StreamConsumer-derived object for this definition, for the
-		# given type.
-		# === Parameters
-		#
-		# * +type+ - The consumer type for which to construct a consumer.
-		#
+		#Returns a StreamConsumer-derived object for this definition, for the
+		#given type.
+		#=== Parameters
+		#* +type+ - The consumer type for which to construct a consumer.
+		#=== Returns
+		#A StreamConsumer-derived object.
 		def getConsumer(type = nil, on_interaction = nil, on_stopped = nil)
 			StreamConsumer.factory(@user, type, self)
 		end

data/lib/DataSift/exceptions.rb

@@ -1,15 +1,32 @@
 module DataSift
-	class AccessDeniedError < StandardError; end
-	class CompileFailedError < StandardError; end
-	class InvalidDataError < StandardError; end
-	class NotYetImplementedError < StandardError; end
-	class RateLimitExceededError < StandardError; end
-	class StreamError < StandardError; end
+	# All exceptions inherit from DataSiftError.
+	class DataSiftError < StandardError; end
 
-	class APIError < StandardError
+	# Thrown when access to the API is denied.
+	class AccessDeniedError < DataSiftError; end
+
+	# Thrown when CSDL validation or compilation fails.
+	class CompileFailedError < DataSiftError; end
+
+	# Thrown whenever invalid data is encountered in the library.
+	class InvalidDataError < DataSiftError; end
+
+	# Thrown when you exceed your API rate limit.
+	class RateLimitExceededError < DataSiftError; end
+
+	# Thrown when error occur while reading streaming data.
+	class StreamError < DataSiftError; end
+
+	#Thrown when an error is found in API responses.
+	#These errors optionally carry the HTTP error code.
+	class APIError < DataSiftError
+		#The HTTP status code.
 		attr_reader :http_code
 
-		def initialize(http_code)
+		#Constructor.
+		#=== Parameters
+		#* +http_code+ - Optional HTTP status code.
+		def initialize(http_code = -1)
 			@http_code = http_code
 		end
 	end

data/lib/DataSift/historic.rb

@@ -0,0 +1,321 @@
+require 'date'
+
+module DataSift
+	#The Historic class represents a Historics query.
+	class Historic
+		#Get a list of Historics queries in your account.
+		#=== Parameters
+		#* +user+ - The user object making the request.
+		#* +page+ - The page number to get.
+		#* +per_page+ - The number of items per page.
+		#=== Returns
+		#A Hash containing...
+		#* +count+ - The total number of Historics queries in your account.
+		#* +historics+ - An array of Hashes where each Hash is a Historics query.
+		def self.list(user, page = 1, per_page = 20)
+			begin
+				res = user.callAPI(
+					'historics/get', {
+						'page' => page,
+						'max' => per_page
+					})
+
+				retval = { 'count' => res['count'], 'historics' => [] }
+				for historic in res['data']
+					retval['historics'].push(new(user, historic))
+				end
+				retval
+			rescue APIError => err
+				case err.http_code
+				when 400
+					# Missing or invalid parameters
+					raise InvalidDataError, err
+				else
+					raise APIError.new(err.http_code), 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.message + ']'
+				end
+			end
+		end
+
+		#The ID of this Historics query.
+		attr_reader :playback_id
+		#The stream hash which this Historics query is executing.
+		attr_reader :stream_hash
+		#The friendly name for this Historics query.
+		attr_reader :name
+		#The start date for this Historics query.
+		attr_reader :start_date
+		#The end date for this Historics query.
+		attr_reader :end_date
+		#The date/time when this Historics query was created.
+		attr_reader :created_at
+		#The current status of this Historics query.
+		attr_reader :status
+		#The current progress in percent of this Historics query.
+		attr_reader :progress
+		#The data sources for which this Historics query is looking.
+		attr_reader :sources
+		#The sample percentage that this Historics query will match.
+		attr_reader :sample
+		#The DPU cost of running this Historics query.
+		attr_reader :dpus
+		#The data availability for this Historics query.
+		attr_reader :volume_info
+		#True if this Historics query has been deleted.
+		attr_reader :is_deleted
+
+		#Constructor. Pass all parameters to create a new Historics query, or provide a User object and a playback_id as the hash parameter to load an existing query from the API.
+		#=== Parameters
+		#* +user+ - The DataSift::User object.
+		#* +hash+ - Either a stream_hash, an array containing the Historics query data or a playback ID.
+		#* +start_date+ - The start date for a new Historics query.
+		#* +end_date+ - The end date for a new Historics query.
+		#* +sources+ - An array of sources for a new Historics query.
+		#* +name+ - The name for a new Historics query.
+		#* +sample+ - The sample rate for the new Historics query.
+		def initialize(user, hash, start_date = false, end_date = false, sources = false, sample = false, name = false)
+			raise InvalidDataError, 'Please supply a valid User object when creating a Historic object.' unless user.is_a? DataSift::User
+			@user = user
+
+			if not start_date
+				if hash.kind_of?(Hash)
+					# Initialising from an array
+					@playback_id = hash['id']
+					initFromArray(hash)
+				else
+					# Fetching from the API
+					@playback_id = hash
+					reloadData()
+				end
+			else
+				# Creating a new Historic query, make sure we have all the parameters
+				raise InvalidDataError,
+					'Please supply all parameters when creating a new Historics query' unless
+						start_date != false and end_date != false and sources != false and
+						name != false and sample != false
+
+				# Convert and validate the parameters as required
+				hash = hash.hash if hash.is_a? DataSift::Definition
+				start_date = DateTime.strftime(start_date, '%s') unless start_date.is_a? Date
+				end_date = DateTime.strptime(end_date, '%s') unless end_date.is_a? Date
+				raise InvalidDataError, 'Please supply an array of sources' unless sources.kind_of?(Array)
+
+				@playback_id  = false
+				@stream_hash  = hash
+				@start_date   = start_date
+				@end_date     = end_date
+				@sources      = sources
+				@name         = name
+				@sample       = sample
+				@progress     = 0
+				@dpus         = false
+				@availability = {}
+				@volume_info  = {}
+				@is_deleted   = false
+			end
+		end
+
+		#Reload the data for this object from the API.
+		def reloadData()
+			#Can't do this if we've been deleted
+			raise InvalidDataError, 'Cannot reload the data for a deleted Historics query' unless not @is_deleted
+
+			#Can't do this without a playback ID
+			raise InvalidDataError, 'Cannot reload the data with a Historics query with no playback ID' unless @playback_id
+
+			begin
+				initFromArray(@user.callAPI('historics/get', { 'id' => @playback_id }))
+			rescue APIError => err
+				case err.http_code
+				when 400
+					raise InvalidDataError, err
+				else
+					raise APIError.new(err.http_code), 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.message + ']'
+				end
+			end
+		end
+
+		#Initialise this obejct from the data in a Hash.
+		#=== Parameters
+		#* +data+ - The Hash containing the data.
+		def initFromArray(data)
+			raise APIError, 'No playback ID in the response' unless data.has_key?('id')
+			raise APIError, 'Incorrect playback ID in the response' unless not @playback_id or data['id'] == @playback_id
+			@playback_id = data['id']
+
+			raise APIError, 'No definition hash in the response' unless data.has_key?('definition_id')
+			@stream_hash = data['definition_id']
+
+			raise APIError, 'No name in the response' unless data.has_key?('name')
+			@name = data['name']
+
+			raise APIError, 'No start timestamp in the response' unless data.has_key?('start')
+			@start_date = DateTime.strptime(String(data['start']), '%s')
+
+			raise APIError, 'No end timestamp in the response' unless data.has_key?('end')
+			@end_date = DateTime.strptime(String(data['end']), '%s')
+
+			raise APIError, 'No created at timstamp in the response' unless data.has_key?('created_at')
+			@created_at = DateTime.strptime(String(data['created_at']), '%s')
+
+			raise APIError, 'No status in the response' unless data.has_key?('status')
+			@status = data['status']
+
+			raise APIError, 'No progress in the response' unless data.has_key?('progress')
+			@progress = data['progress']
+
+			raise APIError, 'No sources in the response' unless data.has_key?('sources')
+			@sources = data['sources']
+
+			raise APIError, 'No sample in the response' unless data.has_key?('sample')
+			@sample = data['sample']
+
+			raise APIError, 'No volume info in the response' unless data.has_key?('volume_info')
+			@volume_info = data['volume_info']
+
+			@is_deleted = (@status == 'deleted')
+
+			return true
+		end
+
+		#Getter for the playback ID. If the Historics query has not yet been
+		#prepared that will be done automagically to obtain the playback ID.
+		def hash
+			if @playback_id == false
+				prepare()
+			end
+
+			@playback_id
+		end
+
+		#Name setter. Updates via the API if this Historics query has already
+		#been prepared.
+		def name=(new_name)
+			raise InvalidDataError, 'Cannot set the name of a deleted Historics query' unless not @is_deleted
+
+			if not @playback_id
+				@name = new_name
+			else
+				@user.callAPI('historics/update', { 'id' => @playback_id, 'name' => new_name })
+				reloadData()
+			end
+		end
+
+		#Call the DataSift API to prepare this Historics query
+		def prepare()
+			raise InvalidDataError, 'Cannot prepare a deleted Historics query' unless not @is_deleted
+			raise InvalidDataError, 'This Historics query has already been prepared' unless not @playback_id
+
+			begin
+				res = @user.callAPI(
+					'historics/prepare', {
+						'hash' => @stream_hash,
+						'start' => Integer(@start_date.strftime('%s')),
+						'end' => Integer(@end_date.strftime('%s')),
+						'name' => @name,
+						'sources' => @sources.join(',')
+					})
+
+				raise InvalidDataError, 'Prepared successfully but no playback ID in the response' unless res.has_key?('id')
+				@playback_id = res['id']
+
+				raise InvalidDataError, 'Prepared successfully but no DPU cost in the response' unless res.has_key?('dpus')
+				@dpus = res['dpus']
+
+				raise InvalidDataError, 'Prepared successfully but no availability in the response' unless res.has_key?('availability')
+				@availability = res['availability']
+			rescue APIError => err
+				case err.http_code
+				when 400
+					raise InvalidDataError, err
+				else
+					raise APIError.new(err.http_code), 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.message + ']'
+				end
+			end
+
+			# Reload the data so we get the created_at date, initial status and the rest.
+			reloadData()
+		end
+
+		#Start this Historics query.
+		def start()
+			raise InvalidDataError, 'Cannot start a deleted Historics query' unless not @is_deleted
+			raise InvalidDataError, 'Cannot start a Historics query that hasn\'t been prepared' unless @playback_id
+
+			begin
+				res = @user.callAPI('historics/start', { 'id' => @playback_id })
+			rescue APIError => err
+				case err.http_code
+				when 400
+					# Missing or invalid parameters
+					raise InvalidDataError, err
+				when 404
+					# Historics query not found
+					raise InvalidDataError, err
+				else
+					raise APIError.new(err.http_code), 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.message + ']'
+				end
+			end
+		end
+
+		#Stop this Historics query.
+		def stop()
+			raise InvalidDataError, 'Cannot stop a deleted Historics query' unless not @is_deleted
+			raise InvalidDataError, 'Cannot stop a Historics query that hasn\'t been prepared' unless @playback_id
+
+			begin
+				res = @user.callAPI('historics/stop', { 'id' => @playback_id })
+			rescue APIError => err
+				case err.http_code
+				when 400
+					# Missing or invalid parameters
+					raise InvalidDataError, err
+				when 404
+					# Historics query not found
+					raise InvalidDataError, err
+				else
+					raise APIError.new(err.http_code), 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.message + ']'
+				end
+			end
+		end
+
+		#Delete this Historics query.
+		def delete()
+			raise InvalidDataError, 'Cannot delete a deleted Historics query' unless not @is_deleted
+			raise InvalidDataError, 'Cannot delete a Historics query that hasn\'t been prepared' unless @playback_id
+
+			begin
+				@user.callAPI('historics/delete', { 'id' => @playback_id })
+				@is_deleted = true
+			rescue APIError => err
+				case err.http_code
+				when 400
+					# Missing or invalid parameters
+					raise InvalidDataError, err
+				when 404
+					# Historics query not found
+					raise InvalidDataError, err
+				else
+					raise APIError.new(err.http_code), 'Unexpected APIError code: ' + err.http_code.to_s + ' [' + err.message + ']'
+				end
+			end
+		end
+
+		#Get a page of Push subscriptions for this Historics query, where each
+		#page contains up to per_page items. Results will be returned in the
+		#order requested.
+		#=== Parameters
+		#* +page+ - The page number to get.
+		#* +per_page+ - The number of items per page.
+		#* +order_by+ - The field by which to order the results.
+		#* +order_dir+ - Ascending or descending.
+		#* +include_finished+ - True to include subscriptions against finished Historics queries.
+		#=== Returns
+		#A Hash containing...
+		#* +count+ - The total number of Push subscriptions in your account.
+		#* +subscriptions+ - An array of Hashes where each Hash is a Push subscription.
+		def getPushSubscriptions(page = 1, per_page = 20, order_by = PushSubscription::ORDERBY_CREATED_AT, order_dir = PushSubscription::ORDERDIR_ASC)
+			return PushSubscription.list(@user, page, per_page, order_by, order_dir, true, 'playback_id', @playback_id)
+		end
+	end
+
+end