Google Calendar API에는 모든 사용자가 공정하게 사용할 수 있도록 할당량이 마련되어 있습니다. Calendar API를 사용할 때 고려해야 할 세 가지 중요한 제한사항이 있습니다.
- API 사용 할당량은 프로젝트 및 사용자당 적용됩니다. 자세한 내용은 다음 섹션을 참고하세요.
- 일반 캘린더 사용량 한도: 캘린더 사용 한도를 사용하지 않습니다.
- 운영 제한: 언제든지 비율 제한이 적용될 수 있습니다. 예를 들어 한 캘린더에 빠르게 연속으로 쓰기 작업을 시도하는 경우가 여기에 해당합니다.
Calendar API 사용 할당량 유형
두 가지 유형의 할당량이 적용됩니다.
- 프로젝트별 분당: Google Cloud 프로젝트의 요청 수입니다.
- 사용자별 프로젝트별 분당 요청 수: Cloud 프로젝트의 특정 사용자가 한 요청 수입니다. 이 한도는 사용자 간에 사용량을 공정하게 배분하기 위한 것입니다.
할당량은 슬라이딩 기간을 사용하여 분 단위로 계산됩니다. 따라서 1분 동안 분당 할당량을 초과하는 트래픽이 급증할 경우 다음 기간 중에 요금이 제한되므로 평균적으로 사용량이 할당량을 초과하지 않습니다.
두 할당량 중 하나라도 초과하면 비율이 제한되고 쿼리에 403 usageLimits 상태 코드 또는 429 usageLimits 상태 코드가 수신됩니다. 이 경우 취할 수 있는 조치는 다음과 같습니다.
- 지수 백오프 사용, 트래픽 패턴 무작위 순서 지정, 푸시 알림 사용 등 모든 권장사항을 따라야 합니다.
- 프로젝트가 증가하고 사용자가 더 많은 경우 프로젝트당 할당량 증가를 요청할 수 있습니다.
- 사용자당 할당량 한도에 도달하면 다음을 수행할 수 있습니다.
- 서비스 계정을 사용하는 경우 사용자에게 부하를 할당하거나 여러 서비스 계정으로 분할합니다.
- 사용자당 할당량 증가를 요청할 수 있지만 일반적으로 애플리케이션이 일반 캘린더 사용 한도 또는 작업 한도와 같은 다른 유형의 한도에 도달할 수 있으므로 일반적으로 기본값 이상으로 늘리지 않는 것이 좋습니다.
할당량 상향 요청
프로젝트의 사용량 한도를 확인 또는 변경하거나 할당량 증가를 요청하려면 다음 단계를 따르세요.
- 프로젝트의 결제 계정이 아직 없는 경우 계정을 만듭니다.
- API 콘솔에서 API 라이브러리의 사용 설정된 API 페이지를 방문하여 목록에서 API를 선택합니다.
- 할당량 관련 설정을 확인하고 변경하려면 할당량을 선택합니다. 사용 통계를 확인하려면 사용량을 선택합니다.
지수 백오프 사용
요청 속도를 낮추기 위해 403 'usageLimits' 응답 또는 429 응답을 반환합니다 (전체 오류 문서 참조). 이는 치명적인 오류는 아니며 짧은 간격 후에 요청을 재시도하는 것이 좋습니다. 요청이 여전히 너무 빨리 도착하면 다시 요청합니다. 이 작업이 올바르게 작동하려면 시간 경과에 따라 요청 간 지연을 증가시켜야 합니다.
일반적으로 잘린 지수 백오프를 사용해야 합니다. Cloud Storage 문서에서 이 기능의 작동 원리와 선호하는 알고리즘에 대한 자세한 설명을 확인할 수 있습니다. Google 클라이언트 라이브러리를 사용하는 경우 일반적으로 이 작업이 자동으로 처리됩니다. 라이브러리 문서를 참조하세요. 일반적으로 직접 작성하는 대신 라이브러리 구현을 사용해야 합니다.
트래픽 패턴 무작위 순서 지정
캘린더 클라이언트에서 여러 클라이언트가 동시에 작업을 수행하면 트래픽 패턴이 급증할 수 있습니다. 예를 들어 캘린더 클라이언트에서 일반적으로 바람직하지 않은 방법은 자정에 전체 동기화를 실행하는 것입니다. 이 경우 분당 할당량을 초과할 가능성이 거의 높으며 비율 제한 및 백오프가 발생할 수 있습니다.
이를 방지하려면 가능한 한 하루 동안 트래픽을 분산시켜야 합니다. 클라이언트가 매일 동기화를 실행해야 하는 경우 클라이언트가 임의의 시간을 결정하도록 합니다 (클라이언트마다 다름). 작업을 정기적으로 실행해야 하는 경우 간격을 +/- 25%로 변경하세요. 이렇게 하면 트래픽을 더 균등하게 분산하고 훨씬 더 나은 사용자 환경을 제공합니다.
푸시 알림 사용
일반적인 사용 사례에서는 사용자의 캘린더에서 무언가가 변경될 때마다 작업을 실행하려고 합니다. 여기서 피해야 할 패턴은 관심 있는 모든 캘린더를 반복적으로 폴링하는 것입니다. 이렇게 하면 모든 할당량이 매우 빠르게 소모됩니다. 예를 들어 애플리케이션에 사용자가 5,000명이 있고 각 사용자의 캘린더를 1분에 한 번씩 폴링하는 경우 작업이 완료되기 전에도 분당 할당량은 5,000 이상이어야 합니다.
서버 측 애플리케이션은 푸시 알림을 등록할 수 있으며, 이를 통해 관심 있는 상황이 발생할 때 Google에서 사용자에게 알릴 수 있습니다. 이는 설정하는 데 더 많은 작업이 필요하지만 할당량을 훨씬 효율적으로 사용할 수 있고 더 나은 사용자 환경을 제공합니다. 알림을 받을 eventType를 지정해야 합니다. 자세한 내용은 푸시 알림을 참고하세요.
서비스 계정을 사용한 적절한 회계
애플리케이션이 도메인 전체 위임을 사용하여 요청을 수행하는 경우, 기본적으로 서비스 계정에는 가장한 사용자가 아닌 '사용자당 프로젝트별 분당' 할당량에 따라 요금이 청구됩니다. 즉, 여러 사용자의 캘린더에서 작동하더라도 서비스 계정이 소진되고 요금이 제한될 수 있습니다. quotaUser URL 매개변수 (또는 x-goog-quota-user HTTP 헤더)를 사용하여 요금이 청구되는 사용자를 나타내면 이를 방지할 수 있습니다. 할당량 계산에만 사용됩니다. 자세한 내용은 Cloud 문서의 사용자당 요청 제한을 참조하세요.
테스트 할당량 한도 처리
애플리케이션이 실제로 할당량 한도에 도달하는 것을 적절하게 처리할 수 있도록 (예: 지수 백오프로 재시도)하고 사용자의 잠재적 방해 요소를 최소화하려면 실제 환경에서 이 시나리오를 테스트하는 것이 좋습니다.
이러한 테스트가 실제 애플리케이션 사용을 방해하지 않도록 하려면 별도의 테스트 전용 프로젝트를 Google API 콘솔에 등록하고 프로덕션 프로젝트와 유사한 방식으로 구성하는 것이 좋습니다. 그런 다음 이 프로젝트에 인위적으로 낮은 할당량을 설정하고 애플리케이션의 동작을 관찰할 수 있습니다.
가격 책정
Google Calendar API는 모두 추가 비용 없이 사용할 수 있습니다. 할당량 요청 한도를 초과할 경우 추가 요금이 발생하지 않으며 계정에 요금이 청구되지 않습니다.