SDK de Ruby

Nuestra gema de Ruby te permite automatizar la subida de archivos mediante la REST API de Transloadit.

Si ejecutas Ruby on Rails y, en cambio, buscas una integración con el navegador para gestionar subidas de archivos, también tenemos un SDK de Ruby on Rails (English) listo para que lo uses.

Instalación

gem install transloadit

Uso

Para comenzar, debes cargar la gema 'transloadit':

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

Luego, crea una instancia de Transloadit, que conservará tus credenciales de autenticación y nos permitirá realizar solicitudes a la API.

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

1. Redimensionar y almacenar una imagen

Este ejemplo muestra cómo puedes crear una Assembly para redimensionar una imagen y almacenar el resultado en 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

Nota

El método submit! de Assembly dejó de ser recomendado y se reemplazó por create!. El método submit! se mantiene como alias de create! por compatibilidad con versiones anteriores.

Cuando el método create! devuelve el resultado, el archivo ya se ha subido, pero es posible que su procesamiento aún no haya terminado. Podemos usar el objeto devuelto para comprobar si el procesamiento finalizó o examinar otros atributos de la solicitud.

# 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

Es importante tener en cuenta que ninguna de estas consultas se realiza «en vivo» (a excepción del método cancel!). Todas comprueban la respuesta proporcionada por la API en el momento en que se creó la Assembly. Debes solicitar explícitamente a la Assembly que vuelva a cargar sus resultados desde la 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

En general, se usa la sintaxis de acceso de hashes para consultar cualquier atributo directo de la respuesta. Los métodos cuyo nombre termina en signo de interrogación ofrecen una forma más legible de consultar el estado (por ejemplo, assembly.completed? frente a comprobar el resultado de assembly[:ok]). Los métodos cuyo nombre termina en signo de exclamación realizan una consulta en vivo a la API HTTP de Transloadit.

2. Subir varios archivos

Puedes proporcionar varios archivos al método create! para subir más de un archivo en la misma solicitud. También puedes pasar un único Step al parámetro steps sin tener que envolverlo en un 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')
)

También puedes pasar un arreglo de archivos al método create!. Simplemente, desempaqueta el arreglo mediante el operador splat *.

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

3. Assembly paralela

Transloadit te permite ejecutar varios Steps de procesamiento en paralelo. Solo necesitas indicar mediante use otros Steps. Siguiendo su ejemplo:

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')

También puedes indicarle a un Step que use el archivo original subido pasando el símbolo :original en lugar de otro Step.

Consulta la documentación de YARD para obtener más información sobre el uso de use.

4. Crear una Assembly con Templates

Transloadit te permite usar Templates personalizados para tareas recurrentes de encoding. Para usarlos, haz lo siguiente:

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')

Puedes usar tus Steps junto con este Template e incluso usar variables. La documentación de Transloadit incluye algunos buenos ejemplos de esto.

5. Usar campos

Transloadit te permite enviar valores de campos de formulario que recibirás nuevamente en la notificación. Esto resulta muy útil si deseas añadir metadatos personalizados adicionales a la propia subida. Puedes usar campos como los siguientes:

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 notificación

Si deseas recibir una notificación cuando finalice el procesamiento, puedes proporcionar una URL de notificación para la 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')

Obtén más información sobre las Notifications en la página de documentación de Transloadit.

7. Otros métodos de Assembly

Transloadit también proporciona métodos para recuperar y reejecutar Assemblies, así como para recuperar y reenviar sus 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

Transloadit proporciona una API de Templates para tareas recurrentes de encoding. Así puedes crear un 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
      }
    }
  }
)

También hay otros métodos para recuperar, actualizar y eliminar un 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. Obtener informes de facturación

Si deseas recuperar el informe de facturación de tu cuenta de Transloadit correspondiente a un mes y año específicos, puedes usar el método bill y pasarle el mes y el año requeridos de la siguiente manera:

require 'transloadit'

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

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

Si no especificas month o year, se usará de forma predeterminada el mes o el año actual, respectivamente.

10. Límites de tasa

Transloadit aplica límites de tasa para garantizar que el uso de un cliente determinado no afecte negativamente a ningún otro cliente. Consulta Límites de tasa.

Al crear una Assembly, si se recibe un error de límite de tasa, de forma predeterminada se realizarán 2 intentos adicionales para obtener una respuesta correcta. Si el error de límite de tasa persiste después de estos intentos, se generará una excepción RateLimitReached.

Para cambiar el número de intentos que se realizarán al crear una Assembly, puedes pasar la opción tries a tu Assembly de la siguiente manera.

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')

Ejemplo

Puedes encontrar aquí un breve tutorial de ejemplo sobre cómo usar el SDK de Ruby de Transloadit para optimizar una imagen, codificar audio MP3, añadir etiquetas ID3 y mucho más.

Documentación

La documentación actualizada de YARD se genera automáticamente. Puedes consultar la documentación de la gema publicada o de la versión más reciente de git main.