再開可能なアップロード
ユーザーがデバイスからファイルをアップロードしているときに、ネットワークの中断やサーバーの問題が発生すると、アップロードが失敗し、通常はファイル全体の再送信が必要になることがあります。再開可能なアップロードは、こうした中断からシームレスに復旧でき、より堅牢で効率的かつ快適なユーザー体験を提供します。
Transloadit には、サーバーにファイルをアップロードする方法が 2 つあります。
- Assembly の作成時に、
multipart/form-dataの POST リクエストにファイルを含めることができます。このリクエストが中断されると、アップロードと Assembly が失敗します。 - tus の再開可能なアップロードプロトコルを使ってファイルをアップロードできます。ネットワークやサーバーの問題からアップロードを復旧でき、ユーザーは必要に応じてアップロードを一時停止したり再開したりすることもできます。tus は、HTTP 経由でファイルを再開可能な形でアップロードするための、オープンで無料のプロトコルです。利用できるオープンソースのクライアント実装が多数あります。
このドキュメントでは、2 つ目の再開可能な方式で使用する API について説明します。この方式は 2 つのステージで構成されており、それぞれをこのドキュメントで説明します。
アップロード → 処理 → 非公開ストレージという流れの例と、制御された中断テストの手順については、ファイルアップロードガイドの大容量動画ワークフロー (English)を参照してください。転送を再開しても、処理やエクスポートの成功が保証されるわけではありません。Assembly ID を保持し、終了時の Assembly Status を確認して、保存された出力を検証してからアセットを公開してください。クライアントのリトライ設定とリロード後の復旧は、tus プロトコル自体とは別のものです。
Java クライアントの例については、DevTip の tus-java-client を使った再開可能なファイル転送を参照してください。ファイルアップロードのチュートリアル (English)では、HTML フォームやカスタムのブラウザーインターフェースも取り上げています。
Node SDK や Uppy など、既製の連携機能の多くは、ファイルのアップロードに内部でデフォルトで tus を使用しています。これらを使用している場合は、再開可能なアップロードを自分で実装する必要はありません。このドキュメントは、SDK を開発したい方、tus 連携のない SDK を使用したい方、または Transloadit が提供する SDK をまったく使用しない方を対象としています。
ステージ 1: 新しい Assembly を作成する
新しい Assembly は、Assemblies を作成するためのエンドポイントに
multipart/form-data の POST リクエストを送信することで作成されます。従来のアップロードでは、すべてのファイルをこのリクエストの追加パートとして含めます。再開可能なアップロードでは、クライアントはこのリクエストにファイルを含めず、アップロードするファイルの数だけを
Transloadit API に伝えます。
これを行うには、マルチパート POST リクエストに num_expected_upload_files フィールドを追加します。この値は、クライアントがこの Assembly にアップロードしたいファイルの数です。params など、Assembly Instructions を制御するための追加フィールドも含める必要があります。
次のスニペットは HTTP リクエストの例です。クライアントは、認証の詳細と
Assembly Instructions を params フィールドに指定します。num_expected_upload_files
フィールドは、クライアントが 2 つのファイルをアップロードしたいことを示しています。ただし、これらのファイルの実際の内容は、このリクエストには含まれていません。
POST /assemblies HTTP/1.1
Host: api2.transloadit.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryIAWBI8vxocZzsG03
------WebKitFormBoundaryIAWBI8vxocZzsG03
Content-Disposition: form-data; name="params"
{"auth":{"key":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"},"steps":{"encode":{"robot":"/image/resize"}}}
------WebKitFormBoundaryIAWBI8vxocZzsG03
Content-Disposition: form-data; name="num_expected_upload_files"
2
------WebKitFormBoundaryIAWBI8vxocZzsG03--
Assembly の作成に成功すると、API は対応する Assembly Status レスポンスを返します。次のスニペットはその例です。
{
"ok": "ASSEMBLY_UPLOADING",
"assembly_id": "b841ea401e1a11e7b37d7bda1b503cdd",
"assembly_ssl_url": "https://api2-freja.transloadit.com/assemblies/b841ea401e1a11e7b37d7bda1b503cdd",
"websocket_url": "https://api2-freja.transloadit.com/ws20277",
"tus_url": "https://api2-freja.transloadit.com/resumable/files/",
"expected_tus_uploads": 2,
"started_tus_uploads": 0,
"finished_tus_uploads": 0,
// …
}
Assembly がアップロード中の状態にあり、アップロードを受け入れる準備ができていることがわかります。レスポンスには、この Assembly を一意に識別する
assembly_ssl_url プロパティが含まれています。また、ファイルのアップロード先エンドポイントを定義する
tus_url プロパティも含まれています。expected_tus_uploads、started_tus_uploads、finished_tus_uploads の各プロパティは、Transloadit がこの Assembly で受け入れる予定のファイル数と、開始済みおよび完了済みのアップロード数を示します。
ステージ 2: 各ファイルをアップロードする
最初のステージで Assembly を作成すると、クライアントは Transloadit の再開可能なアップロードサーバーへのファイルのアップロードを開始できます。
Transloadit は最大 200 GB のファイルサイズをサポートしています。アプリケーションでより高い上限が必要な場合は、お問い合わせください。
Transloadit は、tusd ソフトウェアを使用して tus サーバーを稼働させています。その URL は、最初のステージで説明したように、Assembly Status の tus_url プロパティで提供されます。この
tus アップロードサーバーはプロトコル仕様に準拠しており、tus クライアントからファイルをアップロードできます。仕様に従って独自の tus クライアントを実装することも、使用するプログラミング言語に対応したオープンソースのクライアント実装を選ぶこともできます。
tus を使ったアップロードは、次の 2 つの手順で進みます。
- まず、tus サーバー上にアップロードリソースを作成します。クライアントは
POST リクエストを送信し、Assembly URL、ファイル名、
fieldnameメタデータを含めます。サーバーは、クライアントが実際のファイル内容をアップロードできるアップロード URL を返します。 - アップロード URL を受信すると、クライアントはこのエンドポイントにファイル内容を含む PATCH リクエストを送信し、実際のアップロードを行います。ファイル全体の転送が完了すると、tus サーバーは、追加のやり取りを必要とせずに、そのファイルを処理のために Assembly にシームレスに渡します。
このやり取りの厳密なセマンティクスについて詳しくは、プロトコル仕様を参照してください。次のセクションでは、Transloadit との連携に関係する部分に焦点を当てます。
アップロードの作成
最初の手順では、tus_url で指定されたエンドポイントに POST リクエストを送信して、tus サーバー上にアップロードリソースを作成します。アップロードを先ほど作成した
Assembly に関連付けるには、特別なメタデータを含める必要があります。メタデータには、次の 3 つの値がすべて必要です。
assembly_url: 最初のステージで、Assembly Status のassembly_ssl_urlプロパティから取得した Assembly URLfilename: ファイルの名前fieldname: HTML フォームの入力フィールド名に相当するもの
追加のメタデータはすべて、file.user_meta 内の
Assembly Variable になります。これを使うと、Assembly 内のすべてのファイルで共有される fields の代わりに、Template 内で ファイルごと に動的な処理を行えます。検出された内容に応じて分岐する必要がある場合は、${file.mime} を優先して使い、image/*、video/*、audio/* などの MIME ファミリーと照合してください。${file.type} も、Assembly Status レスポンス内でファイルの大まかなカテゴリとして利用できます。その値は、"audio"、"document"、"image"、"office"、"pdf"、"swf"、"video"、"xls" のいずれかで、カテゴリが検出されなかった場合は null です。利用側では、将来のカテゴリとの互換性を保つために、ほかの文字列値も受け入れるようにしてください。通常は、MIME による照合のほうがより厳密な確認方法です。
次のリクエスト例では、サイズが 10,000 バイトの isaac.png という名前のファイルを、ID が b841ea401e1a11e7b37d7bda1b503cdd の Assembly に、フィールド名
file-input でアップロードしています。Base64 を使ったメタデータのエンコードの詳細は、プロトコル仕様に記載されています。
POST /resumable/files/ HTTP/1.1
Content-Length: 0
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Length: 10000
Upload-Metadata: assembly_url aHR0cHM6Ly9hcGkyLWZyZWphLnRyYW5zbG9hZGl0LmNvbS9hc3NlbWJsaWVzL2I4NDFlYTQwMWUxYTExZTdiMzdkN2JkYTFiNTAzY2Rk,filename aXNhYWMucG5n,fieldname ZmlsZS1pbnB1dA==
正しいリクエストに対して、サーバーはアップロードリソースを作成し、そのアップロード URL を
Location ヘッダーで返します。次に例を示します。
HTTP/1.1 201 Created
Tus-Resumable: 1.0.0
Location: https://api2-freja.transloadit.com/resumable/files/136058f2ef4dc9de3f5c23ceed591545
データ転送
アップロードの作成後、クライアントは PATCH リクエストを使って、実際のファイル内容を tus アップロード URL にアップロードする必要があります。
PATCH /resumable/files/136058f2ef4dc9de3f5c23ceed591545 HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Offset: 0
Content-Length: 10000
Content-Type: application/offset+octet-stream
[content of file]
1 つの tus アップロードが完了すると、Transloadit は、Assembly の作成時に使用したパラメーターを使って、そのファイルを自動的に処理します。特別な操作は必要ありません。すべての
tus アップロードが完了するまで、すでに一部のファイルの処理が完了していても、Assembly は
ASSEMBLY_UPLOADING 状態のままになります。
これらの手順を、クライアントがアップロードしたい各ファイルについて繰り返します。クライアントは、アプリケーションのニーズに応じて、これらのファイルを並列にアップロードするか、順番にアップロードするかを自由に選択できます。
予定アップロード数は、アップロードを完了する必要があるファイル数を Assembly に伝えるものであり、作成できる tus アップロードリソース数の厳密な上限ではありません。アップロード作成のレスポンスが失われた場合にクライアントが復旧できるように、Assembly のアップロード中は追加のリソースが許容されます。進捗カウンターでは、放棄されたリソースを除き、進捗が最も進んでいるアップロードを予定数分使用します。意図したファイルのみをアップロードし、再開時には既知の各アップロード URL を再利用してください。Assembly が
ASSEMBLY_UPLOADING 状態でなくなると、新しいアップロードの作成は拒否されます。
再開
ネットワークの中断やユーザーによるアップロードの一時停止によってデータ転送が失敗した場合、クライアントは停止した位置からアップロードを再開できます。
まず、クライアントはアップロード URL に HEAD リクエストを送信して、中断前にサーバーがどれだけのデータを受信できたかを確認します。
HEAD /resumable/files/136058f2ef4dc9de3f5c23ceed591545 HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
レスポンスの Upload-Offset ヘッダーには、受信済みのバイト数が含まれます。たとえば、次のレスポンスは、10,000 バイトのうち 3,000 バイトを受信済みのアップロードを示しています。
HTTP/1.1 200 OK
Tus-Resumable: 1.0.0
Upload-Offset: 3000
Upload-Length: 10000
続いて、別の PATCH リクエストを使って、残りの 7,000 バイトをアップロードできます。
PATCH /resumable/files/136058f2ef4dc9de3f5c23ceed591545 HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Offset: 3000
Content-Length: 7000
Content-Type: application/offset+octet-stream
[remaining content of file]
tus を使った再開可能なアップロードの詳細については、tus FAQを参照してください。