バケット

バケットは画像、動画、PDFなどのファイルを保存・配信するためのファイルストレージです。

例えば、Webサイトで使用する画像をバケットに保存し、配信することができます。バケットにアップロードすると、アクセスするためのURLが発行されます。WebサイトではこのURLを <img> タグの src 属性に指定することで画像を表示できます。

このドキュメントでは、バケット機能の概要とスキーマを通してバケットを定義する方法を説明します。

バケットの定義

バケットを定義するには buckets プロパティを使用します。

以下の例では、誰でもアクセスできる files バケットと、アクセスに認証が必要な systemFiles バケットを定義しています。

orizm.config.ts

import type { Orizm } from "@orizm/cms-sdk";
 
// 注意: tables, tableModules, authorities, は省略しています
export default {
  buckets: [
    {
      name: "files",
    },
    {
      name: "systemFiles",
      accessControl: "private",
    },
  ],
} satisfies Orizm.ProjectDefine;

accessControl

accessControl プロパティでバケットのアクセス制御を設定できます。指定しない場合は public になります。

public: 誰でもアクセスできる（公開バケット）
private: 署名付きURL を知っているユーザーのみアクセスできる（非公開バケット）

公開バケットへのアクセス

アップロードされたファイルごとに、アクセスするためのURLが生成されます。

https://app.orizm.com/buckets/{プロジェクト名}/{バケット名}/{オブジェクトキー}

このURLを取得するには、CMS SDKでバケットに対して list() または get() を使用してファイルのメタデータを取得します。

// filesバケットのファイル一覧を取得
const { contents } = await cmsClient.buckets.files.list();
 
console.log(contents);
// [
//   {
//     id: 1,
//     key: 'zl9XQ3KeKX89Ttf3.png',
//     size: 25667,
//     type: 'image/png',
//     width: 1024,
//     height: 672,
//     group: null,
//     originalFilename: 'image.png',
//     bucketName: 'files',
//     projectName: 'demo-project',
//     publicUrl: 'https://app.orizm.com/buckets/demo-project/files/zl9XQ3KeKX89Ttf3.png',
//     protectedUrl: 'https://app.orizm.com/buckets-protected/demo-project/files/zl9XQ3KeKX89Ttf3.png?token={トークン}',
//     createdAt: '2025-01-01T00:00:00.000Z',
//     updatedAt: '2025-01-01T00:00:00.000Z'
//   }
// ]

レスポンスされた publicUrl プロパティにアクセス用のURLが含まれています。

https://app.orizm.com/buckets/demo-project/files/zl9XQ3KeKX89Ttf3.png

非公開バケットへのアクセス

非公開バケットへアクセスするためのURLを取得するには、CMS SDKでバケットに対して list() または get() を使用してファイルのメタデータを取得します。

// systemFilesバケットのファイル一覧を取得
const { contents } = await cmsClient.buckets.systemFiles.list();
 
console.log(contents);
// [
//   {
//     id: 1,
//     key: 'zl9XQ3KeKX89Ttf3.png',
//     size: 25667,
//     type: 'image/png',
//     width: 1024,
//     height: 672,
//     group: null,
//     originalFilename: 'image.png',
//     bucketName: 'systemFiles',
//     projectName: 'demo-project',
//     publicUrl: 'https://app.orizm.com/buckets/demo-project/systemFiles/zl9XQ3KeKX89Ttf3.png',
//     protectedUrl: 'https://app.orizm.com/buckets-protected/demo-project/systemFiles/zl9XQ3KeKX89Ttf3.png?token={トークン}',
//     createdAt: '2025-01-01T00:00:00.000Z',
//     updatedAt: '2025-01-01T00:00:00.000Z'
//   }
// ]

レスポンスされた protectedUrl プロパティにアクセス用のURLが含まれています。

このURLは署名付きURLと呼ばれ、アクセスするためのJWTトークンが含まれています。このトークンは 最大15分間有効 です。トークンの期限が切れた場合は、再度 list() または get() でデータを取得することで新しいURLを取得できます。

https://app.orizm.com/buckets-protected/demo-project/systemFiles/zl9XQ3KeKX89Ttf3.png?token={トークン}

⚠️

publicUrl プロパティのURLでアクセスした場合は、認証エラーとしてステータスコード 401 が返されます。

ファイルのアップロード

ファイルをアップロードするにはCMS SDKの upload() メソッドを使用します。

// 引数 file はFile型オブジェクト
await cmsClient.buckets.files.upload(file);

ファイルの削除

ファイルを削除するにはCMS SDKの delete() メソッドを使用します。

const fileKey = "zl9XQ3KeKX89Ttf3.png";
await cmsClient.buckets.files.delete(fileKey);

storage型カラム

データベースで使用できる storage型カラムもファイルストレージとして類似した機能を持っています。

storage型カラムとバケットはファイルを扱う点で似ていますが異なる点があります。バケットはシンプルなファイル置き場であるのに対し、storage型カラムはファイルをレコードに紐づけて扱えます。例えば、ブログ記事にサムネイル画像を設定する場合、storage型カラムを使用して画像ファイルをレコードに紐づけることができます。

レコードが削除された場合、ファイルは30日後に自動で削除されます。削除前であれば、編集履歴の管理機能を利用して復元することも可能です。

テーブルモジュール権限