フォルダ内のファイルで資料掲示板を作成する

books/guideフォルダにMarkdown文書と画像を保存し、Webspaceでファイルの一覧と選択したファイルの内容を提供する掲示板を構成します。データベースに投稿をコピーしなくても、フォルダのファイルを資料の原本として使用できます。

始める前に

スキーマとAPIをデプロイする権限が必要です。
掲示板で提供するファイルを、books/guideフォルダに用意します。
公開範囲に合わせて、エンドポイントの読み取り権限を先に決めます。

この例では、.mdと.pngだけを提供し、サブフォルダは照会しません。

books/
└── guide/
    ├── getting-started.md
    ├── permissions.md
    └── permissions.png

ディレクトリエンドポイントを構成する

この例では、データベース識別子にguide、テーブル名にassets、カスタムパスにcontentを使用します。

スキーマファイルを開き、APIビルドを選択します。
assetsテーブルで、静的ファイルAPIを追加を選択します。
カスタムパスにcontentを入力します。
公開対象で、フォルダー一覧・ファイル閲覧を選択します。
フォルダーを選択で、books/guideを選択します。
許可する拡張子に、.mdと.pngを追加します。
サブフォルダまで提供する場合は、サブフォルダーを含むをオンにします。この例ではオフにします。
掲示板の公開範囲に合わせて、エンドポイントの権限を設定します。

設定した結果の静的ファイルのコントラクトは、次のとおりです。

{
  "mode": "directory",
  "extensions": [".md", ".png"],
  "recursive": false
}

modeは、単一のファイルを提供するfileと、フォルダを提供するdirectoryのどちらかです。extensionsは、応答する拡張子の許可リストです。recursiveがfalseの場合は、books/guideの直下にあるファイルだけが一覧に含まれます。サブフォルダのファイルも提供する場合は、recursiveをtrueに設定します。

APIをデプロイする

画面下部に固定されているデプロイバーで配布するを選択し、パネルを上方向に展開します。この段階では、まだデプロイされません。
データベース識別子にguideを入力し、ストレージエンジンモードとクライアント配布パスを確認します。
展開されたパネルの中の配布するを、もう一度選択します。
デプロイが終わったら、/api/web/guide/assets/contentで一覧の応答を確認します。

ファイルの一覧を取得する

ファイルを指定せずにディレクトリエンドポイントにリクエストすると、JSONの一覧が返されます。

{
  "items": [
    {
      "name": "getting-started.md",
      "path": "getting-started.md",
      "size": 1842,
      "mimeType": "text/markdown; charset=utf-8",
      "modifiedAt": "2026-10-02T09:30:00Z",
      "url": "/api/web/guide/assets/content?file=getting-started.md"
    }
  ],
  "total": 3,
  "offset": 0,
  "limit": 20
}

一覧画面ではnameをタイトルとして表示し、ファイルを選択するときはurlを使用します。結果の総数はtotal、現在の範囲はoffsetとlimitで確認します。

次のクエリで、一覧を絞り込めます。

クエリ	例	用途
`q`	`q=permission`	ファイル名を検索します。
`order`	`order=name:asc`	名前の昇順で並べ替えます。
`order`	`order=modifiedAt:desc`	最近変更されたファイルから順に並べ替えます。
`offset`	`offset=20`	スキップするファイルの数を指定します。
`limit`	`limit=20`	一度に受け取るファイルの数を指定します。

GET /api/web/guide/assets/content?q=permission&order=modifiedAt:desc&offset=0&limit=20

limitを省略すると50件が返され、1回のリクエストの最大値は200です。ファイルがそれより多い場合は、応答のtotalを確認し、offsetを増やして次の一覧をリクエストします。orderを省略するとname:ascが適用され、qは最大256文字です。

選択した文書を表示する

一覧で受け取った相対パスをfileクエリに渡すと、そのファイルの内容を受け取れます。下位にあるファイルの相対パスは、recursiveがtrueの場合にのみ使用できます。

GET /api/web/guide/assets/content?file=getting-started.md

.mdファイルはMarkdownレンダラーで本文を表示し、.pngファイルは画像のURLとして使用します。クライアントでファイルのパスを直接組み立てるよりも、一覧の応答のurlを使用するほうが、エンドポイントのパスの変更に対応しやすくなります。

注意事項

extensionsには、公開する形式だけを入れます。この例では、.mdと.pngだけを許可します。
拡張子は、最大32個まで指定できます。
ドット（.）で始まる隠しファイル・フォルダとシンボリックリンクは、一覧でもファイルのリクエストでも提供されません。
元のフォルダの外に出る相対パスは使用できません。
一覧とファイルの内容には、同じエンドポイントACLが適用されます。公開エンドポイントの場合はlogin: falseを明示し、メンバー向けのエンドポイントの場合は、必要なロール・レベル・チームの条件まで確認します。
サーバーは、正確なtotalと並べ替えの結果を作成するために、ファイルとフォルダを最大2,000件までスキャンします。隠しパスや拡張子のフィルターによって応答から除外される項目も、スキャン数に含まれます。上限を超えた場合は、一覧の一部を返すことはせず、413エラーでリクエスト全体を拒否します。
ファイルを追加または変更した後は、一覧のmodifiedAtと画面の内容が更新されていることを確認します。
掲示板の画面でMarkdownをHTMLに変換するときは、スクリプトと危険なマークアップを許可しないよう、レンダラーのポリシーを確認します。