Skip to main content
このページは @squarecloud/blob v4 を解説しています。v3 からアップグレードする場合は、v3 → v4 移行ガイドをお読みください。
@squarecloud/blob は、Square Cloud Blob Storage の公式 JavaScript SDK です。すべての Blob API endpoint と S3 ゲートウェイをカバーします。

​
要件

  • Node.js 20 以降、または任意のモダンブラウザ。SDK が使用するのは fetch、FormData、Blob だけです。
  • ESM と CommonJS の両方で提供され、ランタイム依存関係はゼロです。
  • @aws-sdk/client-s3 はオプションの peer dependency で、s3() を呼び出す場合にのみ必要です。

​
インストール

​
クライアントの作成

​
コンストラクタ

​
認証情報

認証情報は Bearer プレフィックスなしで、Authorization ヘッダーにそのまま送信されます。
API キーを決してブラウザに渡さないでください。サーバーでアップロードトークンを発行し、クライアントにはトークンだけを渡します。

​
設定できないもの

maxRetries が唯一のオプションです。クライアントは次のものを受け付けません:
  • ベース URL。 https://blob.squarecloud.app/v1/ に固定されています。
  • カスタム fetch。 リクエストにはグローバルの fetch が使われます。
  • タイムアウトや AbortSignal。 呼び出しは fetch が待機する限り続き、キャンセルする方法はありません。
  • カスタムヘッダー。

​
メソッド

すべてのメソッドはプレーンなデータを返します (クラスはありません)。ただし s3() は S3Client を返します。オプションと結果には API のフィールド名 (主に snake_case: security_hash、expires_at) がそのまま使われるため、Blob API リファレンスをそのまま適用できます。 パッケージは SquareCloudBlobError、BlobErrorCode 型、すべてのオプション型と結果型 (PutOptions、PutResult、ListedObject、ObjectInfo、Share、Rule など) もエクスポートしています。エラーを参照してください。

​
オブジェクト ID

すべてのオブジェクトは不透明な ID で識別されます。たとえば公開オブジェクトなら pub/...、プライベートオブジェクトなら prv/... です。
  • ID は返されたとおりに保存してください。 手作業で組み立てたり、パースしたりしないでください。
  • private や expire を変更すると ID が変わります。 保存している ID は、必ず update() が返す ID で置き換えてください。
  • URL を組み立てる代わりに、レスポンスの url を使ってください。プライベートオブジェクトは url: null です。リンクは downloadUrl() または共有で取得します。