SDK Ruby

Notre gem Ruby vous permet d’automatiser le téléversement de fichiers via la REST API de Transloadit.

Si vous utilisez Ruby on Rails et cherchez plutôt à intégrer le navigateur pour gérer les téléversements de fichiers, nous proposons également un SDK Ruby on Rails (English) prêt à l’emploi.

Installation

gem install transloadit

Utilisation

Pour commencer, vous devez charger la gem « transloadit » :

$ irb
>> require 'transloadit'
=> true

Créez ensuite une instance Transloadit, qui conservera vos informations d’authentification et nous permettra d’envoyer des requêtes à l’API.

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

1. Redimensionner et stocker une image

Cet exemple montre comment créer une Assembly pour redimensionner une image et stocker le résultat sur 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

Note

La méthode submit! de l’Assembly est dépréciée et a été remplacée par create!. La méthode submit! reste disponible comme alias de create! pour assurer la rétrocompatibilité.

Lorsque la méthode create! retourne, le fichier a été téléversé, mais son traitement n’est peut-être pas encore terminé. Nous pouvons utiliser l’objet retourné pour vérifier si le traitement est terminé ou examiner d’autres attributs de la requête.

# 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

Il est important de noter qu’aucune de ces requêtes n’est « en direct » (à l’exception de la méthode cancel!). Elles vérifient toutes la réponse fournie par l’API au moment où l’Assembly a été créée. Vous devez explicitement demander à l’Assembly de recharger ses résultats depuis l’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 général, vous utilisez la syntaxe d’accès par hash pour interroger n’importe quel attribut direct de la réponse. Les méthodes suffixées par un point d’interrogation offrent une manière plus lisible d’interroger l’état (par exemple, assembly.completed? plutôt que de vérifier le résultat de assembly[:ok]). Les méthodes suffixées par un point d’exclamation effectuent une requête en direct auprès de l’API HTTP de Transloadit.

2. Téléverser plusieurs fichiers

Vous pouvez transmettre plusieurs fichiers à la méthode create! afin de téléverser plus d’un fichier dans la même requête. Vous pouvez aussi passer un seul Step pour le paramètre steps, sans avoir à l’encapsuler dans 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')
)

Vous pouvez également passer un tableau de fichiers à la méthode create!. Il suffit de développer le tableau avec l’opérateur splat *.

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

3. Assembly parallèle

Transloadit vous permet d’exécuter plusieurs étapes de traitement en parallèle. Il vous suffit d’utiliser use sur d’autres Steps. En suivant leur exemple (English) :

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

Vous pouvez aussi indiquer à un Step d’utiliser le fichier original téléversé en passant le symbole :original au lieu d’un autre Step.

Consultez la documentation YARD pour en savoir plus sur l’utilisation de use.

4. Créer une Assembly avec des Templates

Transloadit vous permet d’utiliser des Templates personnalisés pour les tâches d’encodage récurrentes. Pour les utiliser, procédez comme suit :

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

Vous pouvez combiner vos Steps avec ce Template et même utiliser des variables. La documentation de Transloadit (English) propose quelques bons exemples à ce sujet.

5. Utiliser des champs

Transloadit vous permet de soumettre des valeurs de champs de formulaire que vous récupérerez dans la notification. C’est très pratique si vous souhaitez ajouter des métadonnées personnalisées supplémentaires au téléversement lui-même. Vous pouvez utiliser les champs comme suit :

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 notification

Si vous souhaitez recevoir une notification à la fin du traitement, vous pouvez fournir une URL de notification pour l’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')

Pour en savoir plus sur les Notifications, consultez la page de documentation de Transloadit (English).

7. Autres méthodes pour les Assemblies

Transloadit fournit également des méthodes pour récupérer ou rejouer des Assemblies et leurs 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 fournit une API de Templates (English) pour les tâches d’encodage récurrentes. Voici comment créer 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
      }
    }
  }
)

Il existe également d’autres méthodes pour récupérer, mettre à jour et supprimer 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. Obtenir les rapports de facturation

Si vous souhaitez récupérer le rapport de facturation de votre compte Transloadit pour un mois et une année donnés, vous pouvez utiliser la méthode bill en lui passant le mois et l’année souhaités, comme suit :

require 'transloadit'

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

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

Si vous ne précisez pas month ou year, les valeurs par défaut seront le mois ou l’année en cours.

10. Limites de débit

Transloadit applique des limites de débit afin de garantir qu’aucun client ne soit pénalisé par l’utilisation d’un autre client. Consultez Limitation de débit.

Lors de la création d’une Assembly, si une erreur de limite de débit est reçue, 2 tentatives supplémentaires sont effectuées par défaut pour obtenir une réponse réussie. Si l’erreur de limite de débit persiste après ces tentatives, une exception RateLimitReached sera levée.

Pour modifier le nombre de tentatives effectuées lors de la création d’une Assembly, vous pouvez passer l’option tries à votre Assembly, comme suit.

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

Exemple

Vous trouverez ici un petit tutoriel montrant comment utiliser le ruby-sdk de Transloadit pour optimiser une image, encoder de l’audio MP3, ajouter des tags ID3, et plus encore.

Documentation

Une documentation YARD à jour est générée automatiquement. Vous pouvez consulter la documentation de la gem publiée ou de la dernière version de la branche git main.