문서 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`

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

각 경로 세그먼트를 UTF-8 URL 데이터로 인코딩하지만 디렉터리 간에는 /를 유지합니다. 편집 세션을 위해 URL-안전한 docId를 생성합니다. 신뢰할 수 없는 파일 시스템 경로를 세션 식별자로 재사용하지 마십시오.

/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을 엽니다.
열린 문서를 편집하고 저장합니다.
원본 문서가 수정되었는지 확인합니다.

에디터와 뷰어 선택​

JavaScript에서 URL 만들기​

결과 확인​

에디터와 뷰어 선택

JavaScript에서 URL 만들기

결과 확인