Class: MyGengo::API
- Inherits:
-
Object
- Object
- MyGengo::API
- Defined in:
- lib/mygengo-ruby/api_handler.rb
Overview
The only real class that ever needs to be instantiated.
Instance Attribute Summary collapse
-
#api_host ⇒ Object
Returns the value of attribute api_host.
-
#client_info ⇒ Object
Returns the value of attribute client_info.
-
#debug ⇒ Object
Returns the value of attribute debug.
Instance Method Summary collapse
-
#deleteTranslationJob(params = {}) ⇒ Object
Deletes a job.
-
#determineTranslationCost(params = {}) ⇒ Object
Mirrors the bulk Translation call, but just returns an estimated cost.
-
#get_from_mygengo(endpoint, params = {}) ⇒ Object
The “GET” method; handles requesting basic data sets from myGengo and converting the response to a Ruby hash/object.
-
#getAccountBalance(params = {}) ⇒ Object
Returns a Ruby-hash of the balance for the authenticated account.
-
#getAccountStats(params = {}) ⇒ Object
Returns a Ruby-hash of the stats for the current account.
-
#getServiceLanguagePairs(params = {}) ⇒ Object
Gets information about currently supported language pairs.
-
#getServiceLanguages(params = {}) ⇒ Object
Pulls down currently supported languages.
-
#getTranslationJob(params = {}) ⇒ Object
Given an ID, pulls down information concerning that job from myGengo.
-
#getTranslationJobBatch(params = {}) ⇒ Object
Pulls a group of jobs that were previously submitted together.
-
#getTranslationJobComments(params = {}) ⇒ Object
Get all comments (the history) from a given job.
-
#getTranslationJobFeedback(params = {}) ⇒ Object
Returns the feedback you’ve submitted for a given job.
-
#getTranslationJobPreviewImage(params = {}) ⇒ Object
Returns a preview image for a job.
-
#getTranslationJobRevision(params = {}) ⇒ Object
Get a specific revision to a job.
-
#getTranslationJobRevisions(params = {}) ⇒ Object
Gets a list of the revision resources for a job.
-
#getTranslationJobs(params = {}) ⇒ Object
Pulls down a list of recently submitted jobs, allows some filters.
-
#initialize(opts) ⇒ API
constructor
Creates a new API handler to shuttle calls/jobs/etc over to the myGengo translation API.
-
#postTranslationJob(params = {}) ⇒ Object
Posts a translation job over to myGengo, returns a response indicating whether the submission was successful or not.
-
#postTranslationJobComment(params = {}) ⇒ Object
Post a comment for a translator or myGengo on a job.
-
#postTranslationJobs(params = {}) ⇒ Object
Much like the above, but takes a hash titled “jobs” that is multiple jobs, each with their own unique key.
-
#send_to_mygengo(endpoint, params = {}) ⇒ Object
The “POST” method; handles shuttling up encoded job data to myGengo for translation and such.
-
#signature_of(params) ⇒ Object
Creates an HMAC::SHA1 signature, signing the request with the private key.
-
#updateTranslationJob(params = {}) ⇒ Object
Updates an already submitted job.
Constructor Details
#initialize(opts) ⇒ API
Creates a new API handler to shuttle calls/jobs/etc over to the myGengo 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.
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 |
# File 'lib/mygengo-ruby/api_handler.rb', line 25 def initialize(opts) # Consider this an example of the object you need to pass. @opts = { :public_key => '', :private_key => '', :api_version => '1', :sandbox => false, :user_agent => "myGengo Ruby Library v#{MyGengo::Config::VERSION}", :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) + "v#{@opts[:api_version]}/" # 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.
16 17 18 |
# File 'lib/mygengo-ruby/api_handler.rb', line 16 def api_host @api_host end |
#client_info ⇒ Object
Returns the value of attribute client_info.
18 19 20 |
# File 'lib/mygengo-ruby/api_handler.rb', line 18 def client_info @client_info end |
#debug ⇒ Object
Returns the value of attribute debug.
17 18 19 |
# File 'lib/mygengo-ruby/api_handler.rb', line 17 def debug @debug end |
Instance Method Details
#deleteTranslationJob(params = {}) ⇒ Object
Deletes a job.
Options: id
- The ID of the job you want to delete.
276 277 278 |
# File 'lib/mygengo-ruby/api_handler.rb', line 276 def deleteTranslationJob(params = {}) self.send_to_mygengo('translate/job/:id'.gsub(':id', params.delete(:id)), params) end |
#determineTranslationCost(params = {}) ⇒ Object
Mirrors the bulk Translation call, but just returns an estimated cost.
218 219 220 |
# File 'lib/mygengo-ruby/api_handler.rb', line 218 def determineTranslationCost(params = {}) self.send_to_mygengo('translate/service/quote', params) end |
#get_from_mygengo(endpoint, params = {}) ⇒ Object
The “GET” method; handles requesting basic data sets from myGengo 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.
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 |
# File 'lib/mygengo-ruby/api_handler.rb', line 64 def get_from_mygengo(endpoint, params = {}) # The first part of the object we're going to encode and use in our request to myGengo. The signing process # is a little annoying at the moment, so bear with us... query = {} query["api_key"] = @opts[:public_key] query["data"] = params.to_json if !params.empty? query["ts"] = Time.now.gmtime.to_i.to_s query.merge!("api_sig" => signature_of(query)) endpoint << '?' + query.map { |k, v| "#{k}=#{CGI::escape(v)}" }.join('&') api_url = URI.parse(@api_host + endpoint); resp = Net::HTTP.start(api_url.host, api_url.port) do |http| puts api_url.request_uri http.request(Net::HTTP::Get.new(api_url.request_uri, { 'Accept' => 'application/json', 'User-Agent' => @opts[:user_agent] })) end 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 end |
#getAccountBalance(params = {}) ⇒ Object
Returns a Ruby-hash of the balance for the authenticated account. No args required!
Options: None
- N/A
162 163 164 |
# File 'lib/mygengo-ruby/api_handler.rb', line 162 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
154 155 156 |
# File 'lib/mygengo-ruby/api_handler.rb', line 154 def getAccountStats(params = {}) self.get_from_mygengo('account/stats', params) end |
#getServiceLanguagePairs(params = {}) ⇒ Object
Gets information about currently supported language pairs.
Options: lc_src
- Optional language code to filter on.
284 285 286 |
# File 'lib/mygengo-ruby/api_handler.rb', line 284 def getServiceLanguagePairs(params = {}) self.get_from_mygengo('translate/service/language_pairs', params) end |
#getServiceLanguages(params = {}) ⇒ Object
Pulls down currently supported languages.
289 290 291 |
# File 'lib/mygengo-ruby/api_handler.rb', line 289 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 myGengo.
id
- The ID of a job to check. pre_mt
- Optional, get a machine translation if the human translation is not done.
197 198 199 |
# File 'lib/mygengo-ruby/api_handler.rb', line 197 def getTranslationJob(params = {}) self.get_from_mygengo('translate/job/:id'.gsub(':id', params.delete(:id)), 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.
213 214 215 |
# File 'lib/mygengo-ruby/api_handler.rb', line 213 def getTranslationJobBatch(params = {}) self.get_from_mygengo('translate/jobs/:id'.gsub(':id', params.delete(:id)), 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.
235 236 237 |
# File 'lib/mygengo-ruby/api_handler.rb', line 235 def getTranslationJobComments(params = {}) self.get_from_mygengo('translate/job/:id/comments'.gsub(':id', params.delete(:id)), 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.
243 244 245 |
# File 'lib/mygengo-ruby/api_handler.rb', line 243 def getTranslationJobFeedback(params = {}) self.get_from_mygengo('translate/job/:id/feedback'.gsub(':id', params.delete(:id)), 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.
268 269 270 |
# File 'lib/mygengo-ruby/api_handler.rb', line 268 def getTranslationJobPreviewImage(params = {}) self.get_from_mygengo('translate/job/:id/preview'.gsub(':id', params.delete(:id)), 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.
260 261 262 |
# File 'lib/mygengo-ruby/api_handler.rb', line 260 def getTranslationJobRevision(params = {}) self.get_from_mygengo('translate/job/:id/revisions/:revision_id'.gsub(':id', params.delete(:id)).gsub(':rev_id', params.delete(:rev_id)), 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.
251 252 253 |
# File 'lib/mygengo-ruby/api_handler.rb', line 251 def getTranslationJobRevisions(params = {}) self.get_from_mygengo('translate/job/:id/revisions'.gsub(':id', params.delete(:id)), 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.
206 207 208 |
# File 'lib/mygengo-ruby/api_handler.rb', line 206 def getTranslationJobs(params = {}) self.get_from_mygengo('translate/jobs', params) end |
#postTranslationJob(params = {}) ⇒ Object
Posts a translation job over to myGengo, 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)
172 173 174 |
# File 'lib/mygengo-ruby/api_handler.rb', line 172 def postTranslationJob(params = {}) self.send_to_mygengo('translate/job', params) end |
#postTranslationJobComment(params = {}) ⇒ Object
Post a comment for a translator or myGengo on a job.
Options: id
- The ID of the job you’re commenting on. comment
- The comment to put on the job.
227 228 229 |
# File 'lib/mygengo-ruby/api_handler.rb', line 227 def postTranslationJobComment(params = {}) self.send_to_mygengo('translate/job/:id/comment'.gsub(':id', params.delete(:id)), 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.
180 181 182 |
# File 'lib/mygengo-ruby/api_handler.rb', line 180 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 myGengo 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.
103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 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 |
# File 'lib/mygengo-ruby/api_handler.rb', line 103 def send_to_mygengo(endpoint, params = {}) data = {} # ...strip out job data as we need it. if !params[:job].nil? data[:job] = {:job => params[:job]} elsif !params[:jobs].nil? data[:jobs] = {:jobs => params[:jobs]} data[:process] = params[:process] if !params[:process].nil? data[:as_group] = params[:as_group] if !params[:as_group].nil? elsif !params[:comment].nil? data[:comment] = params[:comment] elsif !params[:update].nil? # Less confusing for people. ;P data[:update] = params[:action] end # The first part of the object we're going to encode and use in our request to myGengo. The signing process # is a little annoying at the moment, so bear with us... query = { "api_key" => @opts[:public_key], "ts" => Time.now.gmtime.to_i.to_s } query["data"] = data if !data.empty? query.merge!('api_sig' => signature_of(query.to_json)) api_url = URI.parse(@api_host + endpoint); resp = Net::HTTP.start(api_url.host, api_url.port) do |http| req = Net::HTTP::Post.new(api_url.request_uri, { 'Accept' => 'application/json', 'User-Agent' => @opts[:user_agent] }) req.set_form_data query http.request(req) end 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 end |
#signature_of(params) ⇒ Object
Creates an HMAC::SHA1 signature, signing the request with the private key.
45 46 47 48 49 50 51 52 53 54 55 56 |
# File 'lib/mygengo-ruby/api_handler.rb', line 45 def signature_of(params) if Hash === params sorted_keys = params.keys.sort params = sorted_keys.zip(params.values_at(*sorted_keys)).map do |k, v| "#{k}=#{CGI::escape(v)}" end * '&' end # This will be faster, but is more work for an end user to maintain. :( #OpenSSL::HMAC.digest(OpenSSL::Digest::Digest.new('sha1'), @opts[:private_key], params) HMAC::SHA1.hexdigest @opts[:private_key], params 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.
189 190 191 |
# File 'lib/mygengo-ruby/api_handler.rb', line 189 def updateTranslationJob(params = {}) self.send_to_mygengo('translate/job/:id'.gsub(':id', params.delete(:id)), params) end |