Word 파일을 웹 준비 마크업으로 변환하는 것은 문서 포털, 블로그 또는 e‑learning 플랫폼을 구축할 때 자주 필요한 작업입니다. GroupDocs.Conversion Cloud SDK for Python 은 클라우드에서 무거운 작업을 처리하는 강력한 API를 제공하므로 애플리케이션 로직에 집중할 수 있습니다. 이 가이드에서는 Python에서 HTML 로 워드 문서를 변환 하는 방법을 단계별로 배우고, 전체 코드 예제를 확인하며, 동등한 cURL 호출을 탐색하고, 대규모 변환을 위한 성능 팁을 얻을 수 있습니다.

Python에서 Word 문서를 HTML로 변환하는 방법 - 단계별

  1. DOCX 파일을 GroupDocs Cloud 스토리지에 업로드: StorageApi.upload_file 메서드를 사용하여 로컬 Word 파일을 클라우드에 배치합니다.

    with open(LOCAL_INPUT_PATH, "rb") as input_stream:
    storage_api.upload_file(path=REMOTE_INPUT_PATH, file=input_stream)

    이 단계는 파일이 변환 서비스에서 접근 가능하도록 보장합니다.

  2. HTML 변환 옵션 구성: 스타일, 이미지 및 하이퍼링크를 보존하기 위해 HtmlConvertOptions 인스턴스를 생성합니다.

html_options = HtmlConvertOptions()  # Default options preserve most formatting

세부적인 제어를 위해 HTML 변환 옵션 문서를 참조하세요.

  1. HTML로 변환 요청: 원격 입력 경로와 대상 형식 "html" 및 출력 경로를 사용하여 ConvertDocumentRequest를 생성합니다.
convert_request = ConvertDocumentRequest(
    file_path=REMOTE_INPUT_PATH,
    format="html",
    output_path=REMOTE_OUTPUT_PATH,
    options=html_options,
)
conversion_api.convert_document(convert_request)

SDK는 비동기 처리가 필요한 경우 폴링할 수 있는 작업 ID를 반환합니다.

  1. 생성된 HTML 파일 다운로드: StorageApi.download_file를 사용하여 변환된 파일을 가져옵니다.
downloaded_bytes = storage_api.download_file(path=REMOTE_OUTPUT_PATH)
with open(LOCAL_OUTPUT_PATH, "wb") as output_stream:
    output_stream.write(downloaded_bytes)

결과물인 sample.html은 웹 게시를 위해 준비된 깔끔하고 표준을 준수하는 마크업을 포함합니다.

  1. 임시 파일 정리: 소스 DOCX와 생성된 HTML을 클라우드 스토리지에서 삭제하여 계정을 깔끔하게 유지합니다.
storage_api.delete_file(DeleteFileRequest(path=REMOTE_INPUT_PATH))
storage_api.delete_file(DeleteFileRequest(path=REMOTE_OUTPUT_PATH))

이 마지막 단계는 불필요한 스토리지 비용을 방지합니다.

이 단계들을 따라 하면 자동화 파이프라인에서 Python으로 워드 문서를 HTML로 안정적으로 변환할 수 있습니다.

Python에서 Word 문서에서 HTML을 생성하는 전체 작업 예제

아래 예제는 인증부터 정리까지 전체 워크플로를 보여주며, GroupDocs.Conversion Cloud SDK for Python을 사용합니다.

import os
from groupdocs_conversion_cloud import (
    Configuration,
    ApiClient,
    ConversionApi,
    ConvertDocumentRequest,
    HtmlConvertOptions,
)
from groupdocs_storage_cloud import (
    Configuration as StorageConfiguration,
    ApiClient as StorageApiClient,
    StorageApi,
    DeleteFileRequest,
)

# ----------------------------------------------------------------------
# Replace these placeholders with your actual GroupDocs Cloud credentials
# ----------------------------------------------------------------------
CLIENT_ID = "YOUR_CLIENT_ID"
CLIENT_SECRET = "YOUR_CLIENT_SECRET"

# --------------------------- Conversion API ----------------------------
conv_config = Configuration(client_id=CLIENT_ID, client_secret=CLIENT_SECRET)
conv_api_client = ApiClient(conv_config)
conversion_api = ConversionApi(conv_api_client)

# ---------------------------- Storage API ------------------------------
storage_config = StorageConfiguration(client_id=CLIENT_ID, client_secret=CLIENT_SECRET)
storage_api_client = StorageApiClient(storage_config)
storage_api = StorageApi(storage_api_client)

# --------------------------- File Paths --------------------------------
LOCAL_INPUT_PATH = "sample.docx"      # Existing Word document on your machine
LOCAL_OUTPUT_PATH = "sample.html"     # Desired HTML output location

REMOTE_INPUT_PATH = "sample.docx"     # Path inside GroupDocs Cloud storage
REMOTE_OUTPUT_PATH = "sample.html"    # Path inside GroupDocs Cloud storage

# --------------------------- Upload Input ------------------------------
with open(LOCAL_INPUT_PATH, "rb") as input_stream:
    storage_api.upload_file(path=REMOTE_INPUT_PATH, file=input_stream)

# --------------------------- Convert to HTML ---------------------------
html_options = HtmlConvertOptions()  # Default HTML conversion options

convert_request = ConvertDocumentRequest(
    file_path=REMOTE_INPUT_PATH,
    format="html",
    output_path=REMOTE_OUTPUT_PATH,
    options=html_options,
)

conversion_api.convert_document(convert_request)

# --------------------------- Download Result ---------------------------
downloaded_bytes = storage_api.download_file(path=REMOTE_OUTPUT_PATH)

with open(LOCAL_OUTPUT_PATH, "wb") as output_stream:
    output_stream.write(downloaded_bytes)

# --------------------------- Cleanup Remote Files ----------------------
storage_api.delete_file(DeleteFileRequest(path=REMOTE_INPUT_PATH))
storage_api.delete_file(DeleteFileRequest(path=REMOTE_OUTPUT_PATH))

참고: 이 코드 예제는 핵심 기능을 보여줍니다. 프로젝트에 사용하기 전에 파일 경로와 구성 값을 실제 환경에 맞게 업데이트하고, 모든 필수 종속성이 올바르게 설치되었는지 확인하며, 개발 환경에서 충분히 테스트하십시오. 문제가 발생하면 공식 문서를 참조하거나 지원 팀에 문의하세요.

cURL을 사용한 REST API로 Word를 HTML로 변환

순수 HTTP 방식을 선호한다면, 동일한 변환을 cURL 명령으로 수행할 수 있습니다. 이 순서는 SDK 단계와 동일합니다: 액세스 토큰을 얻고, DOCX를 업로드하고, 변환을 시작한 다음, HTML 결과를 다운로드합니다.

# 1. Get an access token
curl -X POST "https://api.groupdocs.cloud/v2.0/auth/token" \
     -H "Content-Type: application/json" \
     -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'
# Response contains "access_token"

# 2. Upload the source DOCX
curl -X PUT "https://api.groupdocs.cloud/v2.0/storage/file/sample.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/octet-stream" \
     --data-binary "@sample.docx"

# 3. Request conversion to HTML
curl -X POST "https://api.groupdocs.cloud/v2.0/conversion/convert?format=html&outputPath=sample.html" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"filePath":"sample.docx","options":{}}'

# 4. Download the HTML result
curl -X GET "https://api.groupdocs.cloud/v2.0/storage/file/sample.html" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o sample.html

이 명령은 요청 헤더와 페이로드를 완전히 제어할 수 있게 해 주며, 디버깅이나 비‑Python 환경과의 통합에 유용할 수 있습니다. 자세한 내용은 API 참조를 참조하십시오.

Word를 HTML로 변환하기 위한 환경 준비

코드를 작성하기 전에 개발 머신이 사전 요구 사항을 충족하는지 확인하십시오:

  • Python 3.7+ - SDK는 최신 언어 기능에 의존합니다.

  • GroupDocs Cloud credentials - 귀하의 GroupDocs 계정에서 클라이언트 ID와 비밀을 가져옵니다.

  • Package installation - pip를 통해 SDK를 설치합니다.

    pip install groupdocs-conversion-cloud

    패키지는 다운로드 페이지에서 사용할 수 있습니다.

  • 네트워크 액세스 - SDK는 GroupDocs 서버에 HTTPS 호출을 수행하므로, 아웃바운드 포트 443이 열려 있어야 합니다.

이 항목들이 준비되면, 앞에서 보여준 전체 예제를 실행하고 Python에서 워드 문서를 HTML로 변환을 즉시 시작할 수 있습니다.

HTML 변환 성능 최적화

대량 배치 또는 고 트래픽 서비스를 처리할 때, 다음 최적화를 고려하십시오:

  1. API 클라이언트 인스턴스 재사용 - 각 파일마다 ConversionApi 및 StorageApi 객체를 생성하면 오버헤드가 발생합니다. 한 번 인스턴스를 생성하고 변환 전반에 걸쳐 재사용하십시오.
  2. 업로드 및 다운로드 스트리밍 - 몇 메가바이트보다 큰 파일의 경우 스트리밍 API를 사용하여 전체 파일을 메모리에 로드하는 것을 피하십시오. SDK는 파일과 유사한 객체를 지원하므로 파일 핸들에서 직접 전달할 수 있습니다.
  3. 독립적인 변환 병렬 처리 - 여러 개의 DOCX 파일이 있는 경우 별도의 스레드 또는 비동기 작업으로 변환을 실행하십시오. 각 변환은 서버 측에서 격리되므로 병렬 처리는 계정 제한까지 선형적으로 확장됩니다.
  4. 크기 조정을 위한 HTML 옵션 설정 - 내장 CSS를 비활성화(html_options.embed_css = False)하면 외부 스타일시트를 적용할 계획일 때 출력 크기를 줄일 수 있습니다.

이 팁들을 적용하면 지연 시간을 낮게 유지하고 리소스 사용량을 예측 가능하게 만들 수 있으며, 특히 고용량 웹 서비스에서 Python으로 Word 문서에서 HTML을 생성해야 할 때 도움이 됩니다.

자주 묻는 질문

Python에서 GroupDocs를 사용하여 워드 문서를 HTML로 변환하려면 어떻게 해야 하나요?

GroupDocs.Conversion Cloud SDK for Python를 사용하십시오. 이 SDK를 사용하면 DOCX를 업로드하고, 변환 API를 호출하며, 몇 줄의 코드만으로 HTML 출력을 다운로드할 수 있습니다.

Python에서 Word 파일을 HTML로 변환할 때 사용할 수 있는 옵션은 무엇인가요?

HtmlConvertOptions 클래스는 스타일, 이미지 및 하이퍼링크를 보존할 수 있게 해줍니다. 또한 속성을 통해 CSS 삽입 및 페이지 레이아웃을 제어할 수 있습니다.

Python에서 여러 Word 문서를 HTML로 일괄 변환할 수 있나요?

예. DOCX 경로 목록을 반복하면서 각 파일을 업로드하고 동일한 변환 요청을 호출하면 됩니다. SDK는 각 작업을 독립적으로 처리합니다.

테스트에 임시 라이선스가 필요합니까?

임시 라이선스는 임시 라이선스 페이지에서 얻을 수 있습니다. 전체 라이선스를 구매하기 전에 SDK를 평가할 수 있게 해줍니다.

GroupDocs.Conversion Cloud SDK for Python의 가격 세부 정보를 어디서 찾을 수 있나요?

가격 정보는 제품 페이지에서 확인할 수 있습니다. 최신 플랜은 GroupDocs.Conversion Cloud SDK for Python를 방문하십시오.

Read More