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", "YOUR_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", "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
    }
  }
}

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

Mit der Methode getAssemblyByUrl können Sie eine Assembly auch über ihre URL abrufen.

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

Assembly abbrechen

Um eine ausgeführte 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", "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
    }
  }
}

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

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

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 Instructions 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", "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
    }
  }
}

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", "YOUR_TRANSLOADIT_SECRET");

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

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

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", "YOUR_TRANSLOADIT_SECRET");

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

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", "YOUR_TRANSLOADIT_SECRET");

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

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

Beispiel

Vollständig funktionsfähige Beispiele finden Sie unter /examples.

Dokumentation

Die vollständige API-Dokumentation finden Sie in der Javadoc.