Microsoft Graph로 Excel 리포트 자동화: 세션, 테이블, 차트 이미지

2026년 9월 17일 목요일

5 분 소요

주간 리포트를 만들 때마다 누군가 DB에서 숫자를 뽑아 Excel에 붙여 넣고 차트를 갱신하고 있다면, 그 작업은 Microsoft Graph 실무 입문에서 다룬 도구로 통째로 자동화할 수 있습니다. Graph의 workbook API는 OneDrive와 SharePoint에 있는 Excel 파일을 열지 않고 읽고 쓰는 API입니다. 이 글은 그 핵심인 세션 관리, 테이블 조작, 차트 이미지 추출을 정리합니다. 앱 등록과 인증은 실무 입문 #2를 전제로 합니다.

진입점: 파일 경로 뒤에 /workbook #

workbook API의 URL은 드라이브 아이템 주소 뒤에 /workbook을 붙이는 구조입니다.

요청 예시

GET /me/drive/items/{item-id}/workbook/worksheets
GET /sites/{site-id}/drive/items/{item-id}/workbook/tables

이 뒤로 워크시트, 테이블, 범위(range), 차트, 이름 정의(named item)가 리소스로 매달립니다. 파일 자체의 업로드·다운로드는 실무 입문 #5에서 다룬 드라이브 API의 일이고, workbook API는 열려 있는 통합 문서 내부를 다룹니다.

세션: 성능과 저장 여부를 결정하는 스위치 #

workbook API를 쓸 때 가장 먼저 이해할 것이 세션입니다. 호출 방식이 셋으로 갈립니다.

모드	만드는 법	특징
영속 세션	`createSession`에 `persistChanges: true`	변경이 파일에 저장됨. 가장 효율적, 실무 기본값
비영속 세션	`persistChanges: false`	변경이 임시 사본에만 적용, 세션이 끝나면 소멸
세션 없음	헤더 생략	호출마다 서버가 파일을 다시 찾음. 느림. 단발 호출용

세션 생성

POST /me/drive/items/{item-id}/workbook/createSession
Content-Type: application/json

{ "persistChanges": true }

응답의 세션 ID를 이후 모든 호출에 workbook-session-id 헤더로 넘깁니다. 두 번 이상 호출한다면 세션을 만드는 것이 정답입니다. 서버가 통합 문서를 메모리에 올려 둔 채 연속 처리하므로 호출당 지연이 크게 줄어듭니다.

비영속 세션은 계산기로 쓸 때 빛납니다. 원본 파일에 값을 채워 넣고 수식 결과나 차트만 뽑은 뒤 파일은 원래대로 두고 싶은 경우, persistChanges: false 세션 안에서 작업하면 파일을 건드리지 않고 결과만 가져올 수 있습니다. 템플릿 Excel을 계산 엔진으로 쓰는 패턴입니다.

운영 주의점이 둘 있습니다. 세션은 활동이 없으면 만료됩니다(영속 약 5분, 비영속 약 7분). 만료된 세션으로 호출하면 404가 나므로, 긴 작업은 만료를 전제로 세션 재생성 로직을 넣어야 합니다. 그리고 세션 생성이 오래 걸릴 수 있어 Prefer: respond-async 헤더로 장기 실행 패턴(폴링)을 쓸 수 있고, 간헐적 504는 재시도가 정답입니다.

읽기: usedRange와 테이블 #

시트에서 데이터가 있는 영역만 읽는 가장 간단한 방법은 usedRange입니다.

usedRange 읽기

GET /me/drive/items/{id}/workbook/worksheets/{name}/usedRange

값이나 서식이 있는 최소 사각형 범위가 values(2차원 배열), formulas, text와 함께 돌아옵니다. 특정 영역만 필요하면 range(address='A1:D20')으로 좁힙니다.

그런데 리포트 자동화라면 범위보다 테이블을 기준으로 삼는 것이 훨씬 견고합니다. 범위 주소는 행이 늘면 어긋나지만, 테이블은 이름으로 접근하고 크기가 데이터를 따라 자동으로 늘어나기 때문입니다.

테이블 읽기와 행 추가

GET  /me/drive/items/{id}/workbook/tables                       # 테이블 목록
GET  /me/drive/items/{id}/workbook/tables('SalesTable')/rows    # 행 읽기

POST /me/drive/items/{id}/workbook/tables('SalesTable')/rows
{ "values": [["2026-09-15", "키보드", 12, 348000]] }             # 행 추가

리포트 파이프라인의 기본형이 이것입니다. 원본 데이터는 테이블에 행으로 쌓고, 요약은 테이블을 참조하는 수식·피벗·차트가 알아서 갱신하게 만듭니다. 코드는 행 추가만 책임지고, 집계는 Excel이 합니다.

차트: 만들고, 이미지로 뽑기 #

리포트 자동화의 마무리는 차트입니다. 차트를 추가하고, 이미 있는 차트의 원본 범위를 갱신하고, 무엇보다 이미지로 렌더링해서 받을 수 있습니다.

차트 생성과 이미지 추출

POST /me/drive/items/{id}/workbook/worksheets('Report')/charts/add
{ "type": "ColumnClustered", "sourceData": "A1:B12", "seriesBy": "Auto" }

GET /me/drive/items/{id}/workbook/worksheets('Report')/charts('Chart 1')/image

image 호출은 base64 문자열을 돌려줍니다. 이것을 디코드하면 PNG가 되므로, 메일 본문에 첨부하거나(실무 입문 #4의 메일 전송과 조합) Teams 알림에 넣는 흐름이 코드 몇 줄로 완성됩니다. “Excel을 열어 차트를 캡처하는” 수작업의 대체물입니다. 한 가지 함정은 차트 ID에 {, } 문자가 포함된다는 점입니다. URL에 넣을 때 반드시 인코딩(%7B, %7D)해야 합니다.

권한: Excel API는 위임 중심입니다 #

여기가 이 API의 가장 큰 실무 제약입니다. workbook API의 권한 표를 보면 애플리케이션 권한이 지원되지 않는 엔드포인트가 많습니다(usedRange 등은 위임 Files.ReadWrite만 표기). 사람 없이 도는 데몬 자동화를 앱 권한 하나로 깔끔하게 만들기 어렵다는 뜻입니다.

실무 선택지는 이렇게 정리됩니다.

위임 권한 + 자동화 계정: 전용 계정으로 위임 토큰을 확보해 돌리는 방식입니다. Teams 알림에서도 쓰였던 우회이고(실무 입문 #6), 계정·토큰 수명 관리가 따라옵니다.
데이터 계층에서 해결: 무인 자동화가 목적이라면 Excel을 계산·표현 층으로만 쓰고, 데이터 적재는 앱 권한이 완전한 드라이브 API로 CSV·파일을 올리는 구조로 우회할 수도 있습니다.
엔드포인트별 권한 표 확인: 지원 여부가 엔드포인트마다 다르고 바뀔 수 있으므로, 설계 전에 쓰려는 호출의 문서 권한 표를 확인하는 것이 필수 절차입니다.

정리 #

workbook API는 드라이브 아이템 뒤에 /workbook을 붙여 Excel 내부(시트, 테이블, 범위, 차트)를 다룹니다. 파일 업로드는 드라이브 API의 일입니다.
두 번 이상 호출하면 세션을 만듭니다. persistChanges: true가 실무 기본, false는 파일을 건드리지 않는 계산기 모드입니다. 세션은 몇 분의 비활동으로 만료되므로 재생성 로직이 필요합니다.
리포트 파이프라인은 테이블에 행을 추가하는 구조로 만들고, 집계·차트 갱신은 Excel의 수식에 맡깁니다.
차트는 base64 이미지로 추출해 메일·알림에 바로 넣을 수 있습니다. 차트 ID의 중괄호는 URL 인코딩 필수입니다.
Excel API는 위임 권한 중심이라 무인 자동화 설계 전에 엔드포인트별 권한 표 확인이 필수이고, 자동화 계정 또는 데이터 계층 우회가 현실적 선택지입니다.