사용량 한도

Google Drive API는 공유 서비스이므로 모든 사용자가 공정하게 사용하고 Google Workspace 시스템의 전반적인 성능을 보호하기 위해 할당량과 제한사항을 적용합니다.

한도는 할당량 단위로 정의됩니다. 할당량 단위는 Google Drive 리소스 사용량을 나타내는 추상적인 측정 단위입니다.

Drive API 할당량

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

  • 프로젝트별 분당: Google Cloud 프로젝트에서 1분 동안 사용할 수 있는 할당량 단위 수입니다.

  • 프로젝트별 사용자별 분당: 클라우드 프로젝트에서 특정 사용자가 사용할 수 있는 할당량 단위 수입니다. 이 한도는 사용자 간에 사용량을 공정하게 분배하는 데 도움이 됩니다.

  • 프로젝트별 일일: 요금이 부과되기 전에 Google Cloud 프로젝트에서 24시간 이내에 이그레스할 수 있는 최대 바이트 수를 정의합니다.

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

사용량 한도 유형 한도
프로젝트별 분당 할당량 단위 1,000,000개
프로젝트별 사용자별 분당 할당량 단위 325,000개
프로젝트별 일일 1 TB

할당량을 초과하면 403: User rate limit exceeded HTTP 상태 코드 응답이 표시됩니다. Drive 백엔드에서 추가 속도 제한 검사를 실행하면 429: Rate limit exceeded 응답이 생성될 수도 있습니다. 이 경우 지수 백오프 알고리즘을 사용하고 나중에 다시 시도해야 합니다.

일일 청구 기준액

이 프로젝트별 일일 한도는 요금이 부과되기 전에 Google Cloud 프로젝트에서 24시간 이내에 사용할 수 있는 최대 할당량 단위 수를 정의합니다.

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

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

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

기준액 한도 유형 한도
프로젝트별 일일 할당량 단위 400,000,000개

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

메서드별 할당량 사용량

요청당 사용되는 할당량 단위 수는 호출된 메서드에 따라 다릅니다. 다음 표에서는 메서드별 할당량 단위 사용량을 간략하게 설명합니다.

작업 할당량 단위
files.get과 같은 항목 읽기 5
files.list와 같은 항목 나열 100
files.download와 같은 항목 다운로드 200
files.update와 같은 항목 수정 50
files.generateIds와 같은 기타 작업 5

기타 제약조건

Drive API를 사용할 때는 다음 제약조건이 적용됩니다.

  • Google Workspace 사용자는 내 Drive와 모든 공유 드라이브 간에 매일 750GB까지만 업로드할 수 있습니다. 이 한도는 사본에도 적용됩니다.

  • 750GB 한도에 도달했거나 750GB보다 큰 파일을 업로드한 사용자는 24시간이 지나기 전까지 추가 파일을 업로드하거나 복사할 수 없습니다.

  • 사용자가 업로드할 수 있는 최대 파일 크기는 5TB입니다. 한도를 초과하는 첫 번째 파일만 업로드가 완료됩니다. 사용자가 복사할 수 있는 최대 파일 크기는 750GB입니다.

  • 알림 채널을 열 때 지정된 주소로 전송되는 알림은 할당량 한도에 포함되지 않습니다. 하지만 changes.watch, channels.stop, 및 files.watch 메서드 호출은 할당량에 포함됩니다.

  • 분당 할당량 내에 있는 경우 하루에 요청할 수 있는 횟수에는 제한이 없습니다.

  • Google Workspace 계정 유형에 따라 추가 Drive 스토리지 한도가 적용됩니다.

시간 기반 할당량 오류 해결

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

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

예시 알고리즘

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

  1. Google Drive API에 요청을 전송합니다.
  2. 요청이 실패하면 1초 + random_number_milliseconds를 대기한 후 요청을 재시도합니다.
  3. 요청이 실패하면 2초 + random_number_milliseconds를 대기한 후 요청을 재시도합니다.
  4. 요청이 실패하면 4초 + random_number_milliseconds를 대기한 후 요청을 재시도합니다.
  5. maximum_backoff 시간까지 이를 반복합니다.
  6. 최대 재시도 횟수까지 계속 대기하고 재시도합니다. 그러나 재시도 간 대기 기간을 늘리지 않습니다.

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

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

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

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

가격 책정

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

할당량 상향 조정 요청

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

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

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