SDK para Ruby

Nossa gem Ruby permite automatizar o upload de arquivos por meio da REST API da Transloadit.

Se você usa Ruby on Rails e procura uma integração com o navegador para lidar com uploads de arquivos, também temos um SDK Ruby on Rails (English) pronto para você usar.

Instalar

gem install transloadit

Uso

Para começar, você precisa carregar a gem “transloadit” usando require:

$ irb -rubygems
>> require 'transloadit'
=> true

Em seguida, crie uma instância da Transloadit, que manterá suas credenciais de autenticação e nos permitirá fazer requisições à API.

transloadit = Transloadit.new(
  :key    => 'YOUR_TRANSLOADIT_KEY',
  :secret => 'YOUR_TRANSLOADIT_SECRET'
)

1. Redimensionar e armazenar uma imagem

Este exemplo mostra como você pode criar uma Assembly para redimensionar uma imagem e armazenar o resultado no Amazon S3.

require 'transloadit'

transloadit = Transloadit.new(
  :key    => 'YOUR_TRANSLOADIT_KEY',
  :secret => 'YOUR_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?
  # handle error
else
  # handle other cases
  puts response
end

Observação

O método submit! de Assembly está preterido e foi substituído por create!. O método submit! continua sendo um alias de create! para manter a compatibilidade com versões anteriores.

Quando o método create! retorna, o upload do arquivo já foi concluído, mas o processamento ainda pode estar em andamento. Podemos usar o objeto retornado para verificar se o processamento foi concluído ou examinar outros atributos da requisição.

# 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

É importante observar que nenhuma dessas consultas ocorre “em tempo real”, com exceção do método cancel!. Todas verificam a resposta fornecida pela API no momento em que a Assembly foi criada. Você precisa pedir explicitamente que a Assembly recarregue seus resultados da API.

# 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

Em geral, você usa a sintaxe de acesso a hashes para consultar qualquer atributo direto da resposta. Métodos com ponto de interrogação no final oferecem uma forma mais legível de consultar o estado (por exemplo, assembly.completed? em vez de verificar o resultado de assembly[:ok]). Métodos com ponto de exclamação no final fazem uma consulta em tempo real à API HTTP da Transloadit.

2. Fazer upload de vários arquivos

Você pode passar vários arquivos ao método create! para fazer upload de mais de um arquivo na mesma requisição. Também pode passar um único Step no parâmetro steps, sem precisar colocá-lo em um Array.

require 'transloadit'

transloadit = Transloadit.new(
  :key    => 'YOUR_TRANSLOADIT_KEY',
  :secret => 'YOUR_TRANSLOADIT_SECRET'
)

assembly = transloadit.assembly(steps: store)

response = assembly.create!(
  open('puppies.jpg'),
  open('kittens.jpg'),
  open('ferrets.jpg')
)

Você também pode passar um array de arquivos ao método create!. Basta desempacotar o array usando o operador splat *.

files = [open('puppies.jpg'), open('kittens.jpg'), open('ferrets.jpg')]
response = assembly.create! *files

3. Assembly paralela

A Transloadit permite executar vários Steps de processamento em paralelo. Basta chamar use com outros Steps. Seguindo o exemplo da Transloadit:

require 'transloadit'

transloadit = Transloadit.new(
  :key    => 'YOUR_TRANSLOADIT_KEY',
  :secret => 'YOUR_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')

Você também pode indicar que um Step deve usar o arquivo original enviado por upload, passando o Symbol :original em vez de outro Step.

Consulte a documentação YARD para saber mais sobre como usar use.

4. Criar uma Assembly com Templates

A Transloadit permite usar Templates personalizados para tarefas recorrentes de codificação. Para usá-los, faça o seguinte:

require 'transloadit'

transloadit = Transloadit.new(
  :key    => 'YOUR_TRANSLOADIT_KEY',
  :secret => 'YOUR_TRANSLOADIT_SECRET'
)

transloadit.assembly(
  :template_id => 'YOUR_TEMPLATE_ID'
).create! open('/PATH/TO/FILE.mpg')

Você pode usar seus Steps com esse Template e até usar variáveis. A documentação da Transloadit tem bons exemplos disso.

5. Usar campos

A Transloadit permite enviar valores de campos de formulário que você receberá de volta na notificação. Isso é bastante útil se você quiser adicionar metadados personalizados ao próprio upload. Você pode usar campos como os seguintes:

require 'transloadit'

transloadit = Transloadit.new(
  :key    => 'YOUR_TRANSLOADIT_KEY',
  :secret => 'YOUR_TRANSLOADIT_SECRET'
)

transloadit.assembly(
  :fields => {
    :tag => 'some_tag_name',
    :field_name => 'field_value'
  }
).create! open('/PATH/TO/FILE.mpg')

6. URL de notificação

Se quiser receber uma notificação quando o processamento terminar, você pode fornecer uma URL de notificação para a Assembly.

require 'transloadit'

transloadit = Transloadit.new(
  :key    => 'YOUR_TRANSLOADIT_KEY',
  :secret => 'YOUR_TRANSLOADIT_SECRET'
)

transloadit.assembly(
  :notify_url => 'http://example.com/processing_finished'
).create! open('/PATH/TO/FILE.mpg')

Saiba mais sobre as Notifications na página de documentação da Transloadit.

7. Outros métodos de Assembly

A Transloadit também oferece métodos para recuperar e reexecutar Assemblies, além de recuperar e reenviar suas Notifications.

require 'transloadit'

transloadit = Transloadit.new(
  :key    => 'YOUR_TRANSLOADIT_KEY',
  :secret => 'YOUR_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. Templates

A Transloadit oferece uma API de Templates para tarefas recorrentes de codificação. Veja como criar um Template:

require 'transloadit'

transloadit = Transloadit.new(
  :key    => 'YOUR_TRANSLOADIT_KEY',
  :secret => 'YOUR_TRANSLOADIT_SECRET'
)

template = transloadit.template

# creates a new template
template.create(
  :name => 'TEMPLATE_NAME',
  :template => {
    "steps": {
      "encode": {
        "use": ":original",
        "robot": "/video/encode",
        "result": true
      }
    }
  }
)

Também há outros métodos para recuperar, atualizar e excluir um Template.

require 'transloadit'

transloadit = Transloadit.new(
  :key    => 'YOUR_TRANSLOADIT_KEY',
  :secret => 'YOUR_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. Obter relatórios de cobrança

Se quiser obter o relatório de cobrança da sua conta na Transloadit para um mês e ano específicos, você pode usar o método bill, passando o mês e o ano desejados, assim:

require 'transloadit'

transloadit = Transloadit.new(
  :key    => 'YOUR_TRANSLOADIT_KEY',
  :secret => 'YOUR_TRANSLOADIT_SECRET'
)

# returns bill report for February, 2016.
transloadit.bill(2, 2016)

Se você não especificar month ou year, será usado por padrão o mês ou o ano atual, respectivamente.

10. Limites de requisições

A Transloadit aplica limites de requisições para garantir que nenhum cliente seja prejudicado pelo uso de qualquer outro cliente. Consulte Limitação de requisições.

Ao criar uma Assembly, se ocorrer um erro de limite de requisições, serão feitas, por padrão, mais 2 tentativas para obter uma resposta bem-sucedida. Se o erro persistir após essas tentativas, será lançada uma exceção RateLimitReached.

Para alterar o número de tentativas feitas ao criar uma Assembly, você pode passar a opção tries para sua Assembly assim:

require 'transloadit'

transloadit = Transloadit.new(
  :key    => 'YOUR_TRANSLOADIT_KEY',
  :secret => 'YOUR_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')

Exemplo

Você encontra aqui um breve tutorial com exemplos de como usar o ruby-sdk da Transloadit para otimizar uma imagem, codificar áudio MP3, adicionar tags ID3 e muito mais.

Documentação

A documentação YARD atualizada é gerada automaticamente. Você pode consultar a documentação da gem publicada ou da versão mais recente da branch main no Git.