Transloadit

Ruby SDK

transloadit/ruby-sdk

Mit unserem Ruby-Gem können Sie Datei-Uploads über die Transloadit REST 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 (English) zur Verfügung.

Installation

gem install transloadit

Verwendung

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

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

Erstellen Sie anschließend eine Transloadit-Instanz. Diese verwaltet Ihre Authentifizierungsdaten und ermöglicht Anfragen an die API.

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 zu speichern.

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

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.

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

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

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

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:

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 finden Sie in der YARD-Dokumentation.

4. Eine Assembly mit Templates erstellen

Mit Transloadit können Sie individuelle Templates für wiederkehrende Encoding-Aufgaben verwenden. Gehen Sie dazu wie folgt vor:

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

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 die Assembly eine Benachrichtigungs-URL angeben.

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

7. Weitere Assembly-Methoden

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

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 für wiederkehrende Encoding-Aufgaben. So erstellen Sie ein 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
      }
    }
  }
)

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

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:

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.

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.

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.

Dokumentation

Eine aktuelle YARD-Dokumentation wird automatisch generiert. Sie können die Dokumentation für das veröffentlichte Gem oder den neuesten Stand von git main aufrufen.