Ruby SDK for Filestack API and content management system.
Important: This is the readme for 2.1.0.
A recent change (2.1.0) has renamed the Client
to FilestackClient
, and the Filelink
to FilestackFilelink
. Please make neccessary changes before upgrading to newest release if you run 2.0.1 or 2.0.0. This was to address namespace concerns by users with models and attributes named Client
, and to be more consistent.
- A multi-part uploader powered on the backend by the Filestack CIN.
- An interface to the Filestack Processing Engine for transforming assets via URLs.
- The Filestack Picker - an upload widget for the web that integrates over a dozen cloud providers and provides pre-upload image editing.
Add this line to your application's Gemfile:
gem 'filestack'
And then execute:
$ bundle
Or install it yourself as:
$ gem install filestack
require 'filestack'
Intialize the client using your API key, and security if you are using it.
client = FilestackClient.new('YOUR_API_KEY', security: security_object)
Filestack uses multipart uploading by default, which is faster for larger files. This can be turned off by passing in multipart: false
. Multipart is disabled when uploading external URLs.
filelink = client.upload(filepath: '/path/to/file')
filelink = client.upload(filepath: '/path/to/file', multipart: false)
# OR
filelink = client.upload(external_url: 'http://someurl.com')
To upload a local and an external file with query parameters:
filelink = client.upload(filepath: '/path/to/file', options: {mimetype: 'image/png'})
filelink = client.upload(external_url: 'http://someurl.com/image.png', options: {mimetype: 'image/jpeg'})
To store file on dropbox
, azure
, gcs
or rackspace
, you must have the chosen provider configured in the developer portal to enable this feature. By default the file is stored on s3
. You can add more details of the storage in options
.
filelink = client.upload(filepath: '/path/to/file', storage: 'dropbox', options: {path: 'folder_name/'})
filelink = client.upload(external_url: 'http://someurl.com/image.png', storage: 'dropbox', options: {path: 'folder_name/'})
If security is enabled on your account, or if you are using certain actions that require security (delete, overwrite and certain transformations), you will need to create a security object and pass it into the client on instantiation.
security = FilestackSecurity.new('YOUR_APP_SECRET', options: {call: %w[read store pick]})
client = FilestackClient.new('YOUR_API_KEY', security: security)
FilestackFilelink objects are representation of a file handle. You can download, get raw file content, delete and overwrite file handles directly. Security is required for overwrite and delete methods.
Transforms can be initiated one of two ways. The first, by calling transform
on a filelink:
transform = filelink.transform
Or by using an external URL via the client:
transform = client.transform_external('https://someurl.com')
Transformations can be chained together as you please.
transform = filelink.transform.resize(width: 100, height: 100).flip.enhance
You can retrieve the URL of a transform object:
transform.url
Or you can store (upload) the transformation as a new filelink:
new_filelink = transform.store
For a list of valid transformations, please see here.
If you have auto-tagging enabled onto your account, it can be called on any filelink object (tags don't work on external URLs).
tags = filelink.tags
This will return a hash with labels and their associated confidence:
{
"auto" => {
"art"=>73,
"big cats"=>79,
"carnivoran"=>80,
"cartoon"=>93,
"cat like mammal"=>92,
"fauna"=>86, "mammal"=>92,
"small to medium sized cats"=>89,
"tiger"=>92,
"vertebrate"=>90},
"user" => nil
}
SFW is called the same way, but returns a boolean value (true == safe-for-work, false == not-safe-for-work).
sfw = filelink.sfw
Filestack Ruby SDK follows the Semantic Versioning.
If you have problems, please create a Github Issue.