高速かつ効率的:Java でファイルを Vimeo にエクスポート
Vimeo に非公開動画を一つ作成し、アップロードセッションを保存して、中断した転送を Vimeo で確認済みのバイトオフセットから再開します。以下の Java プログラムでは、HTTP クライアントと Gson を使って Vimeo の再開可能なアップロードフローを実装します。作成、転送、処理状況の確認には、それぞれ別のコマンドを用意しています。
前提条件
この手順は、Bash、cURL、保守中の JDK 21 ディストリビューションを備えた Linux を対象としています。OpenJDK 21.0.12.1 でテスト済みです。保守中の Java 21 系列について、ディストリビューターが提供する最新のセキュリティ更新を適用してください。JAVA_HOME を、その JDK のインストールディレクトリに設定します。各コマンドでは、そのコンパイラーとランタイムを明示的に選択します。
アップロード権限のある Vimeo アプリケーションと、public、private、upload のスコープを持つユーザーアクセストークンも必要です。また、受信先アカウントのクォータに空きが必要です。テスト動画を作成する前に、これらの前提条件を確認してください。アップロードする権利のある、空ではない有効な動画を使用し、同じセッションファイルに対して実行するアップローダーは、一度に一つだけにしてください。
アクセストークンはサーバー上で管理してください。返されたアップロード URL も機密情報です。非公開で保存し、ログには記録しないでください。バイト転送が完了しても、Vimeo で動画のトランスコードが完了したことや、公開再生できることを意味しません。
開発環境のセットアップ
非公開の作業ディレクトリに、以下のクラス全体を VimeoUploader.java として保存します。この単独で実行できるセットアップでは、Gson 2.14.0をダウンロードし、クラスをコンパイルします。各コマンドが成功してから、次のコマンドを実行してください。
test -x "$JAVA_HOME/bin/java" &&
test -x "$JAVA_HOME/bin/javac" &&
command -v curl >/dev/null &&
curl --fail --location --output gson-2.14.0.jar \
https://repo.maven.apache.org/maven2/com/google/code/gson/gson/2.14.0/gson-2.14.0.jar &&
"$JAVA_HOME/bin/javac" -cp gson-2.14.0.jar VimeoUploader.java
ダウンロードまたはコンパイルに失敗した場合は、報告された問題を修正し、このセットアップブロックを再実行してください。ダウンロードした JAR を置き換え、クラスを再ビルドします。ビルドに失敗した後で古いクラスを実行しないでください。
アプリケーションの設定と認証
サーバーのシークレット管理機能を通じて VIMEO_ACCESS_TOKEN を渡します。create コマンドは API リクエストを一回行い、非公開のセッションファイルを保存します。resume は別の動画を作成せずに、そのセッションを再利用します。ファイルハッシュにより、サイズが同じでも内容が異なるファイルでの再開を防ぎます。転送中は入力ファイルを変更しないでください。
import com.google.gson.Gson;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import java.io.IOException;
import java.io.RandomAccessFile;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.attribute.PosixFilePermissions;
import java.security.MessageDigest;
import java.time.Duration;
import java.util.HexFormat;
public final class VimeoUploader {
public record Session(String uri, String uploadLink, long size, String sha256) {}
private static final Gson JSON = new Gson();
private final HttpClient http;
private final URI api;
public VimeoUploader() {
this(HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(15))
.followRedirects(HttpClient.Redirect.NEVER).build(), URI.create("https://api.vimeo.com"));
}
// Tests supply a trusted HTTPS receiver instead of the Vimeo API.
VimeoUploader(HttpClient http, URI api) {
this.http = http;
this.api = https(api);
}
private static URI https(URI uri) {
if (!"https".equals(uri.getScheme()) || uri.getHost() == null
|| uri.getRawUserInfo() != null || uri.getFragment() != null) {
throw new IllegalArgumentException("An HTTPS URL without embedded credentials is required");
}
return uri;
}
private static String hash(Path file) throws Exception {
MessageDigest digest = MessageDigest.getInstance("SHA-256");
try (var input = Files.newInputStream(file)) {
byte[] buffer = new byte[65536];
int count;
while ((count = input.read(buffer)) != -1) digest.update(buffer, 0, count);
}
return HexFormat.of().formatHex(digest.digest());
}
public Session create(Path file, String token, String name) throws Exception {
long size = Files.size(file);
if (!Files.isRegularFile(file) || size == 0) throw new IOException("A nonempty file is required");
if (token == null || token.isBlank()) throw new IllegalArgumentException("Missing Vimeo token");
String checksum = hash(file);
JsonObject upload = new JsonObject();
upload.addProperty("approach", "tus");
upload.addProperty("size", size);
JsonObject body = new JsonObject();
body.add("upload", upload);
body.addProperty("name", name);
JsonObject privacy = new JsonObject();
privacy.addProperty("view", "nobody");
body.add("privacy", privacy);
HttpResponse<String> response = http.send(HttpRequest.newBuilder(api.resolve("/me/videos"))
.timeout(Duration.ofSeconds(60)).header("Authorization", "Bearer " + token)
.header("Accept", "application/vnd.vimeo.*+json;version=3.4")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(JSON.toJson(body))).build(),
HttpResponse.BodyHandlers.ofString());
if (response.statusCode() != 200) throw new IOException("Vimeo create HTTP " + response.statusCode());
JsonObject result = JsonParser.parseString(response.body()).getAsJsonObject();
String uri = result.get("uri").getAsString();
if (!uri.matches("/videos/[0-9]+")) throw new IOException("Invalid video URI");
URI link = https(URI.create(result.getAsJsonObject("upload").get("upload_link").getAsString()));
return new Session(uri, link.toString(), size, checksum);
}
private static long offset(HttpResponse<?> response, long size) throws IOException {
if (!response.headers().firstValue("Tus-Resumable").orElse("").equals("1.0.0")) {
throw new IOException("Unexpected tus protocol version");
}
String value = response.headers().firstValue("Upload-Offset")
.orElseThrow(() -> new IOException("Missing upload offset"));
long offset;
try { offset = Long.parseLong(value); }
catch (NumberFormatException error) { throw new IOException("Invalid upload offset", error); }
if (offset < 0 || offset > size) throw new IOException("Upload offset out of range");
return offset;
}
public void resume(Path file, Session session) throws Exception {
if (session == null) {
throw new IOException("Missing upload session; reconcile your Vimeo account before creating another video");
}
if (Files.size(file) != session.size() || !hash(file).equals(session.sha256())) {
throw new IOException("The upload file changed");
}
URI link = https(URI.create(session.uploadLink()));
HttpResponse<Void> head = http.send(HttpRequest.newBuilder(link)
.timeout(Duration.ofSeconds(30)).header("Tus-Resumable", "1.0.0")
.header("Accept", "application/vnd.vimeo.*+json;version=3.4")
.method("HEAD", HttpRequest.BodyPublishers.noBody()).build(),
HttpResponse.BodyHandlers.discarding());
if (head.statusCode() != 200 && head.statusCode() != 204) {
throw new IOException("Upload HEAD HTTP " + head.statusCode());
}
long position = offset(head, session.size());
try (RandomAccessFile input = new RandomAccessFile(file.toFile(), "r")) {
input.seek(position);
byte[] buffer = new byte[1024 * 1024];
while (position < session.size()) {
int length = (int) Math.min(buffer.length, session.size() - position);
input.readFully(buffer, 0, length);
HttpResponse<Void> patch = http.send(HttpRequest.newBuilder(link)
.timeout(Duration.ofMinutes(2)).header("Tus-Resumable", "1.0.0")
.header("Accept", "application/vnd.vimeo.*+json;version=3.4")
.header("Upload-Offset", Long.toString(position))
.header("Content-Type", "application/offset+octet-stream")
.method("PATCH", HttpRequest.BodyPublishers.ofByteArray(buffer, 0, length)).build(),
HttpResponse.BodyHandlers.discarding());
if (patch.statusCode() != 204) throw new IOException("Upload PATCH HTTP " + patch.statusCode());
long confirmed = offset(patch, session.size());
if (confirmed != position + length) throw new IOException("Unexpected confirmed offset");
position = confirmed;
}
}
}
public JsonObject status(Session session, String token) throws Exception {
if (session == null || session.uri() == null || !session.uri().matches("/videos/[0-9]+")) {
throw new IOException("Missing or invalid video URI");
}
if (token == null || token.isBlank()) throw new IllegalArgumentException("Missing Vimeo token");
HttpResponse<String> response = http.send(HttpRequest.newBuilder(api.resolve(session.uri()
+ "?fields=uri,upload.status,transcode.status,privacy.view"))
.timeout(Duration.ofSeconds(30)).header("Authorization", "Bearer " + token)
.header("Accept", "application/vnd.vimeo.*+json;version=3.4")
.GET().build(), HttpResponse.BodyHandlers.ofString());
if (response.statusCode() != 200) throw new IOException("Vimeo status HTTP " + response.statusCode());
JsonObject video = JsonParser.parseString(response.body()).getAsJsonObject();
if (!session.uri().equals(video.get("uri").getAsString())) {
throw new IOException("Unexpected status video URI");
}
JsonObject result = new JsonObject();
result.add("uri", video.get("uri"));
result.addProperty("upload", statusValue(video, "upload"));
result.addProperty("transcode", statusValue(video, "transcode"));
result.add("privacy", video.getAsJsonObject("privacy").get("view"));
return result;
}
private static String statusValue(JsonObject video, String field) {
if (!video.has(field) || !video.get(field).isJsonObject()) return "unavailable";
var value = video.getAsJsonObject(field).get("status");
return value == null || value.isJsonNull() ? "unavailable" : value.getAsString();
}
public static void main(String[] args) throws Exception {
if (args.length != 3) throw new IllegalArgumentException("create|resume|status video-file session-file");
for (int i = 1; i < args.length; i++) {
if (!args[i].chars().allMatch(c -> c >= 32 && c <= 126)) {
throw new IllegalArgumentException("Use printable ASCII paths for this command-line example");
}
}
Path file = Path.of(args[1]);
Path state = Path.of(args[2]);
VimeoUploader uploader = new VimeoUploader();
if (args[0].equals("create")) {
Files.createFile(state, PosixFilePermissions.asFileAttribute(PosixFilePermissions.fromString("rw-------")));
Session session = uploader.create(file, System.getenv("VIMEO_ACCESS_TOKEN"), file.getFileName().toString());
Files.writeString(state, JSON.toJson(session));
System.out.println("Created " + session.uri());
} else if (args[0].equals("resume")) {
Session session = JSON.fromJson(Files.readString(state), Session.class);
uploader.resume(file, session);
System.out.println("Bytes transferred for " + session.uri());
} else if (args[0].equals("status")) {
Session session = JSON.fromJson(Files.readString(state), Session.class);
System.out.println(JSON.toJson(uploader.status(session, System.getenv("VIMEO_ACCESS_TOKEN"))));
} else {
throw new IllegalArgumentException("Choose create, resume, or status");
}
}
}
セッションファイルは、所有者だけがアクセスできる権限で排他的に新規作成されます。create が既存ファイルを上書きすることはありません。ディレクトリも保護し、自分のアプリケーションで作成したセッションだけを再開してください。セッション内のアップロード URL は動画の送信先になり得るためです。このコマンドラインの例では、ネイティブファイル名のデコードが曖昧にならないよう、表示可能な ASCII 文字のパスのみを受け付けます。それ以外のパスは使用前に名前を変更し、空白やシェル文字を含むパスは引用符で囲んでください。
エラー処理と再試行
create を無条件に再試行しないでください。レスポンスが失われると、呼び出し側ではタイムアウトになっていても、Vimeo に動画が残る場合があります。失敗後にセッションファイルが空の場合は、代わりの動画を作成する前にアカウントの状態を照合してください。転送に失敗した場合は、同じセッションと変更していない入力を使って
resume を再実行します。その HEAD リクエストで、レスポンスが失われる前に受信されたバイトも含め、サーバーで確認済みのオフセットを読み取ります。
認証エラーや無効なリクエストは修正が必要です。API のレート制限については、Vimeo のレート制限のガイドと
X-RateLimit-Reset レスポンスヘッダーに従ってください。一時的なサービス障害やネットワーク障害では、バックオフしてから再開します。期限切れのアップロード URL には明示的な復旧操作が必要です。自動的に新規動画の作成リクエストに切り替えないでください。この例では、Bearer トークンを API リクエストにのみ付与し、動画作成時に
privacy.view: nobody をリクエストします。動画は公開しません。中断を試しやすいようにチャンクサイズを 1 MiB にしています。大きなファイルのアップロードでは、スループットを調整する前に Vimeo の推奨チャンクサイズを確認してください。
実装のテスト
動画を video.mp4 に配置するか、各コマンドのパスを実際のパスに置き換えます。環境から VIMEO_ACCESS_TOKEN を利用できる状態で、非公開動画を一度だけ作成します。
"$JAVA_HOME/bin/java" -cp '.:gson-2.14.0.jar' VimeoUploader create "video.mp4" "session.json"
続いて、動画のバイト列を転送します。プロセスが停止した場合やリクエストに失敗した場合は、同じファイルとセッションを使って、このコマンドを再実行してください。
"$JAVA_HOME/bin/java" -cp '.:gson-2.14.0.jar' VimeoUploader resume "video.mp4" "session.json"
成功メッセージには、バイト列を転送した動画が示されます。再開時は毎回、Vimeo の HEAD の表にある両方のヘッダー、Tus-Resumable: 1.0.0 と
Accept: application/vnd.vimeo.*+json;version=3.4 を含む tus HEAD リクエストから始まります。PATCH は確認済みオフセットより後のバイト列だけを送信します。また、この例では Vimeo の再開手順に従い、PATCH でも Accept を送信します。
受信先の動画は別途確認してください。
"$JAVA_HOME/bin/java" -cp '.:gson-2.14.0.jar' VimeoUploader status "video.mp4" "session.json"
このコマンドは、Vimeo から取得した動画 URI、upload、transcode、privacy の値を含む JSON スナップショットを出力します。アップロードステータスの complete はプロバイダーによる受け入れを示し、トランスコードステータスの complete は処理の完了を示します。どちらも、この非公開動画が公開再生できるようになったことを意味しません。処理が続いている場合は、後で status を再実行してください。レスポンスヘッダーの待機中は、作成リクエストが 60 秒、HEAD またはステータスのリクエストが 30 秒、PATCH が一回につき二分でタイムアウトします。レスポンス本文の読み取りには、このタイムアウトより長くかかる場合があります。プログラムにはアップロード全体の期限や自動再試行ループはありません。サービスで必要な場合は、別途タスクの期限を設けてください。
動画アップロードのベストプラクティス
保存された内容を確認するには、元のソースファイルをダウンロードし、入力と全バイトを比較します。Vimeo の API ファイルリンクには、public、private、video_files のトークンスコープと、対象となるアカウントプランが必要です。元ファイルを利用できるかどうかは、ソースファイルの保存にも依存します。この機能には有料プランが必要で、アップロード前に有効にしておく必要があります。トランスコードされた動画は別のファイルなので、元ファイルとのバイト単位の一致は確認できません。元ファイルは手元でも保管し、テストが終わったら Vimeo アカウントから非公開のテスト動画を削除してください。
Transloadit の Vimeo エクスポート Robot によるワークフローの強化
🤖 /video/encodeでエンコーディングと透かしの追加を行い、その出力を 🤖 /vimeo/store に渡してエクスポートします。エクスポート用 Robot 自体が、それ以前の動画変換をすべて行うわけではありません。
まとめ
受信先の動画を確認し、必要な復旧作業が完了するまで、保存したセッションを保持してください。エクスポート前の処理をマネージドサービスで行うには、Transloadit の動画エンコーディングサービスをご覧ください。
ご自身での運用は避けたいですか?
Transloadit は、単一の API 呼び出し内の処理の一環として、S3、Azure、Google Cloud などにファイルをエクスポートします。
