Storage
StorageTemplate (Bean 名は storageTemplate) は、Supabase Storage のオブジェクトを読み書きします。@StorageBucket のインターフェースは、一つのバケットのオブジェクトを、そのパスを一か所にまとめて宣言します。どちらも現在のユーザーとして動作するので、呼び出しに何ができるかは、storage.objects の行レベルセキュリティのポリシーが決めます。
使う理由
バケットのポリシーは、パスの形に依存します。「ユーザーは、自分の ID の名前のフォルダーの下に書く」というものです。すべての呼び出し元がパラメーターからそのパスを組み立てていると、どれかが間違った場所からユーザーの ID を取ります。宣言したバケットは各パスを一度だけ書き、呼び出し元が別のユーザーの ID を入れられるパラメーターの代わりに、セキュリティコンテキストからユーザーを取れます。
例
@StorageBucket('avatars')
abstract interface class Avatars {
@Upload('#{authentication.name}/avatar.png', upsert: true)
Future<void> put(Uint8List bytes);
@Download('{userId}/avatar.png')
Stream<List<int>> get(String userId);
@SignedUrl('{userId}/avatar.png', expiresIn: Duration(minutes: 5))
Future<Uri> link(String userId);
@PublicUrl('{userId}/avatar.png')
Uri publicLink(String userId);
@StorageObject('{userId}/settings.json')
Future<Settings?> settings(String userId);
@StorageObject('{userId}/settings.json')
Future<void> saveSettings(String userId, Settings settings);
@DeleteObject('{userId}/avatar.png')
Future<void> remove(String userId);
}
put にユーザーの ID は要りません。パスは、サインインしたユーザーのものです。テンプレートで同じことをするには:
await storage.upload('avatars', 'u1/avatar.png', bytes,
contentType: 'image/png', upsert: true);
final link = await storage.signedUrl('avatars', 'u1/avatar.png');
final settings = await storage.read<Settings>('config', 'app.json');
テンプレート
| メソッド | すること |
|---|---|
upload(bucket, path, content, contentType:, upsert:, cacheControl:) |
バイト列、String (UTF-8 として)、または Stream<List<int>> を書き込む。upsert があると、すでにあるオブジェクトを置き換える。なければ StorageObjectAlreadyExistsException。コンテンツタイプは、指定しなければ application/octet-stream (String では text/plain;charset=utf-8)。 |
download(bucket, path) |
オブジェクトのバイト列。届いた順に渡される (Stream<List<int>>)。 |
downloadBytes(bucket, path) |
オブジェクト全体をメモリに読む。 |
read<T>(bucket, path) |
オブジェクトを JSON として、ObjectMapper で T に読む。そのオブジェクトがなければ null。 |
store(bucket, path, value, upsert:) |
値を JSON として書き込む。upsert が false でない限り、あるものを置き換える。 |
publicUrl(bucket, path, download:) |
公開バケットのオブジェクトのアドレス。Storage には何も問い合わせない。アドレスは、オブジェクトがあってもなくても存在する。 |
signedUrl(bucket, path, expiresIn:) |
トークンなしでオブジェクトを読めるアドレス。expiresIn の間だけ有効 (指定しなければ spring.supabase.storage.signed-url-expiry)。 |
signedUploadUrl(bucket, path) |
SignedUpload。トークンなしで、PUT で一度だけオブジェクトをアップロードできるアドレス (サーバーがブラウザーに渡すためのもの)。 |
list(bucket, prefix:, limit:, offset:, sortBy:, descending:, search:) |
プレフィックスの直下のオブジェクトとフォルダー。StorageObjectInfo のリストで、デフォルトは 100 件、name の順。フォルダーには id がない (isFolder)。 |
delete(bucket, path)、deleteAll(bucket, paths) |
オブジェクトを削除する。何もなくてもエラーではない。deleteAll は、あった数を返す。 |
move(bucket, from, to, toBucket:)、copy(…) |
オブジェクトを移動またはコピーする。指定すれば別のバケットへ。 |
exists(bucket, path)、info(bucket, path) |
呼び出し元に見えるオブジェクトがあるかどうか。Storage がそれについて知っていること (size、contentType、etag、updatedAt など)、または null。 |
buckets()、bucket(id)、createBucket(id, isPublic:, fileSizeLimit:, allowedMimeTypes:)、updateBucket、emptyBucket、deleteBucket |
プロジェクトのバケット。 |
asServiceRole() |
すべての呼び出しをサービスロールとして行う、同じテンプレート。サービスロールはポリシーを通過し、バケットを管理できる。spring.supabase.service-role-key が必要。 |
await storage.asServiceRole().createBucket('avatars', isPublic: true);
宣言したバケット
@StorageBucket('avatars') は、メソッドが一つのバケットのオブジェクトを読み書きするインターフェースに付けます。バケットの ID は ${property} でもかまいません。各メソッドには、次のどれか一つを付けます。
| アノテーション | メソッド |
|---|---|
@Upload(path, contentType:, upsert:, cacheControl:) |
コンテンツを受け取り、Future<void> を返す。コンテンツは Uint8List、List<int>、Stream<List<int>>、String のいずれかで、パスが使っていない唯一のパラメーターか、@RequestBody() の付いたパラメーター。 |
@Download(path) |
Stream<List<int>> (届いた順のバイト列) または Future<Uint8List> を返す。null 許容の Future<Uint8List?> は、そのオブジェクトがなければ null。 |
@SignedUrl(path, expiresIn:) |
Future<Uri> または Future<String> を返す。 |
@PublicUrl(path, download:) |
Storage に問い合わせずに、Uri または String を返す。 |
@StorageObject(path, upsert:) |
値を返すときは JSON を読む (Future<Settings?> はオブジェクトがなければ null。null 非許容の型ではエラー)。値を受け取って Future<void> を返すときは書き込む。 |
@DeleteObject(path) |
Future<void> を返す。何もなくてもエラーではない。 |
- Bean はインターフェースにちなんだ名前になり、他の Bean と同じく AOP が効きます。
@PreAuthorize、@Cacheableです。 - 起動時に検査。 アノテーションのないメソッドや、戻り値の型やコンテンツが誤っているメソッドは起動を止めます。メッセージは、そのインターフェースのすべての問題を示します。
- 独自の種類のメソッドは、
StorageBucketOperationを実装する Bean です。組み込みのものより先に尋ねられます。 - アプリケーションのビルド時に分からないもの (一覧、移動、バケット) には、テンプレートを使います。
パスのルール
宣言したバケットのパスには、三種類のプレースホルダーを書けます。
| パスの中 | 何で埋められるか |
|---|---|
${app.folder} |
設定。アプリケーションの起動時に一度だけ |
{userId} |
同じ名前のメソッドのパラメーター。呼び出しのたび |
#{authentication.name} |
SpEL。呼び出しのたび。パラメーターは #name、authentication と principal は @PreAuthorize と同じ、Bean は @name |
@Download('{userId}/#{#kind.name}.png')
Stream<List<int>> get(String userId, AvatarKind kind);
値はパスの一つのセグメントで、パスではありません。 パラメーターや式が返すものは、次の場合に ArgumentError で拒否されます。
- 空、
.、または..である。 /または\を含む。- 制御文字を含む。
そのため、'{userId}/avatar.png' に userId = '../admin' を渡すと拒否され、どの呼び出しも自分のフォルダーの外に出ません。パスの固定のテキストにも、. や .. のセグメントは書けません。
テンプレートは、コードで渡されたものも含めて、すべてのパスをもう一度検査します。空、.、.. のセグメント、バックスラッシュ、制御文字を含むパスは ArgumentError で、各セグメントはパーセントエンコードされます。バケットの ID は一つのセグメントです。
エラー
| 例外 | いつ |
|---|---|
StorageObjectNotFoundException |
オブジェクトまたはバケットが存在しないか、呼び出し元に見えない。Storage はこの二つを区別しない。 |
StorageObjectAlreadyExistsException |
その場所に、すでにオブジェクト (またはバケット) がある。 |
StoragePermissionDeniedException |
storage.objects のポリシーが呼び出しを拒否した、またはトークンが受け入れられなかった。 |
StorageObjectTooLargeException |
オブジェクトが、バケットまたはプロジェクトの許す大きさを超えている。 |
StorageException |
Storage のその他の失敗。 |
SupabaseUnavailableException |
プロジェクトから応答がない。 |
どれも SupabaseException で、statusCode、code、message を持ちます。
try {
await storage.upload('avatars', 'u1.png', bytes);
} on StorageObjectAlreadyExistsException {
// upload(..., upsert: true) would have replaced it
}
download のストリームは、購読されたときに、その例外で失敗します。
制限
- アップロードは、送る前にすべて読み込まれます。 ストリームもです。トランスポートは、リクエストのボディをバイト列として受け取るためです。ダウンロードはストリームで渡されます。
- 再開可能なアップロード (TUS) はありません。
- オブジェクトの
Resourceはありません。resource(bucket, path)はありません。 - 画像の変換はありません。
プロパティ
| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
spring.supabase.storage.signed-url-expiry |
Duration |
1h |
呼び出しが指定しないときの、署名付き URL の有効期間。 |
Spring (Java) との対応
Spring 自体には対応するものがありません。Spring Cloud AWS には、StorageTemplate と同じ形の S3Template があります。宣言したバケットに対応するものはありません。