Microsoft Graph SDK를 사용하는 이유

개발자 프록시가 애플리케이션이 SDK를 사용하지 않고 Microsoft Graph API 요청을 만드는 것을 감지하면 SDK로 마이그레이션하는 것이 좋습니다. 이 지침은 Microsoft Graph SDK가 Microsoft Graph API 작업을 크게 간소화하고 보다 강력한 애플리케이션을 빌드하는 데 도움이 되므로 존재합니다.

Microsoft Graph SDK의 이점

Microsoft Graph SDK는 원시 HTTP 호출보다 많은 이점을 제공합니다.

기본 제공 인증 처리

SDK는 MSAL(Microsoft 인증 라이브러리) 같은 인증 라이브러리와 통합되어 토큰 획득, 새로 고침 및 관리를 자동으로 처리합니다. OAuth 2.0 흐름을 수동으로 구현하거나 토큰 만료에 대해 걱정할 필요가 없습니다.

제한에 대한 자동 재시도 논리

Microsoft 365 서비스는 서비스 안정성을 보장하기 위해 제한을 구현합니다. 애플리케이션이 429 Too Many Requests 응답을 받으면, Microsoft Graph가 반환하는 Retry-After 헤더를 준수하며 적절한 백오프 지연을 활용해 SDK가 재시도를 자동으로 처리합니다.

적절한 페이지 매김 처리

많은 Microsoft Graph 엔드포인트는 페이지를 매긴 결과를 반환합니다. SDK는 후속 페이지 가져오기를 투명하게 처리하는 기본 제공 반복기를 제공하므로 값을 수동으로 추적하고 @odata.nextLink 다른 요청을 수행할 필요가 없습니다.

형식 안전성 및 IntelliSense

SDK는 요청 및 응답에 강력한 형식의 모델을 제공하여 IDE에서 IntelliSense 지원을 제공합니다. 형식 모델은 런타임이 아닌 컴파일 시간에 문제를 catch하여 오류를 줄이고 개발 속도를 향상시킵니다.

일괄 처리 지원

SDK는 여러 요청을 단일 HTTP 호출로 일괄 처리 하여 네트워크 오버헤드를 줄이고 성능을 향상시킬 수 있습니다. 일괄 처리는 개별 요청 수를 줄여 제한 제한 내에서 유지하는 데도 도움이 됩니다.

델타 쿼리

SDK는 마지막 요청 이후 데이터 변경 내용을 효율적으로 동기화할 수 있는 델타 쿼리 구현을 간소화합니다. 델타 쿼리를 사용하는 것은 Microsoft 365 데이터와 동기화 상태를 유지해야 하는 반응형 애플리케이션을 빌드하는 데 중요합니다.

사용자 지정을 위한 미들웨어 아키텍처

SDK는 사용자 지정 가능한 미들웨어 파이프라인을 사용하여 로깅을 추가하거나, 헤더를 수정하거나, 사용자 지정 재시도 정책을 구현하거나, 애플리케이션 코드를 변경하지 않고 다른 동작을 삽입합니다.

일관된 API 패턴

SDK는 다양한 플랫폼 및 언어에서 일관된 패턴을 제공하므로 팀 구성원과 프로젝트 간에 지식을 더 쉽게 공유할 수 있습니다.

원시 HTTP 호출이 놓치는 것

Microsoft Graph에 원시 HTTP를 호출하는 경우 몇 가지 중요한 기능을 직접 구현해야 합니다.

수동 재시도 논리 구현

SDK가 없으면 다음을 포함하여 처리를 위한 재시도 논리를 429 responses구현해야 합니다.

• Retry-After 헤더 값 구문 분석
• 지수 백오프 구현
• 다양한 오류 시나리오 처리
• 고부하 시 재시도 폭주 방지

수동 페이지 매김 처리

다음을 수행해야 합니다.

• 모든 응답에서 @odata.nextLink를 확인하십시오.
• 각 페이지에 대해 더 많은 요청 만들기
• 페이지 간 결과 집계
• 페이지 매김 중 부분 오류 처리

오류 처리 상용구

Microsoft Graph는 다양한 구조로 다양한 오류 응답을 반환할 수 있습니다. SDK가 없으면 다음을 수행해야 합니다.

• 오류 응답 본문 파싱
• 다른 HTTP 상태 코드를 적절하게 처리
• 로깅에 대한 의미 있는 오류 메시지 추출
• 예기치 않은 오류에 대한 대체 동작 구현

인증 복잡성

인증을 수동으로 관리하려면 다음이 필요합니다.

• OAuth 2.0 흐름 구현
• 토큰 저장 및 보안
• 만료 전 토큰 새로 고침 처리
• 다양한 인증 시나리오 관리(위임된 권한 및 애플리케이션 권한)

사용 가능한 SDK

Microsoft는 다음 플랫폼에 대한 공식 SDK를 제공합니다.

SDK 사용에 대한 대안

SDK는 대부분의 시나리오에 권장되지만 다른 방법이 더 적합할 수 있는 경우가 있습니다.

Kiota에서 생성된 클라이언트

애플리케이션이 Microsoft Graph API의 작은 하위 집합만 사용하는 경우 전체 SDK를 사용하는 대신 Kiota를 사용하여 클라이언트를 생성하는 것이 좋습니다. Kiota는 필요한 특정 API에 맞게 조정된 가볍고 강력한 형식의 클라이언트를 생성하여 종속성 공간을 줄이면서 형식 안전성 및 요청 빌드를 제공합니다.

최소 API 사용량

몇 가지 API 호출만 하는 빠른 스크립트 또는 도구를 작성하는 경우 SDK 설정의 오버헤드가 정당화되지 않을 수 있습니다. 이러한 경우 직접 HTTP 호출이 더 간단할 수 있습니다. 그러나 인증 및 오류 응답을 직접 처리해야 하므로 간단한 스크립트에서도 복잡성을 빠르게 추가할 수 있습니다.

지원되지 않는 언어

공식 SDK가 없는 프로그래밍 언어를 사용하는 경우 직접 HTTP 호출을 수행해야 합니다. Kiota에서 지원하는 경우 키오타를 사용하여 언어에 대한 클라이언트를 생성하는 것도 고려할 수 있습니다.

SDK가 아직 특정 기능을 지원하지 않는 경우

Microsoft Graph는 새로운 기능을 지속적으로 추가합니다. 경우에 따라 새 API 또는 기능에 SDK에 흐름 API가 즉시 없을 수 있습니다. 대부분의 경우 SDK를 사용하여 경로 문자열을 사용하여 임의 요청을 수행할 수 있습니다. 그러면 형식화된 요청 작성기 없이도 SDK 미들웨어(인증, 재시도, 로깅)의 이점을 얻을 수 있습니다. SDK가 요청을 전혀 지원하지 않는 경우 SDK 지원이 추가될 때까지 직접 HTTP 호출로 대체될 수 있습니다.

성능에 민감한 환경

콜드 시작 시간과 패키지 크기가 중요한 서버리스 함수 또는 에지 컴퓨팅과 같은 시나리오에서는 Kiota에서 생성된 클라이언트 또는 직접 HTTP 호출을 사용하는 더 가벼운 접근 방식이 더 적합할 수 있습니다.

다음 단계:

Microsoft Graph SDK를 사용하도록 애플리케이션을 업데이트하는 방법을 알아봅니다.

관련 콘텐츠

• Microsoft Graph SDK 개요
• Microsoft Graph 인증 공급자 선택
• Microsoft Graph SDK 설치
• Microsoft Graph 작업에 대한 모범 사례