SDK de Java

Instalación

Los archivos JAR se pueden descargar manualmente desde la búsqueda de Maven Central o se pueden instalar desde el repositorio de Maven.

Los usuarios existentes deben tener en cuenta el cierre de JCenter y actualizar sus archivos de compilación para obtener las versiones más recientes.

Los ejemplos siguientes están pensados para el SDK de Java 2.2.4, incluida su API de proveedor externo de firmas.

Gradle:

implementation 'com.transloadit.sdk:transloadit:2.2.4'

Maven:

<dependency>
  <groupId>com.transloadit.sdk</groupId>
  <artifactId>transloadit</artifactId>
  <version>2.2.4</version>
</dependency>

Uso

Todas las interacciones con el SDK comienzan con la clase com.transloadit.sdk.Transloadit.

Los ejemplos completos de Main que se muestran a continuación se ejecutan en un servidor de confianza con credenciales almacenadas en el servidor. Sustituye los marcadores de posición de credenciales, archivos, Assemblies y Templates por la configuración de tu propio servidor. Mantén la administración de la cuenta y de los Templates en tu backend. Para las subidas desde aplicaciones móviles o de escritorio distribuidas a los usuarios, usa el proveedor externo de firmas que se describe a continuación.

Autenticación

El SDK admite dos métodos de autenticación:

1. Clave de API + secreto

En un servidor de confianza, el SDK puede firmar solicitudes con tu Auth Key y tu Auth Secret. Carga las credenciales reales desde el almacén de secretos de tu servidor; nunca incluyas el Auth Secret en una aplicación distribuida ni lo guardes en el control de versiones. Inicialización del lado del servidor:

Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

2. Proveedor externo de firmas

Para las subidas desde el cliente, mantén el Auth Secret en tu backend y exige Signature Authentication para el Workspace o Template que usa la aplicación. Consulta la guía del SDK de Android para integrar la aplicación con el backend.

SignatureProvider.generateSignature(String paramsJson) se ejecuta de forma síncrona. Tu implementación debe obtener de tu backend HTTPS autenticado una firma para los bytes UTF-8 exactos de paramsJson, con un tiempo de espera de red finito. Lanza una excepción si falla la autorización, el transporte o la validación de la respuesta, y ejecuta las solicitudes del SDK fuera del hilo de la interfaz de usuario. El backend debe autenticar al usuario y autorizar los Steps o el Template de la subida, los destinos, los límites, el nonce y el vencimiento antes de firmar. No debe firmar parámetros arbitrarios proporcionados por el cliente. Para un Template controlado por el servidor, desactiva allow_steps_override.

El constructor siguiente solicita un vencimiento dentro de cinco minutos; el backend debe validarlo con su propio reloj. Devuelve únicamente la firma HMAC-SHA384 aprobada (sha384: seguido de 96 dígitos hexadecimales), nunca el Auth Secret. No vuelvas a serializar los parámetros antes de firmar ni reutilices una firma para parámetros diferentes.

Guarda este código auxiliar como SignedClient.java y proporciona SignatureProvider de tu aplicación:

import com.transloadit.sdk.SignatureProvider;
import com.transloadit.sdk.Transloadit;

public final class SignedClient {
  private SignedClient() {}

  public static Transloadit create(String authKey, SignatureProvider approvedSignatures) {
    return new Transloadit(authKey, approvedSignatures);
  }
}

Crear una Assembly

Para crear una Assembly, usa el método newAssembly.

import com.transloadit.sdk.Assembly;
import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.AssemblyResponse;
import java.io.File;
import java.util.HashMap;
import java.util.Map;

public class Main {

  public static void main(String[] args) {
    Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

    Assembly assembly = transloadit.newAssembly();

    Map<String, Object> stepOptions = new HashMap<>();
    stepOptions.put("width", 75);
    stepOptions.put("height", 75);
    assembly.addStep("resize", "/image/resize", stepOptions);

    assembly.addFile(new File("PATH/TO/FILE.jpg"));
    // you can skip this part if you don't want to wait till the
    // assembly is complete
    assembly.setShouldWaitForCompletion(true);
    try {
      AssemblyResponse response = assembly.save();

      System.out.println(response.getId());
      System.out.println(response.getUrl());
      System.out.println(response.json());
    } catch (RequestException | LocalOperationException e) {
      // handle exception here
    }
  }
}

Recuperar una Assembly

El método getAssembly recupera el estado JSON de una Assembly identificada por el assembly_Id proporcionado.

import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.AssemblyResponse;

public class Main {

  public static void main(String[] args) {
    Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

    try {
      AssemblyResponse response = transloadit.getAssembly("ASSEMBLY_ID");

      System.out.println(response.getUrl());
      System.out.println(response.json());
    } catch (RequestException | LocalOperationException e) {
      // handle exception here
    }
  }
}

También puedes obtener una Assembly mediante su URL con el método getAssemblyByUrl.

    AssemblyResponse response = transloadit.getAssemblyByUrl("ASSEMBLY_URL");

Cancelar una Assembly

Para cancelar una Assembly en ejecución, usa el método cancelAssembly con la URL HTTPS completa de la Assembly obtenida de AssemblyResponse.getSslUrl() (el campo assembly_ssl_url de la respuesta).

import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.AssemblyResponse;

public class Main {

  public static void main(String[] args) {
    Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

    try {
      AssemblyResponse response = transloadit.cancelAssembly("ASSEMBLY_URL");

      System.out.println(response.isCanceled()); // true when cancellation succeeded
    } catch (RequestException | LocalOperationException e) {
      // handle exception here
    }
  }
}

Listar Assemblies

El método listAssemblies recupera un array de Assemblies según las options proporcionadas. Las options válidas pueden ser page, pagesize, type, fromdate y todate. Consulta la documentación de la API de Transloadit para obtener más detalles.

import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.ListResponse;
import java.util.HashMap;
import java.util.Map;

public class Main {

  public static void main(String[] args) {
    Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

    try {
      Map<String, Object> options = new HashMap<>();
      options.put("pagesize", 10);
      ListResponse response = transloadit.listAssemblies(options);

      System.out.println(response.size()); // number of assemblies on the list.
      System.out.println(response.getItems()); // returns an iterable json array
    } catch (RequestException | LocalOperationException e) {
      // handle exception here
    }
  }
}

Crear un Template

Para crear un Template nuevo, usa el método newTemplate y pasa el nombre del Template como parámetro. Los nombres de los Steps deben ser únicos: este ejemplo redimensiona y optimiza la imagen original en Steps separados.

import com.transloadit.sdk.Template;
import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.Response;
import java.util.HashMap;
import java.util.Map;

public class Main {

  public static void main(String[] args) {
    Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

    Template template = transloadit.newTemplate("MY_TEMPLATE_NAME");

    Map<String, Object> resizeOptions = new HashMap<>();
    resizeOptions.put("width", 75);
    resizeOptions.put("height", 75);

    Map<String, Object> optimizeOptions = new HashMap<>();
    optimizeOptions.put("use", ":original");

    template.addStep("resize", "/image/resize", resizeOptions);
    template.addStep("optimize", "/image/optimize", optimizeOptions);

    try {
      Response response = template.save();

      System.out.println(response.json());
      System.out.println(response.json().getString("id")); // gets the Template ID.
    } catch (RequestException | LocalOperationException e) {
      // handle exception here
    }
  }
}

Actualizar un Template

Para actualizar un Template, usa el método updateTemplate y pasa el Template ID y las opciones que quieres actualizar como parámetros. Pasa las Instructions en formato JSON en la opción template, junto con el nuevo name; consulta la API de actualización de Templates.

import com.transloadit.sdk.Steps;
import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.Response;
import java.util.HashMap;
import java.util.Map;
import org.json.JSONObject;

public class Main {

  public static void main(String[] args) {
    Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

    Steps steps = new Steps();

    Map<String, Object> stepOptions = new HashMap<>();
    stepOptions.put("width", 150);
    stepOptions.put("height", 150);
    steps.addStep("resize", "/image/resize", stepOptions);

    Map<String, Object> instructions = new HashMap<>();
    instructions.put("steps", steps.toMap());

    Map<String, Object> templateOptions = new HashMap<>();
    templateOptions.put("template", new JSONObject(instructions).toString());
    templateOptions.put("name", "MY_NEW_TEMPLATE_NAME");

    try {
      Response response = transloadit.updateTemplate("TEMPLATE_ID", templateOptions);
    } catch (RequestException | LocalOperationException e) {
      // handle exception here
    }
  }
}

Eliminar un Template

Para eliminar un Template, usa el método deleteTemplate y pasa el Template ID como parámetro.

import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.Response;
import java.util.HashMap;

public class Main {

  public static void main(String[] args) {
    Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

    try {
      Response response = transloadit.deleteTemplate("TEMPLATE_ID");
    } catch (RequestException | LocalOperationException e) {
      // handle exception here
    }
  }
}

Listar Templates

Para obtener una lista de todos los Templates de tu cuenta, usa el método listTemplates.

import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.ListResponse;

public class Main {

  public static void main(String[] args) {
    Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

    try {
      ListResponse response = transloadit.listTemplates();

      System.out.println(response.size()); // number of assemblies on the list.
      System.out.println(response.getItems()); // returns an iterable json array
    } catch (RequestException | LocalOperationException e) {
      // handle exception here
    }
  }
}

Recuperar un Template

Para obtener un Template específico, usa el método getTemplate y pasa el Template ID como parámetro.

import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.Response;

public class Main {

  public static void main(String[] args) {
    Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

    try {
      Response response = transloadit.getTemplate("TEMPLATE_ID");
      System.out.println(response.json());
    } catch (RequestException | LocalOperationException e) {
      // handle exception here
    }
  }
}

Recuperar la factura

Para obtener los detalles de facturación de tu cuenta correspondientes a un mes específico, usa el método getBill y pasa el mes y el año como parámetros.

import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.Response;

public class Main {

  public static void main(String[] args) {
    Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", "YOUR_TRANSLOADIT_SECRET");

    try {
      Response response = transloadit.getBill(3, 2017);

      System.out.println(response.json());
    } catch (RequestException | LocalOperationException e) {
      // handle exception here
    }
  }
}

Ejemplo

Para consultar ejemplos completamente funcionales, revisa /examples.

Documentación

Consulta Javadoc para ver la documentación completa de la API.