Microsoft Graph 실무 입문 #1 Graph란: Microsoft 365 전체를 여는 하나의 API

2026년 7월 15일 수요일

6 분 소요

회사에서 Microsoft 365를 쓴다면, 여러분의 조직에는 이미 방대한 데이터가 한곳에 모여 있습니다. 전 직원의 메일과 캘린더(Outlook), 조직도와 계정(Entra ID), 파일(OneDrive·SharePoint), 대화(Teams)가 전부 여기에 해당합니다. Microsoft Graph는 이 전부를 하나의 API로 여는 문입니다. “매주 월요일 팀 캘린더를 모아 Teams에 요약을 올린다”, “퇴사자 계정의 파일을 자동으로 백업한다”, “보고서를 생성해 메일로 발송한다” 같은 사내 자동화가 전부 이 API 하나로 만들어집니다.

이 시리즈는 7편에 걸쳐 Graph를 실무 자동화의 관점으로 다룹니다. 이번 편에서 전체 지도를 그리고, 2편에서 인증(앱 등록, delegated vs application 권한), 3편에서 Python SDK 첫 호출, 4편에서 메일·캘린더, 5편에서 파일(OneDrive·SharePoint), 6편에서 Teams, 7편에서 운영(스로틀링, 페이지네이션, delta, 변경 알림)을 다룹니다.

하나의 엔드포인트라는 것의 의미 #

Graph 이전의 Microsoft API는 제품마다 따로였습니다. Exchange는 EWS, SharePoint는 자체 REST/CSOM, Entra ID(구 Azure AD)는 또 다른 API를 썼습니다. 제품마다 인증 방식과 SDK가 달라서, “메일을 읽어 SharePoint에 저장"하는 간단한 자동화에도 두 개의 다른 세계를 배워야 했습니다.

Graph는 이것을 하나로 통합했습니다. 모든 요청이 같은 곳으로 갑니다.

Graph의 URL 구조

https://graph.microsoft.com/{버전}/{리소스}

GET https://graph.microsoft.com/v1.0/me                  # 내 프로필
GET https://graph.microsoft.com/v1.0/me/messages         # 내 메일
GET https://graph.microsoft.com/v1.0/me/calendar/events  # 내 일정
GET https://graph.microsoft.com/v1.0/users               # 조직의 사용자 목록
GET https://graph.microsoft.com/v1.0/me/drive/root/children  # 내 OneDrive 루트
GET https://graph.microsoft.com/v1.0/teams/{id}/channels     # 팀의 채널 목록

URL을 읽는 감각이 곧 Graph를 읽는 감각입니다. me는 “인증된 사용자 자신"이고, users/{id}로 바꾸면 다른 사용자를 가리킵니다(권한이 있다면). 리소스는 계층으로 이어집니다. me → drive → root → children처럼 소유 관계를 경로로 따라가는 구조라서, 익숙해지면 문서를 보기 전에 URL을 추측할 수 있을 정도로 일관적입니다.

인증도 하나로 통합됐습니다. 어떤 리소스를 다루든 Entra ID에서 발급한 토큰 하나로 인증하고, 무엇을 할 수 있는지는 토큰에 담긴 권한(scope)이 정합니다. 이 권한 모델이 Graph 학습의 실질적인 관문이라, 2편 전체를 여기에 쓰겠습니다.

v1.0과 beta: 어느 쪽을 쓰는가 #

URL의 버전 자리에는 v1.0과 beta 둘이 옵니다. 규칙은 명확합니다.

v1.0: 정식 지원 버전입니다. 하위 호환이 관리되고, 프로덕션은 여기에만 의존해야 합니다.
beta: 미리보기입니다. 새 기능이 먼저 오지만 예고 없이 바뀌거나 사라질 수 있습니다. 실험과 검증용으로만 쓰고, 운영 코드에 넣지 않는 것이 원칙입니다.

실무에서 흔한 사고는 beta에만 있는 필드를 쓰다가 어느 날 응답 형태가 바뀌어 자동화가 조용히 깨지는 경우입니다. 문서를 볼 때 페이지 상단의 버전 선택이 v1.0인지 항상 확인하는 습관이 필요합니다.

무엇을 할 수 있는가: 리소스 지도 #

Graph가 여는 영역을 실무 자동화의 시나리오로 묶으면 이렇게 됩니다.

영역	대표 리소스	자동화 예시
조직·계정 (Entra ID)	users, groups	입퇴사 처리, 조직도 동기화, 계정 감사
메일 (Outlook)	messages, mailFolders	보고서 발송, 수신함 분류, 첨부 수집
캘린더 (Outlook)	events, calendars	회의실 예약 현황, 팀 일정 집계, 일정 자동 생성
파일 (OneDrive·SharePoint)	drives, driveItems, sites	문서 백업, 산출물 업로드, 공유 링크 생성
협업 (Teams)	teams, channels, chatMessages	알림 발송, 채널 아카이브, 메시지 수집
보안·관리	auditLogs, signIns, reports	로그인 감사, 사용 현황 리포트

한 가지 감각을 미리 잡아 두면 좋습니다. Graph의 힘은 개별 기능이 아니라 이 영역들이 한 토큰, 한 SDK 안에서 조합된다는 데 있습니다. “SharePoint의 명단을 읽어 → 각 사용자의 캘린더를 확인하고 → 결과를 메일로 보내고 → Teams에 요약을 남긴다"가 하나의 스크립트가 됩니다.

OData: 목록을 다루는 공통 문법 #

모든 목록형 리소스에는 OData 쿼리 파라미터라는 공통 문법이 적용됩니다. 어느 리소스에서든 같은 방식으로 동작하므로, 한 번 익히면 전 영역에서 씁니다.

OData 쿼리 예시

# 필요한 필드만 (응답 크기 절감: 실무 기본기)
GET /v1.0/me/messages?$select=subject,from,receivedDateTime

# 조건 필터
GET /v1.0/users?$filter=department eq 'Engineering'

# 정렬 + 개수 제한
GET /v1.0/me/messages?$orderby=receivedDateTime desc&$top=10

# 개수만
GET /v1.0/users/$count

특히 $select는 습관으로 만들 가치가 있습니다. Graph의 기본 응답은 필드가 많아서, 필요한 것만 고르면 응답 크기와 처리 시간이 크게 줄고, 7편에서 다룰 스로틀링 예산도 아낍니다.

Graph Explorer: 코드 없이 오늘 시작하기 #

Graph의 가장 좋은 학습 도구는 Microsoft가 제공하는 웹 콘솔인 Graph Explorer입니다(주소는 aka.ms/ge입니다). 브라우저에서 Graph 요청을 직접 실행해 볼 수 있고, 두 가지 모드가 있습니다.

로그인 없이: 샘플 조직의 가짜 데이터를 상대로 요청을 연습할 수 있습니다. 지금 바로 GET /v1.0/me를 실행해 볼 수 있다는 뜻입니다.
회사 계정으로 로그인: 자기 계정의 실제 데이터로 실행됩니다. 요청마다 어떤 권한이 필요한지 알려 주고 그 자리에서 동의(consent)할 수 있어서, 2편에서 다룰 권한 개념을 손으로 익히는 데 최적입니다.

Explorer에는 또 하나 실무적인 쓸모가 있습니다. 우측의 코드 스니펫 탭이 지금 실행한 요청을 각 언어 SDK 코드로 바꿔 줍니다. “Explorer에서 요청을 완성하고 → 코드로 옮긴다"는 이 시리즈 전체에서 반복할 작업 흐름입니다.

어떤 것이 Graph가 아닌가: 경계선 #

기대를 정확히 잡기 위해 경계도 짚어 둡니다.

Azure 리소스 관리는 Graph가 아닙니다. VM을 만들고 스토리지를 관리하는 것은 Azure Resource Manager(ARM) API의 영역입니다. Graph는 Microsoft 365와 Entra ID의 데이터를 다룹니다.
Power Automate와의 관계: 노코드 자동화 도구인 Power Automate의 커넥터들도 내부적으로는 상당 부분 Graph를 호출합니다. 클릭 몇 번으로 되는 단순 흐름은 Power Automate가 빠르고, 조건이 복잡하거나 기존 시스템과 엮이거나 버전 관리가 필요한 자동화는 Graph 직접 호출이 맞습니다. 이 시리즈는 후자를 다룹니다.
온프레미스 Exchange·SharePoint 서버는 대상이 아닙니다. Graph는 클라우드(Microsoft 365)의 API입니다.

정리 #

Microsoft Graph는 메일, 캘린더, 파일, Teams, 조직 데이터까지 Microsoft 365 전체를 graph.microsoft.com 하나로 여는 통합 API입니다. 인증도 Entra ID 토큰 하나로 통일돼 있습니다.
프로덕션은 v1.0만 씁니다. beta는 예고 없이 바뀌는 미리보기입니다.
URL은 me, users/{id}, 소유 관계의 계층 경로로 읽고, 목록은 OData($select, $filter, $top)라는 공통 문법으로 다룹니다. $select는 습관으로 삼는 것이 좋습니다.
Graph Explorer로 코드 없이 오늘 시작할 수 있고, 완성한 요청을 SDK 코드로 바꿔 주는 스니펫 탭이 실무 작업 흐름의 출발점입니다.
Graph의 힘은 영역들의 조합입니다. 명단을 읽고, 일정을 확인하고, 메일을 보내고, Teams에 남기는 것이 한 스크립트가 됩니다.

다음 편은 이 전부의 관문인 인증입니다. Entra ID 앱 등록부터 delegated와 application 권한의 차이, 관리자 동의까지 다룹니다. 시리즈에서 가장 중요한 편입니다.