내보내기 API 서버

3.3.2602 버전부터 지원합니다.

기능 설명

내보내기 API 서버는 에디터에서 사용된 이미지를 다운로드한 후, 문서를 HWPX 또는 DOCX와 같은 다양한 형식으로 변환하여 파일을 반환합니다.

런타임 환경

내보내기 API Docker 이미지는 영업 담당자를 통해 요청해야 합니다.

이 내보내기 API 실행 모듈은 Docker 컨테이너 환경에서 실행됩니다.

Docker를 설치하고 실행할 수 있는 Linux 운영 체제에서 사용할 수 있습니다.

다음은 검증된 환경의 예시입니다:

• Ubuntu 18.04 이상
• CentOS 7 이상 / RHEL 7 이상
• Debian 9 이상
• Fedora 30 이상

프로덕션 환경에서는 Linux(x86_64 / amd64) 서버에서의 실행을 권장합니다. 이 환경에서는 아키텍처 에뮬레이션 없이 네이티브로 실행되어 최고의 성능과 안정성을 제공합니다.

컨테이너의 내부 런타임은 node:18-slim 이미지 기반이므로, 실행 모듈의 동작에는 호스트 운영 체제에 따른 차이가 없습니다.

Docker Desktop을 통해 macOS(Apple Silicon) 및 Windows 환경에서도 실행할 수 있지만, 아키텍처 에뮬레이션이 사용될 수 있으므로 개발 및 테스트 용도로만 사용하는 것을 권장합니다.

실행 방법

## Installation
# Load Docker image:
docker load -i export_api.tar

# Docker run
docker run -d --name export-api \
  -p 9090:9090 \
  -e REMOTE_SOURCE_PROXY_DOMAINS=example.com,.internal.local \
  -e REMOTE_SOURCE_PROXY_TARGET=http://10.0.0.5:8080/remote/ \
  export-api:latest

환경 변수

직접 다운로드가 실패하는 경우

서버(또는 Docker 컨테이너)가 기업 네트워크 차단, 인증 요구 사항, IP/지역 제한, HTTP↔HTTPS 정책 등으로 인해 외부 이미지를 직접 받을 수 없는 경우, 해당 이미지는 깨진 이미지로 표시됩니다.

프록시 설정을 통한 우회

• REMOTE_SOURCE_PROXY_DOMAINS: 프록시를 적용할 도메인 목록을 쉼표로 구분하여 지정합니다. 예시: .example.com,cdn.partner.com.
• REMOTE_SOURCE_PROXY_TARGET: 실제 이미지를 대신 다운로드할 프록시 서버 주소를 지정합니다. 예시: http://proxy.internal/....

이 두 변수를 설정하면, 서버는 지정된 도메인의 이미지를 프록시를 통해 다운로드하려고 시도합니다.

또한, 인증과 같은 사용자 정의 HTTP 헤더가 필요한 경우, REMOTE_SOURCE_HEADERS에 headerName:value 형식으로 지정합니다. (예: X-Custom-Auth:my-key)

프록시를 설정해도 실패하는 경우

프록시 인증 실패, 프록시 서버 오류, 추가 권한 요구 등과 같은 문제가 발생하면 이미지를 여전히 가져오지 못할 수 있으며, 이 경우 최종 결과에는 이미지가 깨진 이미지로 표시됩니다.

임시 파일 저장 정책

변환 과정에서 다운로드된 이미지, 생성된 .word.pb, 출력 파일과 같은 모든 리소스는 작업이 완료된 직후 즉시 삭제됩니다.

API

/exportFile 요청 필드 (multipart/form-data)

Synap Editor 클라이언트는 다음 필드를 전송합니다:

payload JSON 구조

{
  "filename": "document",
  "exportType": "hwpx",
  "responseType": "json",
  "mediaManifest": [
    {
      "path": "image/image1.png",
      "filename": "image1.png",
      "isRemote": false,
      "sourceUrl": null,
      "contentType": "image/png"
    },
    {
      "path": "https://example.com/logo.png",
      "filename": "logo.png",
      "isRemote": true,
      "sourceUrl": "https://example.com/logo.png",
      "contentType": "image/png"
    }
  ]
}

payload 필드 설명

mediaManifest 항목 설명

처리 규칙

• serializedData는 multipart 파일 필드로 전송되어야 합니다.
• mediaManifest에 isRemote: true와 sourceUrl이 존재하면, 서버는 해당 URL에서 이미지를 다운로드합니다.
• isRemote가 설정되지 않은 경우, 서버는 media 파일 배열에서 이미지를 순차적으로 매칭합니다.
• 따라서, media의 업로드 순서는 mediaManifest의 비원격 항목 순서와 일치해야 합니다.

관련 정보

• 내보내기 API 설정