Java SDK
Installation
Die JARs können manuell über die Maven Central Search heruntergeladen oder aus dem Maven-Repository installiert werden.
Bestehende Nutzer sollten die Abschaltung von JCenter beachten und ihre Build-Dateien aktualisieren, um die neuesten Versionen zu erhalten.
Die folgenden Beispiele sind für das Java SDK 2.2.4 ausgelegt,
einschließlich seiner API für externe Signaturanbieter.
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>
Verwendung
Alle Interaktionen mit dem SDK beginnen mit der Klasse com.transloadit.sdk.Transloadit.
Die folgenden vollständigen Beispiele für Main laufen auf einem
vertrauenswürdigen Server mit serverseitig gespeicherten Zugangsdaten. Ersetzen Sie die Platzhalter
für Zugangsdaten, Dateien, Assemblies und Templates durch Ihre eigene Serverkonfiguration.
Verwalten Sie Ihr Konto und Ihre Templates im Backend. Verwenden Sie für Uploads aus mobilen Apps
oder Desktop-Apps, die an Nutzer verteilt werden, den unten beschriebenen externen Signaturanbieter.
Authentifizierung
Das SDK unterstützt zwei Authentifizierungsmethoden:
1. API-Schlüssel + geheimer Schlüssel
Auf einem vertrauenswürdigen Server kann das SDK Anfragen mit Ihrem Auth Key und Ihrem Auth Secret signieren. Laden Sie die tatsächlichen Zugangsdaten aus dem Secrets-Speicher Ihres Servers; liefern Sie das Auth Secret niemals in einer App aus und nehmen Sie es niemals in die Versionsverwaltung auf. Serverseitige Initialisierung:
Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", System.getenv("TRANSLOADIT_SECRET"));
2. Externer Signaturanbieter
Behalten Sie für clientseitige Uploads das Auth Secret in Ihrem Backend und verlangen Sie Signature Authentication für den Workspace oder das Template, den bzw. das die App verwendet. Informationen zur Integration von Anwendung und Backend finden Sie in der Anleitung zum Android SDK.
SignatureProvider.generateSignature(String paramsJson) wird synchron ausgeführt. Ihre Implementierung muss von Ihrem
HTTPS-Backend, das eine Authentifizierung verlangt, eine Signatur für die exakten UTF-8-Bytes von
paramsJson abrufen und dabei ein endliches Netzwerk-Timeout verwenden.
Lösen Sie eine Ausnahme aus, wenn die Autorisierung, die Übertragung oder die Validierung der
Antwort fehlschlägt, und führen Sie SDK-Anfragen außerhalb des UI-Threads aus. Das Backend muss
vor dem Signieren den Nutzer authentifizieren und die Steps oder das Template, die Ziele,
Grenzwerte, Nonce und Ablaufzeit des Uploads autorisieren. Es darf keine beliebigen, vom Client
gelieferten Parameter signieren. Deaktivieren Sie für ein serverseitig verwaltetes Template
allow_steps_override.
Der folgende Konstruktor fordert eine Ablaufzeit an, die fünf Minuten in der Zukunft liegt;
das Backend muss sie anhand seiner eigenen Uhr validieren. Geben Sie nur die genehmigte
HMAC-SHA384-Signatur zurück (sha384: gefolgt von 96 hexadezimalen Ziffern),
niemals das Auth Secret. Serialisieren Sie die Parameter vor dem Signieren nicht erneut und
verwenden Sie eine Signatur nicht für andere Parameter wieder.
Speichern Sie diese Hilfsklasse als SignedClient.java und übergeben Sie die
Implementierung von SignatureProvider aus Ihrer Anwendung:
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);
}
}
Assembly erstellen
Um eine Assembly zu erstellen, verwenden Sie die Methode 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);
}
}
}
Assembly abrufen
Die Methode getAssembly ruft den JSON-Status der durch die angegebene
assembly_Id identifizierten Assembly ab.
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);
}
}
}
Mit der Methode getAssemblyByUrl können Sie eine Assembly auch über ihre URL abrufen.
AssemblyResponse response = transloadit.getAssemblyByUrl("ASSEMBLY_URL");
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
Assembly abbrechen
Um eine laufende Assembly abzubrechen, verwenden Sie die Methode cancelAssembly
mit der vollständigen Assembly URL (HTTPS) aus AssemblyResponse.getSslUrl()
(dem Antwortfeld assembly_ssl_url).
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);
}
}
}
Assemblies auflisten
Die Methode listAssemblies ruft anhand der angegebenen
options ein Array von Assemblies ab.
Gültige options sind page,
pagesize, type,
fromdate und todate. Weitere Einzelheiten
finden Sie in der Transloadit-API-Dokumentation.
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);
}
}
}
Template erstellen
Um ein neues Template zu erstellen, verwenden Sie die Methode newTemplate und übergeben den
Namen des Templates als Parameter. Step-Namen müssen eindeutig sein: Dieses Beispiel ändert die
Größe des Originalbilds und optimiert es in separaten Steps.
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);
}
}
}
Template aktualisieren
Um ein Template zu aktualisieren, verwenden Sie die Methode updateTemplate und übergeben die
Template ID sowie die zu aktualisierenden Optionen als Parameter.
Übergeben Sie die Verarbeitungsanweisungen als JSON in der Option template zusammen mit dem
neuen Wert für name; siehe die
API zum Aktualisieren von 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);
}
}
}
Template löschen
Um ein Template zu löschen, verwenden Sie die Methode deleteTemplate und übergeben die Template ID
als Parameter.
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);
}
}
}
Templates auflisten
Um eine Liste aller Templates in Ihrem Konto abzurufen, verwenden Sie die Methode 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);
}
}
}
Template abrufen
Um ein bestimmtes Template abzurufen, verwenden Sie die Methode getTemplate und übergeben die
Template ID als Parameter.
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);
}
}
}
Rechnung abrufen
Um die Abrechnungsdetails Ihres Kontos für einen bestimmten Monat abzurufen, verwenden Sie die
Methode getBill und übergeben Monat und Jahr als Parameter.
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);
}
}
}
Beispiel
Vollständig funktionsfähige Beispiele finden Sie unter /examples.
Dokumentation
Die vollständige API-Dokumentation finden Sie in der Javadoc.