대량 스크립트에서 Microsoft Graph가 429 Too Many Requests를 반환할 때 변경해야 할 사항
By Mirko Peters ·
Graph 스크립트가 요청 간격을 10초에 한 번으로 늦춰도 속도가 크게 떨어지거나 429로 실패합니다. 비용이 큰 속성과 공유 할당량이 왜 중요한지, 그리고 대기 후 재시도하고 호출을 나누고 안전하게 일괄 처리하는 방법을 알아봅니다.
Automatically translated with AI from the original post. Read the English original
스크립트가 Microsoft Graph에서 사용자 데이터를 한 명씩 읽으면서 느리고 신중한 속도를 유지하고 있습니다. 그런데도 429 Too Many Requests를 받습니다. 2026년 5월 Microsoft Q&A 스레드가 정확히 이런 상황을 설명합니다. 사용자 한 명을 조회하는 호출에 signInActivity가 포함된 긴 $select 목록과 $expand=manager가 함께 쓰이고, 클라이언트는 10초에 한 요청을 보내며 동시에 진행 중인 요청은 하나만 두는 구성입니다.
핵심 포인트
- 고정된 요청 속도만으로는 보호되지 않습니다. 제한은 요청 유형, 앱, 테넌트에 따라 달라집니다. Learn은 GET signInActivity를 분당 10개 요청으로 명시합니다.
- 응답 헤더 Retry-After에 지정된 초만큼 기다린 뒤 재시도하십시오. Learn에 따르면 스로틀링을 받는 동안에도 Graph는 사용량을 계속 기록하므로, 즉시 재시도하면 상황이 더 나빠집니다.
- 비용이 큰 속성을 사용자별 호출에서 분리하고, 더 큰 $top으로 페이징하며, delta 쿼리나 변경 알림을 사용하면 요청 수를 줄일 수 있습니다.
- $batch 호출에서는 각 요청이 개별적으로 평가됩니다. 배치 자체는 200을 반환하더라도 그 안의 개별 요청이 429로 실패할 수 있으며, 이들은 자동으로 재시도되지 않습니다.
2026년 2월의 두 번째 스레드는 여러 SharePoint 및 OneDrive 드라이브를 병렬로 읽을 때 스로틀링이 어떻게 동작하는지 물었습니다. 두 스레드를 종합하면 클라이언트 쪽의 단순한 속도 제한만으로는 충분하지 않다는 것을 알 수 있습니다. 이 글은 Microsoft Learn이 문서화한 내용과 스레드에서 제안된 내용을 구분하여 설명합니다. 이 글은 문제 해결 가이드이며, Microsoft의 공식 절차가 아닙니다.
스레드에서 보고된 내용
2026년 5월 스레드(users 엔드포인트). 질문자는 많은 속성을 요청하면서 GET /v1.0/users/{id}를 호출했고, 여기에는 signInActivity가 포함되어 있었으며, $expand=manager도 함께 사용했습니다. 호출마다 사용자 한 명만 반환되었기 때문에 페이징과 필터로는 문제를 해결할 수 없었습니다. Microsoft 중재자는 쓰로틀링을 일으키는 원인이 요청 빈도만이 아니라 비용이 많이 드는 속성이라고 답변했습니다. 중재자는 호출을 프로필, 로그인 활동, 관리자로 나누고, Retry-After를 따르면서 지수 백오프를 적용하고, 캐싱을 사용하며, 로그인 활동은 덜 자주 읽으라고 제안했습니다. 이 답변은 채택됨으로 표시되지 않았습니다. 질문자가 채택됨으로 표시한 AI 생성 답변도 대체로 같은 내용이었습니다. 질문자는 429 오류가 멈췄는지 밝히지 않았습니다.
2026년 2월 스레드 (driveItems). 질문자는 스로틀링이 사이트 단위로 적용되는지 드라이브 단위로 적용되는지, 그리고 동시 요청을 어느 정도까지 안전하게 보낼 수 있는지 알고 싶어 했습니다. 익명 답변이 달렸고 질문자는 이를 채택했습니다. 답변의 요지는 제한이 테넌트, 앱, 서비스 단위로 여러 겹으로 적용되며, 서로 다른 사이트에 대한 요청도 같은 할당량을 공유할 수 있다는 것입니다. 또한 Retry-After를 준수하고, $batch를 사용하며, 폴링보다 델타 쿼리와 변경 알림을 우선하라고 권장했습니다. 동시성 숫자는 제시되지 않았습니다. 질문자는 도움이 되었다고 밝혔습니다.
1단계: 429 응답을 제대로 읽기
실패할 때마다 요청 URL, Retry-After 값, 발생 시각 세 가지를 기록하세요. Learn의 Graph PowerShell 문제 해결 페이지에서는 -Debug와 함께 cmdlet을 실행하면 HTTP 메서드, URI, 상태 코드를 확인할 수 있다고 안내하며, 지원 티켓을 열 경우 응답 헤더의 request-id와 date를 기록하라고 권장합니다.
2026년 5월 스레드에서는 Retry-After 값이 인용되지 않았습니다. 이 값이 없으면 스크립트가 어떤 제한에 걸렸는지 아무도 판단할 수 없습니다.
2단계: Retry-After 준수하기
Learn의 스로틀링 페이지는 이 부분을 명확하게 설명합니다.
Retry-After헤더에 지정된 초만큼 기다리세요.- 요청을 다시 시도합니다.
- 다시 429가 발생하면 성공할 때까지 같은 지연 시간을 유지하세요.
Learn은 그 이유도 설명합니다. Microsoft Graph는 클라이언트가 스로틀링을 받는 동안에도 리소스 사용량을 계속 기록하므로, 헤더에 따라 대기하는 것이 가장 빠르게 회복하는 방법입니다. 즉시 재시도하면 사용량만 늘어납니다. 응답에 Retry-After 헤더가 없으면 Learn은 지수 백오프를 권장합니다.
Learn은 Microsoft Graph SDK가 이미 이를 처리한다고 설명합니다. 하지만 Graph PowerShell cmdlet에 대해서는 같은 내용을 언급하지 않으므로 그렇다고 가정해서는 안 됩니다. Invoke-MgGraphRequest처럼 원시 호출을 감싸는 스크립트라면 대기 로직을 직접 구현하세요.
3단계: 비용이 큰 호출 찾기
Learn의 서비스별 제한 페이지에는 ID 및 액세스 보고서 섹션이 있습니다. 이 페이지는 변경될 수 있는 다음 수치를 제시합니다.
- 이 그룹의 모든 요청: 앱당 모든 테넌트에 걸쳐 10초당 122개 요청, 그리고 앱당 테넌트별로 10초당 5개 요청입니다.
GET signInActivity: 분당 10개 요청입니다.
10초마다 한 번씩 실행되는 스크립트는 분당 6회 호출하므로 문서상으로는 10회 미만입니다. 다만 스레드에서는 같은 앱 등록을 사용하는 다른 작업이 동시에 실행되었는지 언급하지 않습니다. 제한이 앱 단위와 테넌트 단위로 적용되므로, 이러한 작업들은 같은 할당량을 공유하게 됩니다. 이 내용은 스레드에서 직접 언급된 것이 아니라 Learn의 제한 표를 바탕으로 한 결론입니다.
Learn은 또한 List users에서 $select=signInActivity를 사용하면 일반 호출보다 더 엄격한 스로틀링이 발생할 수 있다고 설명합니다. 권장 사항은 다음과 같습니다.
signInActivity를 선택할 때 최대 페이지 크기인$top=500을 기본값 100 대신 사용하세요.createdDateTime에$filter를 사용해 더 짧은 기간의 데이터를 조회하세요. 약 3일 분량으로 시작하고, 스로틀링이 발생하면 기간을 좁히세요.- Learn의 List users 페이지에 따르면
signInActivity속성에는 Microsoft Entra ID P1 또는 P2 라이선스와AuditLog.Read.All권한이 필요합니다.
많은 사용자의 로그인 활동이 필요하다면, GET /v1.0/users?$select=displayName,userPrincipalName,signInActivity&$top=500과 같은 목록 호출을 사용하면 요청당 최대 500명의 사용자를 가져올 수 있습니다. 사용자마다 한 번씩 호출하는 것보다 요청 수가 훨씬 적습니다. Learn의 List users 페이지에는 signInActivity를 포함한 이 요청이 문서화되어 있습니다. 서비스 측 부하가 더 가벼운지는 명시되어 있지 않으므로 직접 측정해 보세요.
5월 스레드의 진행자는 beta 엔드포인트에서 signInActivity를 읽으라고 제안했습니다. 그러나 Learn의 현재 v1.0 참조 문서에는 signInActivity가 나와 있으므로, 이 용도로 beta가 필요하지는 않을 것입니다. 사용하는 엔드포인트에서 해당 속성을 직접 확인하세요.
4단계: 요청 수 줄이기
Learn의 모범 사례도 같은 방향을 가리킵니다.
- 요청당 작업 수와 호출 빈도를 줄이세요.
- 지속적인 폴링과 대규모 컬렉션에 대한 주기적 스캔을 피하세요. 가능한 경우 변경 추적(델타 쿼리)과 변경 알림을 사용하세요.
- 상사 관계처럼 자주 바뀌지 않는 데이터는 캐시하세요. 이는 5월 스레드 진행자의 조언이며, Learn의 공식 설명은 아닙니다.
5단계: $batch를 신중하게 사용하기
일괄 처리는 네트워크 왕복 횟수를 줄일 수 있습니다. Learn의 JSON 일괄 처리 페이지는 일괄 요청당 개별 요청을 20개로 제한합니다. 또한 다음과 같이 설명합니다.
- 배치의 각 요청은 스로틀링 제한과 개별적으로 비교되어 평가됩니다. 어떤 요청이 제한을 초과하면 그 요청만 429로 실패하고, 배치 자체는 200을 반환합니다. 한 배치에서 여러 요청이 동시에 스로틀링될 수 있습니다.
- 실패한 각 요청은 해당 요청의 응답 본문에 있는
retry-after값을 사용해 재시도합니다. Learn에서는 가장 긴retry-after값이 지난 뒤 새 배치로 모든 요청을 다시 보낼 수도 있다고 설명합니다. - SDK가 배치로 묶이지 않은 요청에 대해서는 스로틀링된 요청을 자동으로 재시도하더라도, 배치 안에서 스로틀링된 요청은 자동으로 재시도되지 않습니다.
따라서 배치 처리를 한다고 해서 제한이 사라지는 것은 아닙니다. 재시도 로직이 코드 쪽으로 옮겨질 뿐입니다.
6단계: SharePoint 및 OneDrive 읽기 계획
드라이브 스캔과 관련해 Learn의 SharePoint 스로틀링 문서에서는 SharePoint Online이 Retry-After 헤더와 함께 429 또는 503을 반환하며, 스로틀링된 요청도 제한에 포함된다고 설명합니다. 이 문서는 사용자, 테넌트, 애플리케이션 범위의 스로틀링을 다루며, 사이트별 제한은 익명 링크와 익명 이그레스에 대한 것뿐입니다. 따라서 사이트마다 별도의 할당량이 있다고 가정하고 계획을 세우지 않는 것이 좋습니다. 그 페이지의 다른 내용은 다음과 같습니다:
- 앱 ID와 User-Agent 문자열이 모두 없는 트래픽은 꾸며지지 않은(undecorated) 트래픽입니다. Learn에 따르면 잘 식별된 트래픽이 꾸며지지 않은 트래픽보다 우선 처리됩니다. 문서에 나온 User-Agent 형식은
ISV|CompanyName|AppName/Version과NONISV|CompanyName|AppName/Version입니다. - 단일 항목 쿼리는 리소스 단위 1, 여러 항목 쿼리나 쓰기 작업은 2가 소요됩니다.
$expand=permissions를 포함한 권한 작업은 5가 소요됩니다. 대량 스캔에서는 권한 확장을 피하는 것이 좋습니다. - Learn은 가능한 경우 CSOM과 REST 대신 Microsoft Graph를 사용할 것을 권장합니다. 일반적으로 리소스를 더 적게 사용하기 때문입니다.
2월 스레드에서는 델타 쿼리의 410 Gone 응답도 다루었습니다. 그 스레드의 답변에 따르면 이는 델타 토큰을 더 이상 사용할 수 없다는 뜻이며, 클라이언트는 새 초기 델타 쿼리로 다시 시작해야 합니다. 증분 동기화를 구현할 때는 이 경우에 대비해 두어야 합니다.
확인
- 변경 전후 한 번의 실행에 대해 429 응답 수와
Retry-After값을 기록하는 것이 좋습니다. - 같은 앱 등록을 사용하는 다른 작업 없이 스크립트만 단독으로 실행해, 내 호출이 미치는 영향만 확인하는 것이 좋습니다.
- 백오프를 올바르게 적용하고 호출 수를 줄였는데도 스로틀링이 계속되면
request-id와date헤더를 수집해 지원 사례를 여는 것이 좋습니다.
제한
- 2026년 5월 스레드는 확정된 결과가 없으며, 그 스레드의 채택된 답변은 AI가 생성한 것이었습니다. 여기서는 위의 Learn 지침을 근거로 사용합니다.
- 스레드에서는
signInActivity블록이 없는 사용자에 관한 질문에 답이 나오지 않았습니다. Learn에도 이에 대한 설명이 없으므로, 블록이 없는 경우는 알 수 없는 상태로 취급해야 합니다. 다만 Learn에 따르면lastSuccessfulSignInDateTime은 2023년 12월 1일 이전까지 소급해서 채워지지 않으므로, 값이 비어 있다고 해서 그 사용자가 한 번도 로그인하지 않았다는 뜻은 아닙니다. - Learn에 나온 제한 값은 변경될 수 있다고 명시되어 있습니다. 숫자를 기준으로 구현하기 전에 최신 페이지를 확인하는 것이 좋습니다.
관련 링크
데이터 원본
- Microsoft Learn: Microsoft Graph 스로틀링 지침
- Microsoft Learn: Microsoft Graph 서비스별 스로틀링 제한
- Microsoft Learn: JSON 배치를 사용해 여러 요청 결합
- Microsoft Learn: 사용자 나열
- Microsoft Learn: signInActivity 리소스 형식
- Microsoft Learn: SharePoint Online에서 스로틀링 또는 차단 방지
- Microsoft Learn: Microsoft Graph PowerShell의 일반적인 오류 문제 해결
- Microsoft Q&A: users 엔드포인트의 스로틀링 문제 (2026년 5월)
- Microsoft Q&A: driveItems를 병렬로 처리할 때의 Microsoft Graph 스로틀링 동작 (2026년 2월)