Java SDK
インストール
JAR は Maven Central Search から手動でダウンロードするか、Maven リポジトリからインストールできます。
すでに利用している場合は、JCenter のサービス終了を確認し、最新バージョンを取得できるようにビルドファイルを更新してください。
以下の例は Java SDK 2.2.4 を対象とし、外部署名プロバイダー API も使用します。
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>
使い方
SDK とのすべてのやり取りは、com.transloadit.sdk.Transloadit クラスから始まります。
以下の完全な Main の例は、サーバーで保持する認証情報を使用し、信頼できるサーバー上で実行します。認証情報、ファイル、Assembly、Template のプレースホルダーを、実際のサーバー設定に置き換えてください。アカウントと Template の管理はバックエンドで行ってください。ユーザーに配布するモバイルアプリやデスクトップアプリからのアップロードには、後述の外部署名プロバイダーを使用してください。
認証方法
SDK は次の 2 つの認証方法に対応しています。
1. API キーとシークレット
信頼できるサーバー上では、SDK が Auth Key と Auth Secret を使用してリクエストに署名できます。実際の認証情報はサーバーのシークレットストアから読み込んでください。Auth Secret を配布するアプリに含めたり、ソース管理にコミットしたりしないでください。サーバー側での初期化は次のとおりです。
Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", System.getenv("TRANSLOADIT_SECRET"));
2. 外部署名プロバイダー
クライアントからアップロードする場合は、Auth Secret をバックエンドで保持し、アプリが使用する Workspace または Template で Signature Authentication を必須にしてください。アプリとバックエンドの連携については、Android SDK ガイドを参照してください。
SignatureProvider.generateSignature(String paramsJson) は同期的に実行されます。実装では、paramsJson の正確な UTF-8 バイト列に対する署名を、認証済みの HTTPS バックエンドから取得する必要があります。ネットワークタイムアウトには有限の値を設定してください。認可、通信、レスポンスの検証に失敗した場合は例外をスローし、SDK のリクエストは UI スレッド以外で実行してください。バックエンドでは署名する前にユーザーを認証し、アップロードの Step または Template、送信先、制限、nonce、有効期限を認可する必要があります。クライアントから渡された任意の params に署名してはいけません。サーバーが所有する Template では、allow_steps_override を無効にしてください。
以下のコンストラクターは、現在から 5 分後の有効期限を要求します。バックエンドでは、自身の時計を基準にこの有効期限を検証する必要があります。承認した HMAC-SHA384 署名(sha384: に続く 96 桁の16進数)のみを返し、Auth Secret は絶対に返さないでください。署名前に params を再シリアライズしたり、異なる params に署名を再利用したりしないでください。
このヘルパーを SignedClient.java として保存し、アプリケーションの SignatureProvider を渡してください。
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 の作成
Assembly を作成するには、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 の取得
getAssembly メソッドは、指定した
assembly_Id で識別される Assembly のステータスを JSON で取得します。
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);
}
}
}
getAssemblyByUrl メソッドを使用すると、URL で Assembly を取得することもできます。
AssemblyResponse response = transloadit.getAssemblyByUrl("ASSEMBLY_URL");
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
Assembly のキャンセル
実行中の Assembly をキャンセルするには、cancelAssembly メソッドに、AssemblyResponse.getSslUrl() の完全な HTTPS Assembly URL(レスポンスの 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);
}
}
}
Assembly の一覧取得
listAssemblies メソッドは、指定した options に従って
Assembly の配列を取得します。有効な options は、page、pagesize、type、fromdate、todate です。詳細は Transloadit API ドキュメントを参照してください。
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 の作成
新しい Template を作成するには、newTemplate メソッドに
Template 名をパラメーターとして渡します。Step 名は一意である必要があります。この例では、元画像のリサイズと最適化を別々の Step で行います。
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 の更新
Template を更新するには、updateTemplate メソッドに Template ID と更新するオプションを渡します。新しい name とともに渡す設定のうち、template オプションには処理設定を JSON で指定します。Template 更新 APIを参照してください。
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 の削除
Template を削除するには、deleteTemplate メソッドに
Template ID をパラメーターとして渡します。
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);
}
}
}
Template の一覧取得
アカウント内のすべての Template の一覧を取得するには、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 の取得
特定の Template を取得するには、getTemplate メソッドに
Template ID をパラメーターとして渡します。
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);
}
}
}
請求情報の取得
特定の月のアカウントの請求明細を取得するには、getBill メソッドに月と年をパラメーターとして渡します。
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);
}
}
}
使用例
実際に動作する完全な例は、/examplesを参照してください。
ドキュメント
API ドキュメントの全容は Javadoc を参照してください。