Class: PredictionIO::EventClient

Inherits:
Object
  • Object
show all
Defined in:
lib/predictionio/event_client.rb

Overview

This class contains methods that interface with the PredictionIO Event Server via the PredictionIO Event API using REST requests.

Many REST request methods support optional arguments. They can be supplied to these methods as Hash’es. For a complete reference, please visit prediction.io.

High-performance Asynchronous Backend

All REST request methods come in both synchronous and asynchronous flavors. Both flavors accept the same set of arguments. In addition, all synchronous request methods can instead accept a PredictionIO::AsyncResponse object generated from asynchronous request methods as its first argument. In this case, the method will block until a response is received from it.

Any network reconnection and request retry is automatically handled in the background. Exceptions will be thrown after a request times out to avoid infinite blocking.

Installation

The easiest way is to use RubyGems:

gem install predictionio

Synopsis

In most cases, using synchronous methods. If you have a special performance requirement, you may want to take a look at asynchronous methods.

Instantiate an EventClient

# Include the PredictionIO SDK
require 'predictionio'

client = PredictionIO::EventClient.new(<access_key>)

Import a User Record from Your App (with asynchronous/non-blocking

requests)

#
# (your user registration logic)
#

uid = get_user_from_your_db()

# PredictionIO call to create user
response = client.aset_user(uid)

#
# (other work to do for the rest of the page)
#

begin
  # PredictionIO call to retrieve results from an asynchronous response
  result = client.set_user(response)
rescue PredictionIO::EventClient::NotCreatedError => e
  log_and_email_error(...)
end

Import a User Action (Rate) from Your App (with synchronous/blocking

requests)
# PredictionIO call to record the view action
begin
  result = client.record_user_action_on_item('rate', 'foouser',
                                             'baritem',
                                             'rating' => 4)
rescue PredictionIO::EventClient::NotCreatedError => e
  ...
end

Defined Under Namespace

Classes: NotCreatedError

Instance Method Summary collapse

Constructor Details

#initialize(access_key, apiurl = 'http://localhost:7070', threads = 1, thread_timeout = 60) ⇒ EventClient

Create a new PredictionIO Event Client with defaults:

  • 1 concurrent HTTP(S) connections (threads)

  • API entry point at localhost:7070 (apiurl)

  • a 60-second timeout for each HTTP(S) connection (thread_timeout)



101
102
103
104
 
# File 'lib/predictionio/event_client.rb', line 101

def initialize(access_key, apiurl = 'http://localhost:7070', threads = 1, thread_timeout = 60)
  @access_key = access_key
  @http = PredictionIO::Connection.new(URI(apiurl), threads, thread_timeout)
end

Instance Method Details

#acreate_batch_event(payload) ⇒ Object

:category: Asynchronous Methods Asynchronously request to create a batch of event and return a PredictionIO::AsyncResponse object immediately.

Corresponding REST API method: POST /batch/events.json

See also #acreate_event.



151
152
153
154
155
 
# File 'lib/predictionio/event_client.rb', line 151

def acreate_batch_event(payload)
  @http.apost(PredictionIO::AsyncRequest.new(
    "/batch/events.json?accessKey=#{@access_key}", payload.to_json
  ))
end

#acreate_event(event, entity_type, entity_id, optional = {}) ⇒ Object

:category: Asynchronous Methods Asynchronously request to create an event and return a PredictionIO::AsyncResponse object immediately.

Corresponding REST API method: POST /events.json

See also #create_event.



128
129
130
131
132
133
134
135
 
# File 'lib/predictionio/event_client.rb', line 128

def acreate_event(event, entity_type, entity_id, optional = {})
  h = optional.with_indifferent_access
  h.key?('eventTime') || h['eventTime'] = DateTime.now.iso8601
  h['event'] = event
  h['entityType'] = entity_type
  h['entityId'] = entity_id
  @http.apost(PredictionIO::AsyncRequest.new(event_path_with_main_params(h), h.except(:channel).to_json))
end

#adelete_item(uid) ⇒ Object

:category: Asynchronous Methods Asynchronously request to delete an item and return a PredictionIO::AsyncResponse object immediately.

Corresponding REST API method: POST /events.json

See also #delete_item.



322
323
324
 
# File 'lib/predictionio/event_client.rb', line 322

def adelete_item(uid)
  acreate_event('$delete', 'item', uid)
end

#adelete_user(uid) ⇒ Object

:category: Asynchronous Methods Asynchronously request to delete a user and return a PredictionIO::AsyncResponse object immediately.

Corresponding REST API method: POST /events.json

See also #delete_user.



244
245
246
 
# File 'lib/predictionio/event_client.rb', line 244

def adelete_user(uid)
  acreate_event('$delete', 'user', uid)
end

#arecord_user_action_on_item(action, uid, iid, optional = {}) ⇒ Object

:category: Asynchronous Methods Asynchronously request to record an action on an item and return a PredictionIO::AsyncResponse object immediately.

Corresponding REST API method: POST /events.json

See also #record_user_action_on_item.



346
347
348
349
350
 
# File 'lib/predictionio/event_client.rb', line 346

def arecord_user_action_on_item(action, uid, iid, optional = {})
  optional['targetEntityType'] = 'item'
  optional['targetEntityId'] = iid
  acreate_event(action, 'user', uid, optional)
end

#aset_item(iid, optional = {}) ⇒ Object

:category: Asynchronous Methods Asynchronously request to set properties of an item and return a PredictionIO::AsyncResponse object immediately.

Corresponding REST API method: POST /events.json

See also #set_item.



268
269
270
 
# File 'lib/predictionio/event_client.rb', line 268

def aset_item(iid, optional = {})
  acreate_event('$set', 'item', iid, optional)
end

#aset_user(uid, optional = {}) ⇒ Object

:category: Asynchronous Methods Asynchronously request to set properties of a user and return a PredictionIO::AsyncResponse object immediately.

Corresponding REST API method: POST /events.json

See also #set_user.



190
191
192
 
# File 'lib/predictionio/event_client.rb', line 190

def aset_user(uid, optional = {})
  acreate_event('$set', 'user', uid, optional)
end

#aunset_item(iid, optional) ⇒ Object

:category: Asynchronous Methods Asynchronously request to unset properties of an item and return a PredictionIO::AsyncResponse object immediately.

properties must be a non-empty Hash.

Corresponding REST API method: POST /events.json

See also #unset_item.



294
295
296
297
298
299
300
 
# File 'lib/predictionio/event_client.rb', line 294

def aunset_item(iid, optional)
  optional.key?('properties') ||
    fail(ArgumentError, 'properties must be present when event is $unset')
  optional['properties'].empty? &&
    fail(ArgumentError, 'properties cannot be empty when event is $unset')
  acreate_event('$unset', 'item', iid, optional)
end

#aunset_user(uid, optional) ⇒ Object

:category: Asynchronous Methods Asynchronously request to unset properties of a user and return a PredictionIO::AsyncResponse object immediately.

properties must be a non-empty Hash.

Corresponding REST API method: POST /events.json

See also #unset_user.



216
217
218
219
220
221
222
 
# File 'lib/predictionio/event_client.rb', line 216

def aunset_user(uid, optional)
  optional.key?('properties') ||
    fail(ArgumentError, 'properties must be present when event is $unset')
  optional['properties'].empty? &&
    fail(ArgumentError, 'properties cannot be empty when event is $unset')
  acreate_event('$unset', 'user', uid, optional)
end

#create_batch_event(payload) ⇒ Object

:category: Synchronous Methods Synchronously request to create an event and block until a response is received.

See also #acreate_event.

call-seq: create_batch_event(payload) create_batch_event(async_response)



179
180
181
 
# File 'lib/predictionio/event_client.rb', line 179

def create_batch_event(payload)
  sync_events(:acreate_batch_event, payload)
end

#create_event(*args) ⇒ Object

:category: Synchronous Methods Synchronously request to create an event and block until a response is received.

See also #acreate_event.

call-seq: create_event(event, entity_type, entity_id, optional = {}) create_event(async_response)



166
167
168
 
# File 'lib/predictionio/event_client.rb', line 166

def create_event(*args)
  sync_events(:acreate_event, *args)
end

#delete_item(*args) ⇒ Object

:category: Synchronous Methods Synchronously request to delete an item and block until a response is received.

See also #adelete_item.

call-seq: delete_item(uid) delete_item(async_response)



335
336
337
 
# File 'lib/predictionio/event_client.rb', line 335

def delete_item(*args)
  sync_events(:adelete_item, *args)
end

#delete_user(*args) ⇒ Object

:category: Synchronous Methods Synchronously request to delete a user and block until a response is received.

See also #adelete_user.

call-seq: delete_user(uid) delete_user(async_response)



257
258
259
 
# File 'lib/predictionio/event_client.rb', line 257

def delete_user(*args)
  sync_events(:adelete_user, *args)
end

#event_path_with_main_params(options) ⇒ Object 



137
138
139
140
141
142
 
# File 'lib/predictionio/event_client.rb', line 137

def event_path_with_main_params(options)
  result = "/events.json?accessKey=#{@access_key}"
  result += "&channel=#{options[:channel]}" if options[:channel]

  result
end

#get_status ⇒ Object

Returns PredictionIO’s status in string.



112
113
114
115
116
117
118
119
 
# File 'lib/predictionio/event_client.rb', line 112

def get_status
  status = @http.aget(PredictionIO::AsyncRequest.new('/')).get
  begin
    status.body
  rescue
    status
  end
end

#pending_requests ⇒ Object

Returns the number of pending requests within the current client.



107
108
109
 
# File 'lib/predictionio/event_client.rb', line 107

def pending_requests
  @http.packages.size
end

#record_user_action_on_item(*args) ⇒ Object

:category: Synchronous Methods Synchronously request to record an action on an item and block until a response is received.

See also #arecord_user_action_on_item.

call-seq: record_user_action_on_item(action, uid, iid, optional = {}) record_user_action_on_item(async_response)



361
362
363
 
# File 'lib/predictionio/event_client.rb', line 361

def record_user_action_on_item(*args)
  sync_events(:arecord_user_action_on_item, *args)
end

#set_item(*args) ⇒ Object

:category: Synchronous Methods Synchronously request to set properties of an item and block until a response is received.

See also #aset_item.

call-seq: set_item(iid, properties = {}, optional = {}) set_item(async_response)



281
282
283
 
# File 'lib/predictionio/event_client.rb', line 281

def set_item(*args)
  sync_events(:aset_item, *args)
end

#set_user(*args) ⇒ Object

:category: Synchronous Methods Synchronously request to set properties of a user and block until a response is received.

See also #aset_user.

call-seq: set_user(uid, optional = {}) set_user(async_response)



203
204
205
 
# File 'lib/predictionio/event_client.rb', line 203

def set_user(*args)
  sync_events(:aset_user, *args)
end

#unset_item(*args) ⇒ Object

:category: Synchronous Methods Synchronously request to unset properties of an item and block until a response is received.

See also #aunset_item.

call-seq: unset_item(iid, properties, optional = {}) unset_item(async_response)



311
312
313
 
# File 'lib/predictionio/event_client.rb', line 311

def unset_item(*args)
  sync_events(:aunset_item, *args)
end

#unset_user(*args) ⇒ Object

:category: Synchronous Methods Synchronously request to unset properties of a user and block until a response is received.

See also #aunset_user.

call-seq: unset_user(uid, optional) unset_user(async_response)



233
234
235
 
# File 'lib/predictionio/event_client.rb', line 233

def unset_user(*args)
  sync_events(:aunset_user, *args)
end