Skip to main content

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 の上限が下がることがあります。

マルチパートアップロードの流れ

  1. SDK がアップロードを開始し、サーバーがパートの制限 (max_size、max_parts) を返します。
  2. ファイルは min(max_size, max(16 MiB, ceil(size / max_parts))) バイトのパートに分割されます。パートは通常 16 MiB 以上ですが、サーバーの max_size がそれより小さい場合は小さくなります。
  3. パートは、サーバーが処理中のパートに設けている上限である 6 個ずつ送信されます。失敗したパートは maxRetries の範囲内でリトライされます。
  4. すべてのパートが届くと、SDK がアップロードを完了します。
パートが最終的に失敗した場合や完了処理が失敗した場合、SDK は処理中のパートを待ってからアップロードを中止するため、中止後にパートが届くことはありません。元のエラーがスローされます。再開機能はありません: もう一度 put() を呼び出してください。
マルチパートアップロードは overwrite: false や checksum_sha256 をチェックしません。同じ名前の既存オブジェクトを常に置き換えます。
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 回のみ試行され、リトライされることはありません。