문서 URL 생성

등록된 스토리지 어댑터의 문서를 열려면 Office의 open 엔드포인트를 사용합니다. 먼저 Self-hosted Office 실행을 완료합니다. 이 예제는 포트 8080과 미리 연결된 Host Storage 어댑터 host-storage를 사용합니다.

http://localhost:8080/cloud-office/api/{ADAPTER_NAME}/{DOCUMENT_PATH}/open
  ?app={APP_MODE}
  &user_id={USER_ID}
  &docId={UNIQUE_DOCUMENT_ID}

에디터와 뷰어 선택

문서를 편집하고 저장하려면 에디터를, 편집 없이 열람하려면 뷰어를 선택합니다. 문서 종류와 용도에 맞춰 URL의 app 값을 지정합니다.

문서 확장자	에디터의 `app` 값	뷰어의 `app` 값
DOC, DOCX, ODT	`WORD_EDITOR`	`WORD_VIEWER`
XLS, XLSX, ODS	`CELL_EDITOR`	`CELL_VIEWER`
PPT, PPTX, ODP	`SHOW_EDITOR`	`SHOW_VIEWER`
PDF	-	`PDF_VIEWER`

예를 들어 Word 문서를 뷰어로 열려면 같은 open URL에서 app=WORD_VIEWER를 사용합니다. 어댑터 이름과 문서 경로를 지정하는 방법은 에디터와 같습니다. PDF 문서는 app=PDF_VIEWER로 뷰어에서만 열 수 있으며 PDF 에디터는 없습니다.

각 경로 세그먼트를 UTF-8 URL 데이터로 인코딩하지만 디렉터리 간에는 /를 유지합니다. Office에서 문서를 구분할 URL-safe ID인 docId를 지정합니다. 신뢰할 수 없는 파일 시스템 경로를 문서 ID로 그대로 사용하지 않습니다.

/home/thinkfree/docs/contracts/Proposal 2026.docx의 예:

http://localhost:8080/cloud-office/api/host-storage/contracts/Proposal%202026.docx/open?app=WORD_EDITOR&user_id=local-user&docId=contract-2026-001

JavaScript에서 URL 만들기

다음 함수는 파일 확장자에 맞는 에디터 URL을 만듭니다.

const editorMode = {
  doc: "WORD_EDITOR", docx: "WORD_EDITOR", odt: "WORD_EDITOR",
  xls: "CELL_EDITOR", xlsx: "CELL_EDITOR", ods: "CELL_EDITOR",
  ppt: "SHOW_EDITOR", pptx: "SHOW_EDITOR", odp: "SHOW_EDITOR",
};

export function createOfficeUrl(baseUrl, adapterName, documentPath, userId = "local-user") {
  // Keep directory separators while encoding every untrusted segment.
  const encodedPath = documentPath.split("/").map(encodeURIComponent).join("/");
  const extension = documentPath.split(".").pop().toLowerCase();
  const app = editorMode[extension];
  if (!app) throw new Error(`Unsupported document type: ${extension}`);

  // A unique ID keeps this open request separate from other editing sessions.
  const docId = crypto.randomUUID().replaceAll("-", "");
  const query = new URLSearchParams({app, user_id: userId, docId});
  const encodedAdapter = encodeURIComponent(adapterName);
  return `${baseUrl.replace(/\/$/, "")}/cloud-office/api/${encodedAdapter}/${encodedPath}/open?${query}`;
}

아래 예제는 미리 연결된 Host Storage의 내장 Word 샘플을 여는 URL을 반환합니다. 브라우저의 JavaScript 모듈에서 실행하거나 위 함수를 사용하는 애플리케이션 코드에 추가합니다. 직접 디렉터리를 마운트했다면 실제 파일 경로로 바꿉니다.

const url = createOfficeUrl("http://localhost:8080", "host-storage", "sample.docx");
console.log(url);

같은 Word 샘플을 뷰어로 열려면 생성한 URL의 app 값을 바꾸고 새 docId를 지정합니다.

const viewerUrl = new URL(url);
viewerUrl.searchParams.set("app", "WORD_VIEWER");
viewerUrl.searchParams.set("docId", crypto.randomUUID().replaceAll("-", ""));
console.log(viewerUrl.href);

결과 확인

/home/thinkfree/docs 아래에 있는 파일의 에디터 URL을 만듭니다.
브라우저에서 URL을 엽니다.
열린 문서를 편집하고 저장합니다.
원본 문서가 수정되었는지 확인합니다.

Office를 직접 운영하지 않고 Thinkfree 관리형 편집기를 사용하려면 계정 소유 스토리지 연결에 대해 반환되는 단기 뷰어 및 편집기 URL을 정의하는 Cloud Office API 참조를 사용하세요.

에디터와 뷰어 선택​

JavaScript에서 URL 만들기​

결과 확인​

에디터와 뷰어 선택

JavaScript에서 URL 만들기

결과 확인