Ruby SDK
この Ruby Gem を使うと、Transloadit REST API 経由のファイルアップロードを自動化できます。
Ruby on Rails を利用していて、ファイルアップロードをブラウザー連携で処理したい場合は、利用可能な Ruby on Rails SDK (English) も用意しています。
インストール
gem install transloadit
使い方
まず、「transloadit」 gem を require します。
$ irb
>> require 'transloadit'
=> true
続いて、Transloadit のインスタンスを作成します。これにより、認証 Credential を保持し、API へのリクエストを送信できます。
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => ENV.fetch('TRANSLOADIT_SECRET')
)
1. 画像のリサイズと保存
この例では、画像をリサイズし、その結果を Amazon S3 に保存する Assembly の作成方法を示します。
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => ENV.fetch('TRANSLOADIT_SECRET')
)
# First, we create two steps: one to resize the image to 320x240, and another to
# store the image in our S3 bucket.
resize = transloadit.step 'resize', '/image/resize',
:width => 320,
:height => 240
store = transloadit.step 'store', '/s3/store',
:key => 'YOUR_AWS_KEY',
:secret => 'YOUR_AWS_SECRET',
:bucket => 'YOUR_S3_BUCKET'
# Now that we have the steps, we create an assembly (which is just a request to
# process a file or set of files) and let Transloadit do the rest.
assembly = transloadit.assembly(
:steps => [ resize, store ]
)
response = assembly.create! open('/PATH/TO/FILE.jpg')
# reloads the response once per second until all processing is finished
response.reload_until_finished!
if response.error?
abort(response[:error])
else
# handle other cases
puts response
end
Assembly の submit! メソッドは非推奨となり、create! に置き換えられました。submit! メソッドは、後方互換性のために create! のエイリアスとして引き続き利用できます。
create! メソッドが返ると、ファイルのアップロードは完了していますが、処理はまだ完了していない場合があります。返されたオブジェクトを使って、処理が完了したかどうかを確認したり、リクエストのほかの属性を調べたりできます。
# returns the unique API ID of the assembly
response[:assembly_id] # => '9bd733a...'
# returns the API URL endpoint for the assembly
response[:assembly_url] # => 'http://api2.vivian.transloadit.com/assemblies/9bd733a...'
# checks how many bytes were expected / received by transloadit
response[:bytes_expected] # => 92933
response[:bytes_received] # => 92933
# checks if all processing has been finished
response.finished? # => false
# cancels further processing on the assembly
response.cancel! # => true
# checks if processing was successfully completed
response.completed? # => true
# checks if the processing returned with an error
response.error? # => false
これらの問い合わせは、cancel! メソッドを除き、いずれも「ライブ」ではない点に注意してください。どれも
Assembly 作成時に API が返したレスポンスを確認するだけです。API から結果を再取得するには、Assembly に明示的に再読み込みを指示する必要があります。
# reloads the response's contents from the REST API
response.reload!
# reloads once per second until all processing is finished, up to number of
# times specified in :tries option, otherwise will raise ReloadLimitReached
response.reload_until_finished! tries: 300 # default is 600
一般に、レスポンス の直接属性を問い合わせるには、ハッシュアクセサー構文を使います。疑問符で終わるメソッドは、状態をより読みやすく確認するためのものです(たとえば、assembly.completed? は assembly[:ok] の結果を確認するより読みやすくなります)。感嘆符で終わるメソッドは、Transloadit HTTP API に対してライブ問い合わせを行います。
2. 複数ファイルのアップロード
同じリクエストで複数のファイルをアップロードするには、create! メソッドに複数のファイルを渡せます。また、steps パラメーターには、単一の Step を Array でラップせずにそのまま渡せます。
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => ENV.fetch('TRANSLOADIT_SECRET')
)
assembly = transloadit.assembly(steps: store)
response = assembly.create!(
open('puppies.jpg'),
open('kittens.jpg'),
open('ferrets.jpg')
)
create! メソッドにはファイルの配列も渡せます。その場合は、splat 演算子 * を使って配列を展開してください。
files = [open('puppies.jpg'), open('kittens.jpg'), open('ferrets.jpg')]
response = assembly.create! *files
3. 並列 Assembly
Transloadit では、複数の処理ステップを並列に実行できます。use でほかの Step を指定するだけです。たとえば、その例 は次のとおりです。
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => ENV.fetch('TRANSLOADIT_SECRET')
)
encode = transloadit.step 'encode', '/video/encode', { ... }
thumbs = transloadit.step 'thumbs', '/video/thumbs', { ... }
export = transloadit.step 'store', '/s3/store', { ... }
export.use [ encode, thumbs ]
transloadit.assembly(
:steps => [ encode, thumbs, export ]
).create! open('/PATH/TO/FILE.mpg')
別のステップの代わりに Symbol :original を渡すことで、元のアップロードファイルを使うようステップに指定することもできます。
使用方法の詳細は、YARD ドキュメントの use を参照してください。
4. Template を使った Assembly の作成
Transloadit では、繰り返し発生するエンコードタスクに対して独自の Template を利用できます。利用するには、次のとおりです。
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => ENV.fetch('TRANSLOADIT_SECRET')
)
transloadit.assembly(
:template_id => 'YOUR_TEMPLATE_ID'
).create! open('/PATH/TO/FILE.mpg')
この Template はステップと組み合わせて使えます。また、変数も使用できます。詳しい例は Transloadit のドキュメント を参照してください。
5. フィールドの使用
Transloadit では、通知で返されるフォームフィールド値を送信できます。これは、アップロード自体に追加のカスタムメタデータを付与したい場合に便利です。たとえば、次のようなフィールドを使えます。
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => ENV.fetch('TRANSLOADIT_SECRET')
)
transloadit.assembly(
:fields => {
:tag => 'some_tag_name',
:field_name => 'field_value'
}
).create! open('/PATH/TO/FILE.mpg')
6. 通知先 URL
処理が完了したときに通知を受け取りたい場合は、Assembly に通知先 URL を指定できます。
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => ENV.fetch('TRANSLOADIT_SECRET')
)
transloadit.assembly(
:notify_url => 'http://example.com/processing_finished'
).create! open('/PATH/TO/FILE.mpg')
Notification の詳細は、Transloadit のドキュメントページ を参照してください。
7. その他の Assembly メソッド
Transloadit には、Assembly の取得と再実行、およびその Notification の取得と再送を行うメソッドもあります。
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => ENV.fetch('TRANSLOADIT_SECRET')
)
assembly = transloadit.assembly
# returns a list of all assemblies
assembly.list
# returns a specific assembly
assembly.get 'YOUR_ASSEMBLY_ID'
# replays a specific assembly
response = assembly.replay 'YOUR_ASSEMBLY_ID'
# should return true if assembly is replaying and false otherwise.
response.replaying?
# returns all assembly notifications
assembly.get_notifications
# replays an assembly notification
assembly.replay_notification 'YOUR_ASSEMBLY_ID'
8. Template
Transloadit は、繰り返し発生するエンコードタスク向けに Template API を提供しています。Template の作成方法は次のとおりです。
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => ENV.fetch('TRANSLOADIT_SECRET')
)
template = transloadit.template
# creates a new template
template.create(
:name => 'TEMPLATE_NAME',
:template => {
"steps": {
"encode": {
"use": ":original",
"robot": "/video/encode",
"result": true
}
}
}
)
Template を取得、更新、削除するほかのメソッドもあります。
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => ENV.fetch('TRANSLOADIT_SECRET')
)
template = transloadit.template
# returns a list of all templates.
template.list
# returns a specific template.
template.get 'YOUR_TEMPLATE_ID'
# updates the template whose id is specified.
template.update(
'YOUR_TEMPLATE_ID',
:name => 'CHANGED_TEMPLATE_NAME',
:template => {
:steps => {
:encode => {
:use => ':original',
:robot => '/video/merge'
}
}
}
)
# deletes a specific template
template.delete 'YOUR_TEMPLATE_ID'
9. 請求レポートの取得
特定の月と年の Transloadit アカウント請求レポートを取得したい場合は、bill メソッドに必要な月と年を渡して、次のように実行できます。
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => ENV.fetch('TRANSLOADIT_SECRET')
)
# returns bill report for February, 2016.
transloadit.bill(2, 2016)
month または year を指定しない場合は、現在の月または年がデフォルトで使われます。
10. レート制限
Transloadit は、特定の顧客の利用によってほかの顧客が悪影響を受けないよう、レート制限を適用しています。詳細は レート制限 を参照してください。
Assembly の作成中にレート制限エラーを受け取った場合、デフォルトでは、成功レスポンスを得るためにさらに 2 回試行します。それでもレート制限エラーが続く場合は、RateLimitReached 例外が送出されます。
Assembly 作成時の試行回数を変更するには、tries オプションを次のように
Assembly に渡します。
require 'transloadit'
transloadit = Transloadit.new(
:key => 'YOUR_TRANSLOADIT_KEY',
:secret => ENV.fetch('TRANSLOADIT_SECRET')
)
# would make one extra attempt after a failed attempt.
transloadit.assembly(:tries => 2).create! open('/PATH/TO/FILE.mpg')
# Would make no attempt at all. Your request would not be sent.
transloadit.assembly(:tries => 0).create! open('/PATH/TO/FILE.mpg')
例
Transloadit ruby-sdk を使って、画像の最適化、MP3 音声のエンコード、ID3 タグの追加などを行う小さなサンプルチュートリアルをこちら で参照できます。
ドキュメント
最新の YARD ドキュメントは自動生成されています。リリース済み gem のドキュメント、または最新の git main のドキュメントを参照できます。