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", System.getenv("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", System.getenv("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();
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
System.out.println(response.getId());
System.out.println(response.getUrl());
System.out.println(response.json());
} catch (RequestException | LocalOperationException e) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
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", System.getenv("TRANSLOADIT_SECRET"));
try {
AssemblyResponse response = transloadit.getAssembly("ASSEMBLY_ID");
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
System.out.println(response.getUrl());
System.out.println(response.json());
} catch (RequestException | LocalOperationException e) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
Você também pode obter uma Assembly pela URL com o método getAssemblyByUrl.
AssemblyResponse response = transloadit.getAssemblyByUrl("ASSEMBLY_URL");
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
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", System.getenv("TRANSLOADIT_SECRET"));
try {
AssemblyResponse response = transloadit.cancelAssembly("ASSEMBLY_URL");
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
System.out.println(response.isCanceled()); // true when cancellation succeeded
} catch (RequestException | LocalOperationException e) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
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", System.getenv("TRANSLOADIT_SECRET"));
try {
Map<String, Object> options = new HashMap<>();
options.put("pagesize", 10);
ListResponse response = transloadit.listAssemblies(options);
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
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) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
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", System.getenv("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();
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
System.out.println(response.json());
System.out.println(response.json().getString("id")); // gets the Template ID.
} catch (RequestException | LocalOperationException e) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
Atualizar um Template
Para atualizar um Template, use o método updateTemplate com o Template ID e as opções
a atualizar. Passe a configuração de processamento 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", System.getenv("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);
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
} catch (RequestException | LocalOperationException e) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
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", System.getenv("TRANSLOADIT_SECRET"));
try {
Response response = transloadit.deleteTemplate("TEMPLATE_ID");
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
} catch (RequestException | LocalOperationException e) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
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", System.getenv("TRANSLOADIT_SECRET"));
try {
ListResponse response = transloadit.listTemplates();
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
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) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
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", System.getenv("TRANSLOADIT_SECRET"));
try {
Response response = transloadit.getTemplate("TEMPLATE_ID");
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
System.out.println(response.json());
} catch (RequestException | LocalOperationException e) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
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", System.getenv("TRANSLOADIT_SECRET"));
try {
Response response = transloadit.getBill(3, 2017);
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
System.out.println(response.json());
} catch (RequestException | LocalOperationException e) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
Exemplo
Para ver exemplos totalmente funcionais, consulte /examples.
Documentação
Consulte o Javadoc para ver a documentação completa da API.