# SDK de Ruby

[transloadit/ruby-sdk](https://github.com/transloadit/ruby-sdk)

Nuestra gema de Ruby te permite automatizar la subida de archivos mediante laREST 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](/docs/sdks/rails-sdk.md) listo para que lo uses.

## Instalación

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```bash
gem install transloadit

```

## Uso

Para comenzar, debes cargar la gema 'transloadit':

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

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

```

Luego, crea una instancia de Transloadit, que conservará tus[credenciales de autenticación](/workspaces/credentials/) y nos permitirá realizar solicitudes a [la API](/es/docs/api.md).

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```ruby
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](https://aws.amazon.com/s3/).

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```ruby
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.

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```ruby
# 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.

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```ruby
# 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](/es/docs/api/assembly-status-response.md). 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.

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```ruby
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`*`.

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```ruby
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](/es/docs/topics/assembly-instructions.md#step-parameters):

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```ruby
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](http://rubydoc.info/gems/transloadit/frames/Transloadit/Step#use-instance%5Fmethod).

### 4. Crear una Assembly con Templates

Transloadit te permite usar[Templates](https://github.com/transloadit/ruby-sdk#8-templates) personalizados para tareas recurrentes de encoding. Para usarlos, haz lo siguiente:

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```ruby
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](/es/docs/topics/templates.md#passing-variables-into-a-template)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:

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```ruby
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 laAssembly.

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```ruby
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](/es/docs/topics/webhooks.md).

### 7. Otros métodos de Assembly

Transloadit también proporciona métodos para recuperar y reejecutar Assemblies, así como para recuperar y reenviar susNotifications.

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```ruby
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](/es/docs/topics/templates.md) para tareas recurrentes de encoding. Así puedes crear un Template:

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```ruby
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.

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```ruby
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:

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```ruby
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](/es/docs/api/rate-limiting.md).

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.

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```ruby
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í](https://github.com/transloadit/ruby-sdk/tree/master/examples) 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](http://rubydoc.info/gems/transloadit/frames) o de la versión más reciente de[git main](https://github.com/transloadit/ruby-sdk).