SDK Java

Installer

Vous pouvez télécharger les fichiers JAR manuellement depuis Maven Central Search, ou les installer depuis le dépôt Maven.

Si vous utilisez déjà le SDK, vous devriez prendre connaissance de l’arrêt de JCenter et mettre à jour vos fichiers de build afin de recevoir les versions les plus récentes.

Les exemples ci-dessous ciblent le SDK Java 2.2.4, y compris son API de fournisseur externe de signatures.

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>

Utilisation

Toutes les interactions avec le SDK commencent par la classe com.transloadit.sdk.Transloadit.

Les exemples complets Main ci-dessous s’exécutent sur un serveur de confiance avec des informations d’accès conservées sur ce serveur. Remplacez les valeurs de substitution des informations d’accès, du fichier, de l’Assembly et du Template par celles de votre propre configuration serveur. Conservez l’administration du compte et des Templates sur votre backend. Pour les envois depuis des applications mobiles ou de bureau distribuées aux utilisateurs, utilisez le fournisseur externe de signatures décrit ci-dessous.

Authentification

Le SDK prend en charge deux méthodes d’authentification :

1. Clé API + secret

Sur un serveur de confiance, le SDK peut signer les requêtes avec votre Auth Key et votre Auth Secret. Chargez les informations d’accès réelles depuis le coffre de secrets de votre serveur ; n’incluez jamais l’Auth Secret dans une application distribuée et ne l’enregistrez jamais dans un système de gestion de versions. Initialisation côté serveur :

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

2. Fournisseur externe de signatures

Pour les envois côté client, conservez l’Auth Secret sur votre backend et imposez la Signature Authentication pour le Workspace ou le Template utilisé par l’application. Consultez le guide du SDK Android pour l’intégration entre l’application et le backend.

SignatureProvider.generateSignature(String paramsJson) s’exécute de manière synchrone. Votre implémentation doit obtenir une signature des octets UTF-8 exacts de paramsJson auprès de votre backend HTTPS authentifié, avec un délai d’attente réseau fini. Levez une exception en cas d’échec de l’autorisation, du transport ou de la validation de la réponse, et exécutez les requêtes du SDK en dehors du thread de l’interface utilisateur. Le backend doit authentifier l’utilisateur et autoriser les Steps ou le Template, les destinations, les limites, le nonce et la date d’expiration de l’envoi avant de signer. Il ne doit pas signer des paramètres arbitraires fournis par le client. Pour un Template appartenant au serveur, désactivez allow_steps_override.

Le constructeur ci-dessous demande une expiration dans cinq minutes ; le backend doit la valider en se fondant sur sa propre horloge. Ne renvoyez que la signature HMAC-SHA384 approuvée (sha384: suivi de 96 chiffres hexadécimaux), jamais l’Auth Secret. Ne sérialisez pas à nouveau les paramètres avant de les signer et ne réutilisez pas une signature pour des paramètres différents.

Enregistrez cet utilitaire sous SignedClient.java et fournissez le SignatureProvider de votre application :

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

Créer une Assembly

Pour créer une Assembly, utilisez la méthode 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
    }
  }
}

Récupérer une Assembly

La méthode getAssembly récupère le statut JSON d’une Assembly identifiée par le assembly_Id fourni.

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

Vous pouvez aussi récupérer une Assembly par son URL avec la méthode getAssemblyByUrl.

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

Annuler une Assembly

Pour annuler une Assembly en cours d’exécution, utilisez la méthode cancelAssembly avec l’URL HTTPS complète de l’Assembly provenant de AssemblyResponse.getSslUrl() (le champ assembly_ssl_url de la réponse).

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

Lister les Assemblies

La méthode listAssemblies récupère un tableau d’Assemblies en fonction de options. Les options valides peuvent être page, pagesize, type, fromdate et todate. Veuillez consulter la documentation de l’API Transloadit pour plus de détails.

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

Créer un Template

Pour créer un nouveau Template, utilisez la méthode newTemplate en passant le nom du Template en paramètre. Les noms des Steps doivent être uniques : cet exemple redimensionne et optimise l’image d’origine dans des Steps distincts.

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

Mettre à jour un Template

Pour mettre à jour un Template, utilisez la méthode updateTemplate avec l’identifiant du Template et les options à mettre à jour. Transmettez les Instructions au format JSON dans l’option template, avec le nouveau name ; consultez l’API de mise à jour des 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
    }
  }
}

Supprimer un Template

Pour supprimer un Template, utilisez la méthode deleteTemplate en passant l’identifiant du Template en paramètre.

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

Lister les Templates

Pour obtenir la liste de tous les Templates de votre compte, utilisez la méthode 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
    }
  }
}

Récupérer un Template

Pour récupérer un Template donné, utilisez la méthode getTemplate en passant l’identifiant du Template en paramètre.

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

Récupérer la facture

Pour récupérer les détails de facturation de votre compte pour un mois donné, utilisez la méthode getBill en passant le mois et l’année en paramètres.

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

Exemple

Pour des exemples entièrement fonctionnels, consultez /examples.

Documentation

Consultez Javadoc pour la documentation complète de l’API.