Transloadit

Assembly Instructions

Para conocer las Assembly Instructions, veamos este ejemplo:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "imported_watermark": {
      "robot": "/http/import",
      "url": "https://transloadit.com/assets/images/face.jpg"
    },
    "resized": {
      "robot": "/image/resize",
      "use": {
        "steps": [
          { "name": ":original", "as": "base" },
          { "name": "imported_watermark", "as": "watermark" }
        ]
      },
      "width": 400,
      "height": 400,
      "watermark_position": "center",
      "watermark_size": "30%"
    },
    "exported": {
      "robot": "/s3/store",
      "use": [":original", "resized"],
      "credentials": "my_cloud_storage_credentials",
      "path": "/my_images/${file.id}/${file.url_name}"
    }
  }
}

El ejemplo muestra cuatro Steps: :original, imported_watermark, resized y exported. Puedes asignar a tus Steps cualquier nombre que quieras, excepto :original, que hace referencia a los archivos subidos y debe usar el Robot 🤖/upload/handle.

Observa cómo los Steps :original e imported_watermark se usan como entrada del Step resized mediante el parámetro use. Aquí usamos la agrupación de Steps mediante la sintaxis «as» para pasar varios archivos al Step resized al mismo tiempo: uno «como» imagen base y otro «como» marca de agua que se imprimirá sobre la imagen base. Los distintos Robots ofrecen diferentes posibilidades para la sintaxis «as», ¡lo que la hace muy potente!

Luego, el Step exported simplemente usa como entrada la mayoría de los demás Steps y los almacena en S3, uno por uno, sin agrupación de Steps. Las Variables ${file.id} y ${file.url_name} utilizadas están disponibles para todos los Steps y pueden usarse para crear nombres de archivo únicos para cada archivo.

De esta manera, podremos procesar los archivos subidos, aplicarles una marca de agua y exportar a S3 tanto la imagen subida como la versión redimensionada con marca de agua.

No todos los Steps requieren entradas. Por ejemplo, nuestro Step imported_watermark proporciona la primera entrada al descargarla, por lo que omitiremos use allí. Otros ejemplos de Robots que no requieren archivos de entrada son 🤖/html/convert, que puede tomar una captura de pantalla de un sitio web y crear así el primer archivo, y 🤖/upload/handle, que obtiene sus archivos de los visitantes de tu aplicación en lugar de otro Step.

Con un solo cambio sencillo, podríamos hacer que esta aplicación fuera realmente dinámica. Imagina reemplazar la URL estática del Step imported_watermark por una dinámica proveniente de un campo de tu aplicación. Solo necesitamos cambiar el parámetro "url" a "${fields.watermark_url}" en nuestro Template y, luego, proporcionar este campo de entrada en nuestro formulario web HTML (o mediante un campo POST adicional en nuestra solicitud) para que la aplicación de la marca de agua sea realmente dinámica.

Parámetros de Step

Como puedes ver, cada Step se define como un objeto con varias propiedades o parámetros. De hecho, la mayoría son parámetros de Robot, ya que indican, por ejemplo, el width de una imagen después de redimensionarla. Todos se explican en la documentación de Robots correspondiente. Sin embargo, también hay 5 parámetros que dan instrucciones al propio motor de Assembly y definen qué Robots se invocan y cómo se interconectan:

  • use

    string | Array<string> | Array<object> | object

    Especifica qué Step o Steps se usarán como entrada.

    • Puedes elegir cualquier nombre para los Steps, excepto ":original" (reservado para las subidas de usuarios gestionadas por Transloadit)
    • Puedes proporcionar varios Steps como entrada mediante arrays: 
      {
  "use": [
    ":original",
    "encoded",
    "resized"
  ]
}
    • También puedes etiquetar los Steps de entrada con as para comunicar la intención semántica a los Robots: 
      {
  "use": [
    {
      "name": ":original",
      "as": "image"
    },
    {
      "name": ":original",
      "as": "mask"
    }
  ]
}

  • robot — obligatorio

    string

    Especifica qué Robot debe procesar los archivos enviados a este Step.

    Consulta todos los Robots, cada uno con sus propios parámetros, como width para controlar cómo se cambia el tamaño de una imagen. La lista completa de parámetros de cada Robot está disponible en la documentación de Robots.

  • result

    boolean(valor predeterminado: false)

    Indica si los resultados de este Step deben aparecer en el Assembly Status JSON

  • force_accept

    boolean(valor predeterminado: false)

    Forzar a un Robot a aceptar un tipo de archivo que habría ignorado.

    De forma predeterminada, los Robots ignoran los archivos que no reconocen. 🤖/video/encode, por ejemplo, ignorará sin problemas las imágenes de entrada.

    Si configuras el parámetro force_accept como true, puedes forzar a los Robots a aceptar todos los archivos que reciban. Esto normalmente provocará errores y solo debe usarse para depuración o para abordar casos extremos.

  • ignore_errors

    boolean | Array<meta | execute>(valor predeterminado: [])

    Ignorar errores durante fases específicas del procesamiento.

    Establecer este parámetro en ["meta"] hará que el Robot ignore los errores durante la extracción de metadatos.

    Establecer este parámetro en ["execute"] hará que el Robot ignore los errores durante la fase principal de ejecución.

    Configurar este parámetro como true equivale a ["meta", "execute"] y hará que se ignoren los errores en ambas fases.

Para obtener orientación práctica y conocer las combinaciones de valores (incluido el comportamiento específico de las importaciones), consulta El parámetro ignore_errors.

Orden de ejecución

Para acelerar las Assemblies, los Steps se ejecutarán en cuanto sus Steps de entrada emitan archivos. En otras palabras, muchas operaciones se procesan en paralelo. Por ejemplo, supongamos que quieres codificar un video subido y también extraer miniaturas de él:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "encoded": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "web/mp4/1080p"
    },
    "thumbed": {
      "use": ":original",
      "robot": "/video/thumbs",
      "count": 4
    },
    "exported": {
      "use": ["encoded", "thumbed"],
      "robot": "/s3/store",
      "credentials": "YOUR_S3_CREDENTIALS"
    }
  }
}

Los Steps encoded y thumbed se ejecutarán en paralelo en cuanto finalice la subida del primer archivo. El Step exported se activa para cada uno de los archivos provenientes de encoded y thumbed. Es probable que las miniaturas lleguen a tu bucket de S3 antes que el video optimizado para iPad, aunque se hayan definido después. Por lo tanto, el orden de los Steps no es realmente importante. El parámetro use define la entrada de cada Step y, en última instancia, determina cómo se encadenan nuestros Steps.

Filtrado para hacer que los Steps sean condicionales

Con 🤖/file/filter, puedes ejecutar Steps según las propiedades de un archivo. Esto te permite crear Assembly Instructions para: procesar subidas tanto de video como de audio, rechazar archivos demasiado pequeños, aplicar un efecto únicamente a imágenes que tengan áreas transparentes, etc. Estas y otras posibilidades también se explican en la documentación del Robot.

Assembly Variables

Para obtener información sobre Assembly Variables como ${file.id}, ${assembly.id}, ${fields.*} y otras, consulta la página dedicada a Assembly Variables.