Class: MyGengo::API

Inherits:
Object
  • Object
show all
Defined in:
lib/mygengo-ruby/api_handler.rb

Overview

The only real class that ever needs to be instantiated.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(opts) ⇒ API

Creates a new API handler to shuttle calls/jobs/etc over to the Gengo translation API.

Options: opts - A hash containing the api key, the api secret key, the API version (defaults to 1), whether to use the sandbox API, and an optional custom user agent to send.



26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/mygengo-ruby/api_handler.rb', line 26

def initialize(opts)
	# Consider this an example of the object you need to pass.
	@opts = {
		:public_key => '',
		:private_key => '',
		:api_version => '1.1',
		:sandbox => false,
		:user_agent => "Gengo Ruby Library; Version #{MyGengo::Config::VERSION}; http://gengo.com/;",
		:debug => false,
	}.merge(opts)

	# Let's go ahead and separate these out, for clarity...
	@debug = @opts[:debug]
	@api_host = (@opts[:sandbox] == true ? MyGengo::Config::SANDBOX_API_HOST : MyGengo::Config::API_HOST)

	# More of a public "check this" kind of object.
	@client_info = {"VERSION" => MyGengo::Config::VERSION}
end

Instance Attribute Details

#api_host ⇒ Object

Returns the value of attribute api_host.



17
18
19
 
# File 'lib/mygengo-ruby/api_handler.rb', line 17

def api_host
  @api_host
end

#client_info ⇒ Object

Returns the value of attribute client_info.



19
20
21
 
# File 'lib/mygengo-ruby/api_handler.rb', line 19

def client_info
  @client_info
end

#debug ⇒ Object

Returns the value of attribute debug.



18
19
20
 
# File 'lib/mygengo-ruby/api_handler.rb', line 18

def debug
  @debug
end

Instance Method Details

#deleteTranslationJob(params = {}) ⇒ Object

Deletes a job.

Options: id - The ID of the job you want to delete.



384
385
386
387
 
# File 'lib/mygengo-ruby/api_handler.rb', line 384

def deleteTranslationJob(params = {})
        params[:is_delete] = true
  self.get_from_mygengo('translate/job/:id'.gsub(':id', params.delete(:id).to_s), params)
end

#deleteTranslationJobs(params = {}) ⇒ Object

Deletes multiple jobs.

Options: ids - An Array of job IDs you want to delete.



393
394
395
396
397
398
399
400
401
 
# File 'lib/mygengo-ruby/api_handler.rb', line 393

def deleteTranslationJobs(params = {})
  if params[:ids] and params[:ids].kind_of?(Array)
    params[:job_ids] = params[:ids].map { |i| i.to_s() }.join(',')
    params.delete(:ids)
  end

        params[:is_delete] = true
  self.get_from_mygengo('translate/jobs', params)
end

#determineTranslationCost(params = {}) ⇒ Object

Mirrors the bulk Translation call, but just returns an estimated cost.



319
320
321
322
323
324
325
326
327
 
# File 'lib/mygengo-ruby/api_handler.rb', line 319

def determineTranslationCost(params = {})
  is_upload = params.delete(:is_upload)

  if is_upload
    self.upload_to_mygengo('translate/service/quote/file', params)
  else
    self.send_to_mygengo('translate/service/quote', params)
  end
end

#get_from_mygengo(endpoint, params = {}) ⇒ Object

The “GET” method; handles requesting basic data sets from Gengo and converting the response to a Ruby hash/object.

Options: endpoint - String/URL to request data from. params - Data necessary for request (keys, etc). Generally taken care of by the requesting instance.



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/mygengo-ruby/api_handler.rb', line 61

def get_from_mygengo(endpoint, params = {})
	# Do this small check here...
          is_delete = params.delete(:is_delete)
          is_download_file = params.delete(:is_download)

          # The first part of the object we're going to encode and use in our request to Gengo. The signing process
	# is a little annoying at the moment, so bear with us...
	query = params.reduce({}) {|hash_thus_far, (param_key, param_value)|
            hash_thus_far.merge(
                param_key.to_sym => param_value.to_s
            )
          }

          query[:api_key] = @opts[:public_key]
          query[:ts] = Time.now.gmtime.to_i.to_s

	endpoint << "?api_sig=" + signature_of(query[:ts])
	endpoint << '&' + query.map { |k, v| "#{k}=#{urlencode(v)}" }.join('&')

          uri = "/v#{@opts[:api_version]}/" + endpoint
          headers = {
              'Accept' => 'application/json',
              'User-Agent' => @opts[:user_agent]
          }

          if is_delete
              req = Net::HTTP::Delete.new(uri, headers)
          else
              req = Net::HTTP::Get.new(uri, headers)
          end

	http = Net::HTTP.start(@api_host, 80)
          if @debug
            http.set_debug_output($stdout)
          end
          http.read_timeout = 5*60
          resp = http.request(req)

	if is_download_file.nil?
            json = JSON.parse(resp.body)
            if json['opstat'] != 'ok'
                raise MyGengo::Exception.new(json['opstat'], json['err']['code'].to_i, json['err']['msg'])
            end

            # Return it if there are no problems, nice...
            return json
          else
            return resp.body
          end

end

#getAccountBalance(params = {}) ⇒ Object

Returns a Ruby-hash of the balance for the authenticated account. No args required!

Options: None - N/A



240
241
242
 
# File 'lib/mygengo-ruby/api_handler.rb', line 240

def getAccountBalance(params = {})
  self.get_from_mygengo('account/balance', params)
end

#getAccountStats(params = {}) ⇒ Object

Returns a Ruby-hash of the stats for the current account. No arguments required!

Options: None - N/A



232
233
234
 
# File 'lib/mygengo-ruby/api_handler.rb', line 232

def getAccountStats(params = {})
  self.get_from_mygengo('account/stats', params)
end

#getGlossary(params = {}) ⇒ Object

Gets one glossary that belongs to the authenticated user



422
423
424
 
# File 'lib/mygengo-ruby/api_handler.rb', line 422

def getGlossary(params = {})
    self.get_from_mygengo('translate/glossary/:id'.gsub(':id', params.delete(:id).to_s), params)
end

#getGlossaryFile(params = {}) ⇒ Object

Downloads one glossary that belongs to the authenticated user



427
428
429
430
 
# File 'lib/mygengo-ruby/api_handler.rb', line 427

def getGlossaryFile(params = {})
    params[:is_download] = true
    self.get_from_mygengo('translate/glossary/download/:id'.gsub(':id', params.delete(:id).to_s), params)
end

#getGlossaryList(params = {}) ⇒ Object

Gets list of glossaries that belongs to the authenticated user



417
418
419
 
# File 'lib/mygengo-ruby/api_handler.rb', line 417

def getGlossaryList(params = {})
    self.get_from_mygengo('translate/glossary', params)
end

#getServiceLanguagePairs(params = {}) ⇒ Object

Gets information about currently supported language pairs.

Options: lc_src - Optional language code to filter on.



407
408
409
 
# File 'lib/mygengo-ruby/api_handler.rb', line 407

def getServiceLanguagePairs(params = {})
        self.get_from_mygengo('translate/service/language_pairs', params)
end

#getServiceLanguages(params = {}) ⇒ Object

Pulls down currently supported languages.



412
413
414
 
# File 'lib/mygengo-ruby/api_handler.rb', line 412

def getServiceLanguages(params = {})
  self.get_from_mygengo('translate/service/languages', params)
end

#getTranslationJob(params = {}) ⇒ Object

Given an ID, pulls down information concerning that job from Gengo.

id - The ID of a job to check. pre_mt - Optional, get a machine translation if the human translation is not done.



286
287
288
 
# File 'lib/mygengo-ruby/api_handler.rb', line 286

def getTranslationJob(params = {})
  self.get_from_mygengo('translate/job/:id'.gsub(':id', params.delete(:id).to_s), params)
end

#getTranslationJobBatch(params = {}) ⇒ Object

Pulls a group of jobs that were previously submitted together.

id - Required, the ID of a job that you want the batch/group of.



307
308
309
 
# File 'lib/mygengo-ruby/api_handler.rb', line 307

def getTranslationJobBatch(params = {})
  self.get_from_mygengo('translate/jobs/group/:group_id'.gsub(':group_id', params.delete(:group_id).to_s), params)
end

#getTranslationJobComments(params = {}) ⇒ Object

Get all comments (the history) from a given job.

Options: id - The ID of the job to get comments for.



342
343
344
 
# File 'lib/mygengo-ruby/api_handler.rb', line 342

def getTranslationJobComments(params = {})
  self.get_from_mygengo('translate/job/:id/comments'.gsub(':id', params.delete(:id).to_s), params)
end

#getTranslationJobFeedback(params = {}) ⇒ Object

Returns the feedback you’ve submitted for a given job.

Options: id - The ID of the translation job you’re retrieving comments from.



350
351
352
 
# File 'lib/mygengo-ruby/api_handler.rb', line 350

def getTranslationJobFeedback(params = {})
  self.get_from_mygengo('translate/job/:id/feedback'.gsub(':id', params.delete(:id).to_s), params)
end

#getTranslationJobPreviewImage(params = {}) ⇒ Object

Returns a preview image for a job.

Options: id - The ID of the job you want a preview image of.



375
376
377
378
 
# File 'lib/mygengo-ruby/api_handler.rb', line 375

def getTranslationJobPreviewImage(params = {})
  params[:is_download] = true
  self.get_from_mygengo('translate/job/:id/preview'.gsub(':id', params.delete(:id).to_s), params)
end

#getTranslationJobRevision(params = {}) ⇒ Object

Get a specific revision to a job.

Options: id - The ID of the translation job you’re getting revisions from. rev_id - The ID of the revision you’re looking up.



367
368
369
 
# File 'lib/mygengo-ruby/api_handler.rb', line 367

def getTranslationJobRevision(params = {})
  self.get_from_mygengo('translate/job/:id/revisions/:revision_id'.gsub(':id', params.delete(:id).to_s).gsub(':revision_id', params.delete(:rev_id).to_s), params)
end

#getTranslationJobRevisions(params = {}) ⇒ Object

Gets a list of the revision resources for a job. Revisions are created each time a translator updates the text.

Options: id - The ID of the translation job you’re getting revisions from.



358
359
360
 
# File 'lib/mygengo-ruby/api_handler.rb', line 358

def getTranslationJobRevisions(params = {})
  self.get_from_mygengo('translate/job/:id/revisions'.gsub(':id', params.delete(:id).to_s), params)
end

#getTranslationJobs(params = {}) ⇒ Object

Pulls down a list of recently submitted jobs, allows some filters.

status - Optional. “unpaid”, “available”, “pending”, “reviewable”, “approved”, “rejected”, or “canceled”. timestamp_after - Optional. Epoch timestamp from which to filter submitted jobs. count - Optional. Defaults to 10.



295
296
297
298
299
300
301
302
 
# File 'lib/mygengo-ruby/api_handler.rb', line 295

def getTranslationJobs(params = {})
  if params[:ids] and params[:ids].kind_of?(Array)
    params[:ids] = params[:ids].map { |i| i.to_s() }.join(',')
    self.get_from_mygengo('translate/jobs/:ids'.gsub(':ids', params.delete(:ids)))
  else
    self.get_from_mygengo('translate/jobs', params)
  end
end

#getTranslationOrderJobs(params = {}) ⇒ Object

Pulls a group of jobs that were previously submitted together.

id - Required, the ID of a job that you want the batch/group of.



314
315
316
 
# File 'lib/mygengo-ruby/api_handler.rb', line 314

def getTranslationOrderJobs(params = {})
  self.get_from_mygengo('translate/order/:order_id'.gsub(':order_id', params.delete(:order_id).to_s), params)
end

#postTranslationJob(params = {}) ⇒ Object

Posts a translation job over to Gengo, returns a response indicating whether the submission was successful or not. Param list is quite expansive here, pay attention…

Options: job - A job is a hash of data describing what you want translated. See the examples included for more information on what this should be. (type/slug/body_src/lc_src/lc_tgt/tier/auto_approve/comment/callback_url/custom_data)



250
251
252
 
# File 'lib/mygengo-ruby/api_handler.rb', line 250

def postTranslationJob(params = {})
  self.send_to_mygengo('translate/job', params)
end

#postTranslationJobComment(params = {}) ⇒ Object

Post a comment for a translator or Gengo on a job.

Options: id - The ID of the job you’re commenting on. comment - The comment to put on the job.



334
335
336
 
# File 'lib/mygengo-ruby/api_handler.rb', line 334

def postTranslationJobComment(params = {})
  self.send_to_mygengo('translate/job/:id/comment'.gsub(':id', params.delete(:id).to_s), params)
end

#postTranslationJobs(params = {}) ⇒ Object

Much like the above, but takes a hash titled “jobs” that is multiple jobs, each with their own unique key.

Options: jobs - “Jobs” is a hash containing further hashes; each further hash is a job. This is best seen in the example code.



258
259
260
 
# File 'lib/mygengo-ruby/api_handler.rb', line 258

def postTranslationJobs(params = {})
  self.send_to_mygengo('translate/jobs', params)
end

#send_to_mygengo(endpoint, params = {}) ⇒ Object

The “POST” method; handles shuttling up encoded job data to Gengo for translation and such. Somewhat similar to the above methods, but depending on the scenario can get some strange exceptions, so we’re gonna keep them fairly separate for the time being. Consider for a merger down the road…

Options: endpoint - String/URL to post data to. params - Data necessary for request (keys, etc). Generally taken care of by the requesting instance.



121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/mygengo-ruby/api_handler.rb', line 121

def send_to_mygengo(endpoint, params = {})

  # Check if this is a put
    is_put = params.delete(:is_put)

	query = {
		:api_key => @opts[:public_key],
		:data => params.to_json.gsub('"', '\"'),
		:ts => Time.now.gmtime.to_i.to_s
	}

	url = URI.parse("http://#{@api_host}/v#{@opts[:api_version]}/#{endpoint}")
	http = Net::HTTP.new(url.host, url.port)
          http.read_timeout = 5*60
	if is_put
	  request = Net::HTTP::Put.new(url.path)
  else
	  request = Net::HTTP::Post.new(url.path)
  end

	request.add_field('Accept', 'application/json')
	request.add_field('User-Agent', @opts[:user_agent])

	request.content_type = 'application/x-www-form-urlencoded'
	request.body = {
		"api_sig" => signature_of(query[:ts]),
		"api_key" => urlencode(@opts[:public_key]),
		"data" => urlencode(params.to_json.gsub('\\', '\\\\')),
		"ts" => query[:ts].to_i.to_s
	}.map { |k, v| "#{k}=#{v}" }.flatten.join('&')

	if @debug
		http.set_debug_output($stdout)
	end

	resp = http.request(request)

	case resp
		when Net::HTTPSuccess, Net::HTTPRedirection
			json = JSON.parse(resp.body)

			if json['opstat'] != 'ok'
				raise MyGengo::Exception.new(json['opstat'], json['err']['code'].to_i, json['err']['msg'])
			end

			# Return it if there are no problems, nice...
			json
		else
			resp.error!
	end
end

#signature_of(ts) ⇒ Object

Creates an HMAC::SHA1 signature, signing the timestamp with the private key.



51
52
53
 
# File 'lib/mygengo-ruby/api_handler.rb', line 51

def signature_of(ts)
	OpenSSL::HMAC.hexdigest 'sha1', @opts[:private_key], ts
end

#updateTranslationJob(params = {}) ⇒ Object

Updates an already submitted job.

Options: id - The ID of a job to update. action - A hash describing the update to this job. See the examples for further documentation.



267
268
269
270
 
# File 'lib/mygengo-ruby/api_handler.rb', line 267

def updateTranslationJob(params = {})
  params[:is_put] = true
  self.send_to_mygengo('translate/job/:id'.gsub(':id', params.delete(:id).to_s), params)
end

#updateTranslationJobs(params = {}) ⇒ Object

Updates a group of already submitted jobs.

Options: jobs - An Array of job objects to update (job objects or ids) action - A String describing the update to this job. “approved”, “rejected”, etc - see Gengo docs.



277
278
279
280
 
# File 'lib/mygengo-ruby/api_handler.rb', line 277

def updateTranslationJobs(params = {})
  params[:is_put] = true
  self.send_to_mygengo('translate/jobs', {:jobs => params[:jobs], :action => params[:action]})
end

#upload_to_mygengo(endpoint, params = {}) ⇒ Object

The “UPLOAD” method; handles sending a file to the quote method

Options: endpoint - String/URL to post data to. params - Data necessary for request (keys, etc). Generally taken care of by the requesting instance.



178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/mygengo-ruby/api_handler.rb', line 178

def upload_to_mygengo(endpoint, params = {})

  # prepare the file_hash and append file_key to each job payload
        files_hash = params[:jobs].each_value.reduce({}) do |hash_thus_far, job_values|
          if job_values[:file_path].present?
              job_mime_type = MIME::Types.type_for(job_values[:file_path]).first.content_type
              file_hash_key = "file_#{hash_thus_far.length.to_s}".to_sym
              job_values[:file_key] = file_hash_key
              hash_thus_far[file_hash_key] = UploadIO.new(File.open(job_values[:file_path]), job_mime_type, File.basename(job_values[:file_path]))
          end
          hash_thus_far
        end

        url = URI.parse("http://#{@api_host}/v#{@opts[:api_version]}/#{endpoint}")

        http = Net::HTTP.new(url.host, url.port)
        http.read_timeout = 5*60

        call_timestamp = Time.now.gmtime.to_i.to_s

	the_hash = files_hash.merge({
		"api_sig" => signature_of(call_timestamp),
		"api_key" => @opts[:public_key],
		"data" =>params.to_json.gsub('\\', '\\\\'),
		"ts" => call_timestamp
	})

	request = Net::HTTP::Post::Multipart.new(url.path, the_hash, {'Accept' => 'application/json', 'User-Agent' => @opts[:user_agent] })

	if @debug
		http.set_debug_output($stdout)
	end

	resp = http.request(request)

	case resp
		when Net::HTTPSuccess, Net::HTTPRedirection
			json = JSON.parse(resp.body)

			if json['opstat'] != 'ok'
				raise MyGengo::Exception.new(json['opstat'], json['err']['code'].to_i, json['err']['msg'])
			end

			# Return it if there are no problems, nice...
			json
		else
			resp.error!
	end
end

#urlencode(string) ⇒ Object

Use CGI escape to escape a string



46
47
48
 
# File 'lib/mygengo-ruby/api_handler.rb', line 46

def urlencode(string)
	CGI::escape(string)
end