폴더 파일로 자료 게시판 만들기

books/guide 폴더에 Markdown 문서와 이미지를 저장하고, Webspace에서 파일 목록과 선택한 파일 내용을 제공하는 게시판을 구성합니다. 데이터베이스에 게시물을 복사하지 않아도 폴더의 파일을 자료 원본으로 사용할 수 있습니다.

시작하기 전에

• 스키마와 API를 배포할 권한이 필요합니다.
• 게시판에서 제공할 파일을 books/guide 폴더에 준비합니다.
• 공개 범위에 맞게 엔드포인트 읽기 권한을 먼저 정합니다.

예제에서는 .md와 .png만 제공하며 하위 폴더는 조회하지 않습니다.

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

디렉터리 엔드포인트 구성하기

예제의 데이터베이스 식별자는 guide, 테이블 이름은 assets, 커스텀 경로는 content로 사용합니다.

1. 스키마 파일을 열고 API 빌드를 선택합니다.
2. assets 테이블에서 정적 파일 API 추가를 선택합니다.
3. 커스텀 경로에 content를 입력합니다.
4. 공개 대상에서 폴더 목록 · 파일 읽기를 선택합니다.
5. 폴더 선택에서 books/guide를 선택합니다.
6. 허용 확장자에 .md와 .png를 추가합니다.
7. 하위 폴더까지 제공하려면 하위 폴더 포함을 켭니다. 이 예제에서는 끕니다.
8. 게시판 공개 범위에 맞게 엔드포인트 권한을 설정합니다.

설정 결과의 정적 파일 계약은 다음과 같습니다.

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

mode는 단일 파일을 제공하는 file과 폴더를 제공하는 directory 중 하나입니다. extensions는 응답할 확장자 허용 목록입니다. recursive가 false이면 books/guide 바로 아래의 파일만 목록에 포함됩니다. 하위 폴더의 파일도 제공하려면 recursive를 true로 설정합니다.

API 배포하기

1. 화면 하단 고정 배포 바에서 배포하기를 선택해 패널을 위쪽으로 펼칩니다. 이 단계에서는 아직 배포되지 않습니다.
2. 데이터베이스 식별자에 guide를 입력하고 스토리지 엔진 모드와 클라이언트 배포 경로를 확인합니다.
3. 펼쳐진 패널 안의 배포하기를 다시 선택합니다.
4. 배포가 끝나면 /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으로 확인합니다.

다음 쿼리로 목록을 좁힐 수 있습니다.

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

limit을 생략하면 50개를 반환하며 한 요청의 최대값은 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로 변환할 때는 스크립트와 위험한 마크업을 허용하지 않도록 렌더러 정책을 확인합니다.

관련 문서

• API 빌드 및 데이터베이스 배포하기
• 프론트엔드 샘플 확인하기
• 웹사이트 배포하기