put(file, options)
put() はファイルを 1 つアップロードし、新しいオブジェクトを返します。
入力
オブジェクトの拡張子は
filename、次にパスのベース名または File の名前から取得されます。バイト列やプレーンな Blob には名前がないため、アップロードする際は filename を渡してください (例: "data.json")。
Node.js では、開けないパスはプレーンな
Error (Cannot open file: <path>、元のエラーは cause) をスローします。ブラウザでは、パスを渡すとそれより前の段階で node:fs のインポートエラーにより失敗します。代わりに <input type="file"> から取得した File を使ってください。オプション
サーバー側の完全なルールについては、Blob オブジェクトのアップロードを参照してください。
結果
シンプルアップロードとマルチパートアップロード
put() はファイルサイズに応じてアップロード方式を選びます:
すべてのファイルは最低 512 バイト必要で、それより小さいファイルは
FILE_TOO_SMALL で失敗します。ルールやアップロードトークンの max_size、またはストレージの割り当てによって、10 GiB の上限が下がることがあります。
マルチパートアップロードの流れ
- SDK がアップロードを開始し、サーバーがパートの制限 (
max_size、max_parts) を返します。 - ファイルは
min(max_size, max(16 MiB, ceil(size / max_parts)))バイトのパートに分割されます。パートは通常 16 MiB 以上ですが、サーバーのmax_sizeがそれより小さい場合は小さくなります。 - パートは、サーバーが処理中のパートに設けている上限である 6 個ずつ送信されます。失敗したパートは
maxRetriesの範囲内でリトライされます。 - すべてのパートが届くと、SDK がアップロードを完了します。
put() を呼び出してください。
1 つのアカウントで同時に開いておけるマルチパートアップロードは最大 32 個です (S3 ゲートウェイと共有)。それを超えると
TOO_MANY_OPEN_UPLOADS で失敗します。パートはアカウントごとに 6 個ずつ送信されるため、大きなアップロードは 1 つずつ実行してください。ブラウザからのアップロード
API キーを決してブラウザに送らないでください。代わりに、サーバーが短期間有効なアップロードトークンを発行し、ブラウザはそれを使ってアップロードします。- サーバー
- ブラウザ
put() しか呼び出せません。その他のメソッドは 403 UPLOAD_TOKEN_NOT_ALLOWED で失敗します。
uploadTokens.create(options)
トークンは、発行時に指定されたすべてのオプションを固定します。
{ token, expires_at, max_uses } を返します。サーバー側のルールについては Blob アップロードトークンを参照してください。
uploadTokens.create() は書き込みなので、1 回のみ試行され、リトライされることはありません。
