@roottale/cms-mcp
Version:
RootTale CMS MCP server and CLI for models, entries, exposures, media, integration docs, and public API access.
51 lines (42 loc) • 2.95 kB
Markdown
# 미디어 업로드 결과와 재시도
미디어를 연동할 때는 [업로드 API](../../docs/api-reference.md#미디어-업로드-api)의
3단계를 따릅니다. 업로드 URL 발급 응답의 `r2_key`를 완료 요청용으로 보관하고,
공개 페이지에는 완료 응답의 `url`을 사용합니다. 보존이 활성화된 환경에서는
임시 업로드 경로와 최종 `r2_key`가 다릅니다.
보존 조회의 일시적 오류는 서버가 제한 재시도합니다. 아래 `503` 처리는 그 재시도
후에도 보존을 확인하지 못한 경우에 적용하며, 성공 응답 전에는 등록 완료로 표시하지 않습니다.
```ts
// 인증된 서버 측 작업에서 실행합니다. API 키를 클라이언트 번들에 넣지 않습니다.
// uploadRequest는 1단계 응답, fileInfo는 1단계에 보낸 파일 정보입니다.
const completionBody = {
...fileInfo,
r2_key: uploadRequest.r2_key,
};
const completed = await fetch(`${apiBase}/v1/cms/media/uploads/complete`, {
method: "POST",
headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
body: JSON.stringify(completionBody),
});
if (completed.status === 503) {
// 같은 completionBody를 보관해 잠시 뒤 재시도합니다.
// 이때 새 업로드를 발급하거나 임시 경로로 공개 URL을 만들지 않습니다.
throw new Error("파일 보존 확인이 지연되고 있습니다. 같은 업로드를 다시 완료해 주세요.");
}
if (!completed.ok) throw new Error("미디어 등록에 실패했습니다.");
const media = await completed.json(); // 신규201 또는 멱등 재시도200
// 글 연결에는 media.id, 본문 이미지에는 media.url을 사용합니다.
```
삭제는 서버에서 `DELETE /v1/cms/media/{media_id}`로 요청합니다. `200`일 때만
공개 파일 정리 완료로 안내하세요. `503`이고 메시지가 공개 파일 정리 대기를 알리면
관리 목록에서는 이미 사라졌어도 서버가 원본·변형 이미지·CDN 캐시를 자동으로 재정리합니다.
이 경우 같은 파일을 다시 업로드하거나 목록에서 사라졌다는 이유로 완료 안내를 보내지 않습니다.
## 배경 영상 선택
영상 업로드·삭제는 ROOT-ADMIN의 루트테일 직원 화면을 사용합니다. REST·CLI·MCP로는
올리거나 삭제할 수 없습니다. 고객은 `file` 필드에 `mediaKind: "video"`를 지정한
선택창에서 기존 영상을 연결합니다. 공개 글과 미리보기의 필드 값을 그대로 사용합니다.
```tsx
// video는 fields의 영상 file 값. 모바일 화면에서는 variants.mobile을 고릅니다.
<video src={video.url} poster={video.variants.poster} autoPlay muted loop playsInline />
```
PC는 `url`·`variants.poster`, 모바일은 `variants.mobile`·`variants.mobilePoster`를
짝으로 사용합니다. 네 주소 모두 HTTPS이며 영상에는 소리가 없습니다.