Microsoft Excel 파일 연결과 변경

Microsoft Excel 커넥터는 저장소의 통합 문서를 읽어 워크시트와 셀 범위를 관계형 테이블로 제공합니다. 원천 탐색, 배치 동기화, 증분 수집, OAuth 2.0 인증과 테이블 내보내기는 Beta 단계입니다. 플랫폼 인스턴스에서 제공되지 않을 수 있고 기능이 변경될 수 있습니다.

읽기 작업도 통합 문서를 수정할 수 있습니다. 기본적으로 커넥터는 변경된 셀의 영향을 받는 수식을 다시 계산하고 결과를 워크시트에 씁니다. 파일을 바꾸지 않고 저장된 수식 결과만 읽으려면 Recalculate=FALSE로 설정합니다. 다른 프로세스도 같은 파일을 수정하는 경우에 특히 주의합니다.

연결 방식 선택

지원 저장소에는 Amazon S3, Azure Blob Storage, OneDrive, SharePoint와 SFTP 서버가 있습니다. 파일 자체를 수집하는 경우에는 저장소 커넥터와 함께 Transforms용 Excel parser, Pipeline Builder의 parseExcel, pandas.read_excel 또는 openpyxl을 사용할 수 있습니다. 컴퓨터의 파일을 한 번 올리려는 목적이면 Foundry에 파일을 끌어다 놓는 수동 업로드도 가능합니다.

소스와 인증 구성

Data Connection의 +New Source에서 Microsoft Excel을 선택하고, 실제 파일 저장소에 맞는 ConnectionType과 인증 방식을 지정합니다. 저장소의 인증과 네트워크 조건을 따르므로 Excel 파일 자체의 경로만으로 연결이 완성되지는 않습니다.

예를 들어 OneDrive의 파일을 위임된 Microsoft Entra ID 사용자 권한으로 읽으면 ConnectionType=OneDrive, AuthScheme=AzureAD, InitiateOAuth=REFRESH로 설정하고 앱의 client ID와 secret을 제공합니다.

OAuth 인증 코드 흐름은 Foundry 워커에서 사용합니다. 소스의 콜백 URL을 외부 앱에 등록하고 저장한 뒤 Authorize로 승인합니다. 승인 시작, 갱신과 철회에는 기본적으로 소스 Owner 역할이 필요하며 Viewer와 Editor만으로는 수행할 수 없습니다. ConnectOnOpen=true는 이 OAuth 흐름과 함께 사용할 수 없습니다.

저장소와 인증 엔드포인트에 외부 통신 정책을 추가합니다. 필요한 호스트는 ConnectionType, AuthScheme, 계정과 리전에 따라 달라집니다. Foundry에서 직접 도달할 수 없는 저장소는 에이전트 프록시 정책을 사용하고 에이전트 호스트의 연결도 확보합니다.

워크시트 읽기

원천 탐색에서 워크시트 테이블을 선택하고 배치 동기화를 구성하면 데이터를 Foundry 데이터셋에 저장합니다. CData 카탈로그 아래에서 통합 문서는 스키마, 워크시트는 테이블로 나타납니다. URI에 파일 대신 폴더를 지정하면 그 폴더의 여러 통합 문서를 탐색합니다.

Excel의 한 열에 여러 자료형의 값이 섞여 있으면 숫자가 텍스트로 수집될 수 있습니다. 숫자 연산에 사용할 열은 수집 후 변환에서 자료형을 맞춥니다.

행 내보내기와 파일 갱신

관계형 행을 쓰려면 Microsoft Excel 커넥터의 테이블 내보내기를 사용합니다. CData 테이블 내보내기는 기존 데이터를 비우지 않는 모드만 지원하며 키 기준 갱신, 삭제와 upsert는 지원하지 않습니다.

파일 전체를 수정하려면 통합 문서가 저장된 저장소의 커넥터를 사용합니다. 해당 소스를 외부 변환이나 외부 함수에 가져오고, 파일 바이트를 다운로드하여 메모리에서 수정한 뒤 같은 위치에 업로드합니다. 인증, 외부 통신, 다운로드와 업로드 호출은 저장소 커넥터가 담당합니다.

업로드 전에 저장소 소스를 다음과 같이 구성합니다.

• Connection settings의 Export configuration에서 Enable exports to this source를 켜고 내보낼 수 있는 보안 표지를 선택합니다.
• 함수에서 업로드한다면 Enable exports to this source without markings validations도 켭니다. 보안 표지 검증을 생략하는 설정이므로 허용된 데이터와 호출 경로를 확인해야 합니다.
• 대상 파일 위치에 쓰기 권한이 있는 인증 정보를 사용합니다. Microsoft Graph 위임 접근은 Files.ReadWrite를 사용할 수 있고, 애플리케이션 접근에는 Files.ReadWrite.All 같은 적절한 애플리케이션 권한과 관리자 동의가 필요합니다.

Python에서 파일 바이트 처리

저장소에서 내려받은 바이트와 워크시트 이름을 다음 함수에 전달합니다. 저장소 연결 로직과 파일 형식 처리 로직을 분리하므로 함수 자체는 외부 파일을 다운로드하거나 업로드하지 않습니다. Python 저장소 의존성에 openpyxl을 추가합니다.

행 읽기

첫 행을 열 이름으로 사용하고 이후의 비어 있지 않은 행을 사전 목록으로 반환합니다. 헤더가 비어 있으면 column_1 같은 이름을 붙입니다. data_only=True는 수식 문자열 대신 마지막으로 저장된 수식 결과를 읽으며 수식을 새로 계산하지 않습니다.

from io import BytesIO
from typing import Any

from openpyxl import load_workbook


def read_worksheet_rows(
    workbook_bytes: bytes,
    worksheet_name: str,
) -> list[dict[str, Any]]:
    workbook = load_workbook(
        BytesIO(workbook_bytes),
        read_only=True,
        data_only=True,
    )
    try:
        worksheet = workbook[worksheet_name]
        rows = worksheet.iter_rows(values_only=True)
        raw_headers = next(rows, None)
        if raw_headers is None:
            return []

        headers = [
            str(header) if header is not None else f"column_{index + 1}"
            for index, header in enumerate(raw_headers)
        ]
        return [
            dict(zip(headers, row))
            for row in rows
            if any(value is not None for value in row)
        ]
    finally:
        workbook.close()

셀 수정

이 함수는 지정한 셀 하나를 수정한 뒤 새 통합 문서 바이트를 반환합니다. 반환값을 원래 위치에 업로드하면 원격 파일 전체를 교체합니다.

from io import BytesIO
from typing import Any

from openpyxl import load_workbook


def update_workbook_cell(
    workbook_bytes: bytes,
    worksheet_name: str,
    cell_reference: str,
    value: Any,
) -> bytes:
    workbook = load_workbook(BytesIO(workbook_bytes))
    try:
        workbook[worksheet_name][cell_reference] = value
        output = BytesIO()
        workbook.save(output)
        return output.getvalue()
    finally:
        workbook.close()

파일 형식과 보존 제약

매크로가 포함된 .xlsm은 드라이버에서 읽기만 지원합니다. 수정 후 업로드하려면 .xlsx 사본을 사용합니다. 이전 .xls 형식은 지원하지 않으며 Excel 2007 이후의 Office Open XML 형식을 읽습니다.

openpyxl은 지원하지 않는 도형 등 일부 통합 문서 기능을 보존하지 못할 수 있습니다. 실제 파일을 교체하기 전에 사본에서 다운로드, 수정과 업로드 전체를 시험하고 필요한 기능이 남아 있는지 확인합니다.