# Ruby SDK

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

Mit unserem Ruby-Gem können Sie Datei-Uploads über die TransloaditREST API automatisieren.

Wenn Sie Ruby on Rails verwenden und stattdessen eine Browserintegration für Datei-Uploads suchen, steht Ihnen auch unser [Ruby on Rails SDK](/docs/sdks/rails-sdk.md) zur Verfügung.

## Installation

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

```bash
gem install transloadit

```

## Verwendung

Zunächst müssen Sie das „transloadit“-Gem einbinden:

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

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

```

Erstellen Sie anschließend eine Transloadit-Instanz. Diese verwaltet Ihre[Authentifizierungsdaten](/workspaces/credentials/) und ermöglicht Anfragen an[die API](/de/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. Bild skalieren und speichern

Dieses Beispiel zeigt, wie Sie eine Assembly erstellen, um ein Bild zu skalieren und das Ergebnis auf [Amazon S3](https://aws.amazon.com/s3/) zu speichern.

![](/_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

```

###### Hinweis

Die Methode `submit!` der Assembly ist veraltet und wurde durch `create!` ersetzt. Für die Abwärtskompatibilität bleibt die Methode `submit!` als Alias für `create!` erhalten.

Wenn die Methode `create!` zurückkehrt, wurde die Datei hochgeladen, die Verarbeitung ist jedoch möglicherweise noch nicht abgeschlossen. Mit dem zurückgegebenen Objekt können Sie prüfen, ob die Verarbeitung abgeschlossen ist, oder weitere Attribute der Anfrage untersuchen.

![](/_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

```

Beachten Sie, dass keine dieser Abfragen „live“ ist (mit Ausnahme der Methode `cancel!`). Sie prüfen jeweils die Antwort, die die API bei der Erstellung der Assembly zurückgegeben hat. Sie müssen die Assembly ausdrücklich anweisen, ihre Ergebnisse erneut von der API zu laden.

![](/_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

```

Im Allgemeinen verwenden Sie die Hash-Zugriffssyntax, um direkte Attribute aus der[Antwort](/de/docs/api/assembly-status-response.md) abzufragen. Methoden mit einem Fragezeichen als Suffix bieten eine besser lesbare Möglichkeit, den Status abzufragen (z. B. `assembly.completed?` statt das Ergebnis von `assembly[:ok]` zu prüfen). Methoden mit einem Ausrufezeichen als Suffix führen eine Live-Abfrage an die Transloadit HTTP API aus.

### 2. Mehrere Dateien hochladen

Sie können der Methode `create!` mehrere Dateien übergeben, um mehr als eine Datei in derselben Anfrage hochzuladen. Für den Parameter `steps` können Sie auch einen einzelnen Step übergeben, ohne ihn in ein Array einschließen zu müssen.

![](/_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')
)

```

Sie können der Methode `create!` auch ein Array mit Dateien übergeben. Entpacken Sie das Array einfach mit dem Splat-Operator`*`.

![](/_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. Parallele Assembly

Mit Transloadit können Sie mehrere Verarbeitungsschritte parallel ausführen. Dazu müssen Sie lediglich andere Stepsüber `use` verwenden. Nach[diesem Beispiel](/de/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')

```

Sie können einen Step auch anweisen, die ursprünglich hochgeladene Datei zu verwenden, indem Sie das Symbol `:original` statt eines anderen Steps übergeben.

Weitere Informationen zur Verwendung von[use](http://rubydoc.info/gems/transloadit/frames/Transloadit/Step#use-instance%5Fmethod) finden Sie in der YARD-Dokumentation.

### 4. Eine Assembly mit Templates erstellen

Mit Transloadit können Sie individuelle[Templates](https://github.com/transloadit/ruby-sdk#8-templates) für wiederkehrende Encoding-Aufgaben verwenden. Gehen Sie dazu wie folgt vor:

![](/_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')

```

Sie können Ihre Steps zusammen mit diesem Template verwenden und sogar Variablen einsetzen. Die[Transloadit-Dokumentation](/de/docs/topics/templates.md#passing-variables-into-a-template)bietet dazu einige hilfreiche Beispiele.

### 5. Felder verwenden

Mit Transloadit können Sie Werte aus Formularfeldern übermitteln, die Sie in der Benachrichtigung zurückerhalten. Dies ist praktisch, wenn Sie dem Upload zusätzliche individuelle Metadaten hinzufügen möchten. Sie können Felder wie folgt verwenden:

![](/_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. Benachrichtigungs-URL

Wenn Sie nach Abschluss der Verarbeitung benachrichtigt werden möchten, können Sie für dieAssembly eine Benachrichtigungs-URL angeben.

![](/_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')

```

Weitere Informationen zu Assembly Notifications finden Sie[auf der Dokumentationsseite von Transloadit](/de/docs/topics/webhooks.md)

### 7. Weitere Assembly-Methoden

Transloadit bietet außerdem Methoden, um Assemblies und derenAssembly Notifications abzurufen oder erneut wiederzugeben.

![](/_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 bietet eine [Templates-API](/de/docs/topics/templates.md) für wiederkehrende Encoding-Aufgaben. So erstellen Sie ein 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
      }
    }
  }
)

```

Darüber hinaus stehen weitere Methoden zum Abrufen, Aktualisieren und Löschen eines Templates zur Verfügung.

![](/_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. Abrechnungsberichte abrufen

Wenn Sie den Abrechnungsbericht Ihres Transloadit-Kontos für einen bestimmten Monat und ein bestimmtes Jahr abrufen möchten, können Sie der Methode `bill` den erforderlichen Monat und das Jahr wie folgt übergeben:

![](/_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)

```

Wenn Sie `month` oder `year` nicht angeben, wird standardmäßig der aktuelle Monat beziehungsweise das aktuelle Jahr verwendet.

### 10. Ratenbegrenzungen

Transloadit setzt Ratenbegrenzungen durch, damit die Nutzung eines einzelnen Kunden keine anderen Kunden beeinträchtigt. Weitere Informationen finden Sie unter [Ratenbegrenzung](/de/docs/api/rate-limiting.md).

Wenn beim Erstellen einer Assembly ein Ratenbegrenzungsfehler auftritt, werden standardmäßig 2 weitere Versuche unternommen, um eine erfolgreiche Antwort zu erhalten. Besteht der Ratenbegrenzungsfehler nach diesen Versuchen weiterhin, wird eine `RateLimitReached`-Ausnahme ausgelöst.

Um die Anzahl der Versuche beim Erstellen einer Assembly zu ändern, können Sie der Assembly wie folgt die Option `tries` übergeben.

![](/_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')

```

## Beispiel

Ein kurzes Tutorial zur Verwendung des Transloadit ruby-sdk, mit dem Sie ein Bild optimieren, MP3-Audio codieren, ID3-Tags hinzufügen und mehr, finden Sie[hier](https://github.com/transloadit/ruby-sdk/tree/master/examples).

## Dokumentation

Eine aktuelle YARD-Dokumentation wird automatisch generiert. Sie können die Dokumentation für das[veröffentlichte Gem](http://rubydoc.info/gems/transloadit/frames) oder den neuesten Stand von[git main](https://github.com/transloadit/ruby-sdk) aufrufen.