SDK para Java

Instalar

Os JARs podem ser baixados manualmente pelo Maven Central Search ou instalados a partir do repositório Maven.

Quem já usa o SDK deve ficar atento ao encerramento do JCenter e atualizar seus arquivos de build para receber as versões mais recentes.

Os exemplos abaixo usam o SDK para Java 2.2.4, incluindo sua API de provedor externo de assinatura.

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 as interações com o SDK começam pela classe com.transloadit.sdk.Transloadit.

Os exemplos completos de Main abaixo são executados em um servidor confiável usando credenciais mantidas no servidor. Substitua os marcadores de posição de credencial, arquivo, Assembly e Template pela configuração do seu servidor. Mantenha a administração da conta e dos Templates no seu backend. Para uploads de aplicativos móveis ou desktop distribuídos aos usuários, use o provedor externo de assinatura descrito abaixo.

Autenticação

O SDK oferece suporte a dois métodos de autenticação:

1. Chave de API + segredo

Em um servidor confiável, o SDK pode assinar requisições usando sua Auth Key e seu Auth Secret. Carregue as credenciais reais do repositório de segredos do seu servidor; nunca inclua o Auth Secret em um aplicativo distribuído nem o adicione ao controle de versão. Inicialização no lado do servidor:

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

2. Provedor externo de assinatura

Para uploads no lado do cliente, mantenha o Auth Secret no seu backend e exija Signature Authentication para o Workspace ou Template usado pelo aplicativo. Consulte o guia do SDK para Android para a integração entre aplicativo e backend.

SignatureProvider.generateSignature(String paramsJson) é executado de forma síncrona. Sua implementação deve obter uma assinatura para os bytes UTF-8 exatos de paramsJson do seu backend HTTPS autenticado, com um tempo limite de rede finito. Lance uma exceção se a autorização, o transporte ou a validação da resposta falhar e execute as requisições do SDK fora da thread da interface. O backend deve autenticar o usuário e autorizar os Steps ou o Template, os destinos, os limites, o nonce e a expiração do upload antes de assinar. Ele não deve assinar parâmetros arbitrários fornecidos pelo cliente. Para um Template de propriedade do servidor, desative allow_steps_override.

O construtor abaixo solicita uma expiração para daqui a cinco minutos; o backend deve validá-la com base no próprio relógio. Retorne apenas a assinatura HMAC-SHA384 aprovada (sha384: seguido de 96 dígitos hexadecimais), nunca o Auth Secret. Não serialize os parâmetros novamente antes de assinar nem reutilize uma assinatura para parâmetros diferentes.

Salve este código auxiliar como SignedClient.java e forneça o SignatureProvider do seu aplicativo:

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);
  }
}

Criar uma Assembly

Para criar uma Assembly, use o 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
    }
  }
}

Obter uma Assembly

O método getAssembly obtém o status JSON de uma Assembly identificada pelo assembly_Id informado.

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

Você também pode obter uma Assembly pela URL com o método getAssemblyByUrl.

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

Cancelar uma Assembly

Para cancelar uma Assembly em execução, use o método cancelAssembly com a Assembly URL HTTPS completa de AssemblyResponse.getSslUrl() (o campo assembly_ssl_url da resposta).

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

O método listAssemblies obtém um array de Assemblies conforme o options informado. Valores válidos para options podem ser page, pagesize, type, fromdate e todate. Consulte a documentação da API da Transloadit para mais detalhes.

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

Criar um Template

Para criar um novo Template, use o método newTemplate, passando o nome do Template como parâmetro. Os nomes dos Steps devem ser únicos: este exemplo redimensiona e otimiza a imagem original em 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
    }
  }
}

Atualizar um Template

Para atualizar um Template, use o método updateTemplate com o Template ID e as opções a atualizar. Passe as Instructions como JSON na opção template, junto com o novo name; consulte a API de atualização 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
    }
  }
}

Excluir um Template

Para excluir um Template, use o método deleteTemplate, passando o 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 obter uma lista de todos os Templates da sua conta, use o 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
    }
  }
}

Obter um Template

Para obter um Template específico, use o método getTemplate, passando o 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
    }
  }
}

Obter fatura

Para obter os dados de cobrança da sua conta de um mês específico, use o método getBill, passando o mês e o ano 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
    }
  }
}

Exemplo

Para ver exemplos totalmente funcionais, consulte /examples.

Documentação

Consulte o Javadoc para ver a documentação completa da API.