Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

사용량 한도

Google Calendar API에는 모든 사용자가 공정하게 사용할 수 있도록 할당량이 있습니다. Calendar API를 사용할 때 고려해야 할 세 가지 중요한 제한사항이 있습니다.

API 사용량 할당량: 프로젝트별 및 사용자별로 적용됩니다. 자세한 내용은 Calendar API 사용 할당량 유형을 참고하세요.
일반 Google Calendar 사용량 한도: Google Calendar API는 Google Workspace 시스템의 전반적인 성능을 보호하기 위해 제한사항이 있는 공유 서비스입니다. 자세한 내용은 Calendar 사용 한도 방지를 참고하세요.
운영 한도: 이러한 한도는 언제든지 제한될 수 있습니다. 예를 들어 단일 캘린더에 연속으로 빠르게 쓰기를 시도하는 경우입니다.

Calendar API 할당량

두 가지 유형의 할당량이 적용됩니다.

프로젝트별 분당: Google Cloud 프로젝트에서 1분 동안 수행할 수 있는 요청 수입니다.
프로젝트별 사용자별 분당: 특정 사용자가 Cloud 프로젝트에서 수행할 수 있는 요청 수입니다. 이 한도는 사용자 간에 사용량을 공정하게 분배하는 데 도움이 됩니다.

할당량은 슬라이딩 윈도우를 사용하여 분 단위로 계산됩니다. 1분 동안 분당 할당량을 초과하는 트래픽이 급증하면 다음 기간 동안 비율 제한이 적용되어 평균적으로 사용량이 할당량 내로 유지됩니다.

다음 표에서는 이러한 한도를 자세히 설명합니다.

사용량 한도 유형	한도
프로젝트별 분당	요청 10,000개
프로젝트별 사용자별 분당	요청 600개

일일 청구 기준액

이 프로젝트별 일일 한도는 요금이 청구되기 전에 Google Cloud 프로젝트에서 24시간 동안 사용할 수 있는 최대 요청 수를 정의합니다.

이 기준점 미만의 사용량에는 추가 요금이 부과되지 않으며 Google Cloud 계정에 요금이 청구되지 않습니다. 전체 결제 세부정보는 2026년 후반에 공유되며, 변경사항이 적용되기 최소 90일 전에 고지됩니다.

이 일일 기준점 한도의 상향 조정은 요청할 수 없습니다.

다음 표에는 한도가 자세히 나와 있습니다.

기준액 한도 유형	한도
프로젝트당 일일	요청 1,000,000개

자세한 내용은 에이전트 도구 및 API를 위한 Google Workspace 표준화 모델을 참고하세요.

시간 기반 할당량 오류 해결

모든 시간 기반 오류(X분당 최대 N개 요청)의 경우 코드가 예외를 포착하고 잘린 지수 백오프를 사용하여 기기에서 과도한 부하를 생성하지 않도록 하는 것이 좋습니다.

지수 백오프는 네트워크 애플리케이션의 표준 오류 처리 전략입니다. 지수 백오프 알고리즘은 요청 간 대기 시간을 기하급수적으로 늘려 최대 백오프 시간까지 요청을 재시도합니다. 요청이 여전히 실패하면 요청이 성공할 때까지 요청 간 지연 시간이 시간이 지남에 따라 증가하는 것이 중요합니다.

예시 알고리즘

지수 백오프 알고리즘이 재시도 간 대기 시간을 최대 백오프 시간까지 늘려서 기하급수적으로 요청을 재시도합니다. 예를 들면 다음과 같습니다.

Google Calendar API에 요청을 전송합니다.
요청이 실패하면 1초 + random_number_milliseconds를 대기한 후 요청을 재시도합니다.
요청이 실패하면 2초 + random_number_milliseconds를 대기한 후 요청을 재시도합니다.
요청이 실패하면 4초 + random_number_milliseconds를 대기한 후 요청을 재시도합니다.
maximum_backoff 시간까지 이를 반복합니다.
최대 재시도 횟수까지 대기 후 재시도 과정을 반복하지만 재시도 간 대기 시간을 늘리지는 않습니다.

각 항목의 의미는 다음과 같습니다.

대기 시간은 min(((2^n)+random_number_milliseconds), maximum_backoff)이고, n은 반복(요청)할 때마다 1씩 증가합니다.
random_number_milliseconds는 1,000밀리초 이하의 랜덤 숫자입니다. 이렇게 하면 많은 클라이언트가 특정 상황에 의해 동기화되고 모두 한 번에 재시도되어 일련의 동기화된 작업으로 요청을 보내는 상황을 피하는 데 도움이 됩니다. random_number_milliseconds 값은 각 재시도 요청 후 다시 계산됩니다.
maximum_backoff는 일반적으로 32 또는 64초입니다. 적절한 값은 사용 사례에 따라 다릅니다.

클라이언트는 maximum_backoff 시간에 도달한 후 재시도를 계속할 수 있습니다. 이후 재시도는 백오프 시간을 계속 늘릴 필요가 없습니다. 예를 들어 클라이언트에 64초에 해당하는 maximum_backoff 시간이 사용되는 경우 이 값에 도달한 후 클라이언트가 64초마다 재시도할 수 있습니다. 특정 시점에서 클라이언트가 무한정 재시도하지 못하게 해야 합니다.

재시도 간 대기 시간과 재시도 횟수는 사용 사례 및 네트워크 조건에 따라 달라집니다.

가격 책정

Google Calendar API의 모든 표준 사용은 추가 비용 없이 제공됩니다. 할당량 요청 한도를 초과하면 2026년 후반에 Google Cloud 결제 계정에 요금이 청구될 예정입니다. 자세한 내용은 에이전트 도구 및 API를 위한 Google Workspace 표준화 모델을 참조하세요.

할당량 상향 조정 요청

프로젝트의 리소스 사용량에 따라 할당량 조정을 요청할 수 있습니다. 서비스 계정의 API 호출은 단일 계정을 사용하는 것으로 간주됩니다. 할당량 조정을 신청해도 승인된다고 보장할 수 없습니다. 할당량 값을 크게 늘리는 할당량 조정 요청은 승인되는 데 시간이 더 오래 걸릴 수 있습니다.

모든 프로젝트의 할당량이 동일하지는 않습니다. 시간이 지남에 따라 Google Cloud 사용량이 증가하면 할당량 값을 늘려야 할 수 있습니다. 앞으로 사용량이 현저하게 늘어날 것으로 예상되는 경우 Google Cloud 콘솔의 할당량 및 시스템 한도 페이지에서 사전에 할당량 조정을 요청할 수 있습니다.

자세한 내용은 다음 리소스를 참조하세요.

문제 해결

할당량 중 하나를 초과하면 비율이 제한되고 쿼리에 대한 응답으로 403 usageLimits 상태 코드 또는 429 usageLimits 상태 코드가 수신됩니다.

이러한 경우 다음을 시도해 보세요.

지수 백오프를 사용하고, 트래픽 패턴을 무작위화하고, 푸시 알림을 사용하는 등 모든 권장사항을 따르세요.
프로젝트가 성장하고 사용자가 많아지면 할당량 증가를 요청할 수 있습니다.
사용자당 할당량 한도에 도달하면 다음을 수행할 수 있습니다.
- 서비스 계정을 사용하는 경우 사용자에게 부하를 할당하거나 여러 서비스 계정 간에 분할합니다.
- 사용자당 할당량 상향 조정을 요청할 수 있지만 일반적으로 기본값 이상으로 상향 조정하는 것은 권장되지 않습니다. 애플리케이션이 일반 캘린더 사용량 한도 또는 운영 한도와 같은 다른 유형의 한도에 도달할 수 있기 때문입니다.
프로덕션 프로젝트와 구성이 유사한 별도의 테스트 전용 프로젝트를 등록하여 할당량 한도를 테스트합니다. 자세한 내용은 할당량 한도 처리 테스트를 참조하세요.

트래픽 패턴 무작위화

Calendar 클라이언트는 여러 클라이언트가 동시에 작업을 수행하여 발생하는 급증하는 트래픽 패턴에 취약합니다. 예를 들어 Calendar 클라이언트의 일반적인 잘못된 관행은 자정에 전체 동기화를 실행하는 것입니다. 이렇게 하면 분당 할당량을 초과할 가능성이 높으며 비율 제한 및 백오프가 발생합니다.

이를 방지하려면 가능하면 하루 동안 트래픽이 분산되도록 해야 합니다. 클라이언트가 매일 동기화를 수행해야 하는 경우 클라이언트가 임의의 시간(클라이언트마다 다름)을 결정하도록 합니다. 정기적으로 작업을 실행해야 하는 경우 간격을 +/- 25%로 변경합니다. 이렇게 하면 트래픽이 더 고르게 분산되고 훨씬 더 나은 사용자 환경이 제공됩니다.

푸시 알림 사용

일반적인 사용 사례는 사용자의 캘린더에서 변경사항이 있을 때마다 작업을 실행하는 것입니다. 여기서 안티패턴은 관심 있는 모든 캘린더를 반복적으로 폴링하는 것입니다. 이렇게 하면 할당량이 매우 빠르게 소진됩니다. 예를 들어 애플리케이션에 사용자가 5,000명이고 각 사용자의 캘린더를 1분에 한 번씩 폴링하는 경우 작업을 수행하기 전에도 분당 할당량이 최소 5,000개 필요합니다.

서버 측 애플리케이션은 푸시 알림을 등록할 수 있으므로 관심 있는 이벤트가 발생할 때 알림을 받을 수 있습니다. 설정하는 데 더 많은 작업이 필요하지만 할당량을 훨씬 더 효율적으로 사용할 수 있고 더 나은 사용자 환경을 제공합니다. 알림을 받을 eventType를 지정해야 합니다. 자세한 내용은 푸시 알림을 참조하세요.

서비스 계정의 적절한 할당

애플리케이션이 도메인 전체 위임을 사용하여 요청을 수행하는 경우 기본적으로 가장하는 사용자가 아닌 서비스 계정에 '프로젝트당 사용자당 분당' 할당량이 청구됩니다. 즉, 서비스 계정이 여러 사용자의 캘린더에서 작동할 수 있지만 할당량이 소진되어 비율 제한이 적용될 수 있습니다.

quotaUser URL 매개변수(또는 x-goog-quota-user HTTP 헤더)를 사용하여 각 고유 사용자를 고유하게 식별하는 임의의 문자열(최대 40자)을 지정하면 이 문제를 방지할 수 있습니다. Calendar API는 할당량 계산에만 이 값을 사용합니다.

quotaUser를 사용하여 여러 사용자에게 사용자별 비율 제한을 적용하려면 요청이 다음 요구사항을 충족해야 합니다.

IP 제한 API 키 포함: key 쿼리 매개변수에 API 키를 전달하고 백엔드 서버의 공개 IP 주소를 지정하는 IP 주소 제한으로 해당 키를 구성합니다. API 키를 생략하거나 IP 주소 제한을 구성하지 않으면 Calendar API는 quotaUser를 무시하고 인증된 계정(예: 서비스 계정)에 할당량을 청구합니다.
X-Goog-User-Project 헤더 생략: quotaUser를 사용하는 요청에 X-Goog-User-Project HTTP 헤더를 전송하지 않습니다. 사용자 프로젝트를 제공하면 할당량 기여 분석을 위한 API 키가 재정의되므로 Calendar API는 quotaUser를 무시합니다.

자세한 내용은 사용자당 요청 제한을 참조하세요.

할당량 한도 처리 테스트

애플리케이션이 실제로 할당량 한도에 도달하는 상황을 적절하게 처리할 수 있는지 확인하고(예: 지수 백오프를 사용한 재시도) 사용자에게 발생할 수 있는 잠재적인 방해를 최소화하려면 실제 환경에서 시나리오를 테스트하는 것이 좋습니다.

실제 애플리케이션 사용에 지장을 주지 않고 테스트하려면 Google Cloud 콘솔에 별도의 테스트 전용 프로젝트를 등록한 다음 프로덕션 프로젝트와 유사한 방식으로 OAuth 동의 화면을 구성하는 것이 좋습니다. 그런 다음 이 프로젝트에 대해 인위적으로 낮은 할당량 한도를 설정하고 애플리케이션의 동작을 관찰할 수 있습니다.

Calendar MCP 서버 할당량

Calendar MCP 서버는 쿼리 비용 할당 측정항목을 사용합니다. 다음 표에서는 각 Calendar MCP 서버 메서드의 쿼리 비용을 섹션별로 자세히 설명합니다.

Calendar MCP 할당량