스토리지 (Storage)
파일 업로드 및 관리 API입니다. 모든 메서드는 storageId (stg_xxx 형식, 콘솔에서 발급)를 받습니다.
💡 Connect Base의 파일 업로드는 Presigned URL 방식입니다. SDK가 내부적으로 ① presigned URL 발급 → ② Object Storage에 직접 PUT → ③ 완료 알림 의 3단계를 자동으로 처리합니다.
파일 업로드
기본 업로드
html
<input type="file" id="avatar" />typescript
const input = document.getElementById('avatar') as HTMLInputElement
const file = input.files?.[0]
if (!file) throw new Error('파일을 선택해주세요')
// cb.storage.uploadFile(storageId, file, parentId?)
const result = await cb.storage.uploadFile('stg_xxx', file)
console.log(result.url, result.id, result.size)폴더 안에 업로드
먼저 createFolder 로 폴더를 만들고, 반환된 폴더 ID를 parentId 로 전달합니다.
typescript
const folder = await cb.storage.createFolder('stg_xxx', { name: 'avatars' })
const result = await cb.storage.uploadFile('stg_xxx', file, folder.id)여러 파일 업로드
typescript
const input = document.getElementById('files') as HTMLInputElement
const files = Array.from(input.files ?? [])
const results = await cb.storage.uploadFiles('stg_xxx', files)
results.forEach((r) => console.log(r.url))경로 기반 업로드 (덮어쓰기)
같은 경로에 다시 업로드하면 파일만 교체되어 URL이 유지됩니다. 프로필 이미지처럼 고정 URL이 필요할 때 사용합니다.
typescript
const result = await cb.storage.uploadByPath(
'stg_xxx',
'/profiles/user123/avatar.png',
file
)
console.log(result.url) // 다시 업로드해도 동일한 URL파일 조회
목록
typescript
const files = await cb.storage.getFiles('stg_xxx')
files.forEach((f) => console.log(f.name, f.url, f.size))경로로 조회
typescript
const file = await cb.storage.getByPath('stg_xxx', '/profiles/user123/avatar.png')
console.log(file.url)
// URL만 필요하면 (없으면 null)
const url = await cb.storage.getUrlByPath('stg_xxx', '/profiles/user123/avatar.png')파일 삭제 / 이동 / 이름 변경
typescript
// 삭제
await cb.storage.deleteFile('stg_xxx', 'file_123')
// 이동 (다른 폴더로) — 루트로 이동하려면 new_parent_id 생략
await cb.storage.moveFile('stg_xxx', 'file_123', { new_parent_id: 'folder_456' })
// 이름 변경
await cb.storage.renameFile('stg_xxx', 'file_123', { name: 'new-name.png' })헬퍼 메서드
typescript
const file = (await cb.storage.getFiles('stg_xxx'))[0]
cb.storage.getFileUrl(file) // file.url 반환 (없으면 null)
cb.storage.isImageFile(file) // mime_type 으로 이미지 여부 판단페이지 메타 (정적 호스팅 SEO)
웹 스토리지에 배포된 페이지마다 OG 태그 / JSON-LD 구조화 데이터를 설정할 수 있습니다.
typescript
await cb.storage.setPageMeta('web_storage_id', {
path: '/products/123',
title: '최신 스마트폰',
description: '최고의 성능, 최저가 보장',
image: 'https://example.com/product.jpg',
og_type: 'product',
json_ld: JSON.stringify({
'@context': 'https://schema.org',
'@type': 'Product',
name: '최신 스마트폰'
})
})
// 일괄 설정 (최대 100개)
await cb.storage.batchSetPageMeta('web_storage_id', {
pages: [
{ path: '/products/1', title: '상품 1', description: '설명 1' },
{ path: '/products/2', title: '상품 2', description: '설명 2' }
]
})
// 조회 / 삭제
const meta = await cb.storage.getPageMeta('web_storage_id', '/products/123')
const list = await cb.storage.listPageMetas('web_storage_id', { limit: 20, offset: 0 })
await cb.storage.deletePageMeta('web_storage_id', '/products/123')
await cb.storage.deleteAllPageMetas('web_storage_id')응답 타입
typescript
interface UploadFileResponse {
id: string
name: string
path: string
type: string // 'file' | 'folder'
mime_type: string
size: number
url: string
parent_id?: string
created_at: string
}