제한사항 및 할당량은 Reports API를 부적절한 방식으로 사용하는 자동 프로세스로부터 Google 인프라를 보호합니다. API의 과도한 요청은 무해한 오타로 인해 발생할 수도 있고, 불필요한 API 호출을 하는 비효율적으로 설계된 시스템으로 인해 발생할 수도 있습니다. 원인과 무관하게 Google Workspace 시스템을 전반적으로 정상 상태로 유지하려면 특정 소스의 트래픽이 일정 수준에 도달할 때 트래픽을 차단해야 합니다. 이를 통해 한 개발자의 작업이 더 큰 커뮤니티에 부정적인 영향을 미치지 않도록 할 수 있습니다.
API 요청이 실패하는 드문 경우 HTTP 상태 코드 응답이 표시됩니다. 상태 코드 403에는 잘못된 입력에 관한 오류 정보가 있고 HTTP 상태 코드 503에는 초과된 API 할당량을 나타내는 오류 정보가 있습니다. 이러한 응답을 통해 맞춤 애플리케이션에서 이러한 오류를 감지하고 적절한 조치를 취할 수 있습니다.
고정된 기간 내에 요청을 완료해야 하는 경우 요청을 동시에 보내거나 Java 또는 C# 애플리케이션에서 여러 스레드를 사용하세요. 동시 요청의 예로는 한 사용자의 이메일을 한 번에 많이 추가하거나 삭제하는 대신 여러 사용자의 이메일을 작은 일괄 처리로 요청하는 것입니다. 스레드의 경우 사용자 이메일당 하나의 스레드로 10개의 스레드부터 시작해 보세요. 스레드 권장사항에는 장단점이 있으며 모든 API 상황에 유용한 것은 아닙니다. 요청 수가 너무 많아지면 할당량 오류가 발생합니다.
시간 기반 오류 (스레드당 N초 동안 최대 N개)의 경우, 특히 503 상태 코드 오류의 경우 코드가 예외를 포착하고 지수 백오프 알고리즘을 사용하여 실패한 호출을 재시도하기 전에 약간의 지연을 기다리는 것이 좋습니다. 한 스레드의 Reports API 예는 5초 동안 기다렸다가 실패한 호출을 재시도하는 것입니다. 요청이 성공하면 다른 스레드에 대해 이 패턴을 반복합니다. 두 번째 요청이 성공하지 않으면 호출이 성공할 때까지 애플리케이션에서 요청 빈도를 줄여야 합니다. 예를 들어 초기 5초 지연을 10초로 늘리고 실패한 호출을 다시 재시도합니다. 또한 재시도 한도를 정합니다. 예를 들어 애플리케이션에서 사용자에게 오류를 반환하기 전에 지연 시간이 다른 요청을 5~7회 재시도합니다.
제한사항
| API 제한사항 카테고리 | 제한사항 |
|---|---|
| 보고서 QPS 및 QPD 비율 | API는 Google Cloud 프로젝트의 요청 수를 제한합니다.
Google Cloud 콘솔에 설정된 기본값은 Google Cloud 프로젝트당 사용자당 분당 쿼리 수 2,400개입니다. Google Cloud 프로젝트의
Admin SDK API 할당량 페이지
에서 이 한도를 늘릴 수 있습니다.
이러한 한도를 초과하면 서버에서 HTTP 503 상태 코드을 반환합니다. 요청을 재시도할 때는 지수 백오프 알고리즘을 사용하세요. |
activities.list의 추가 제한사항 |
activities.list API에는 분당 250
개의 필터 쿼리 (시간당 15,000개의 필터 쿼리)라는 추가 제한사항이 있습니다. 필터 쿼리
는 다음 쿼리
매개변수 중 하나 이상을 포함하는 API 요청입니다.
|
| API 할당량 카테고리 | 할당량 |
| maxResults | API 응답의 각 페이지에 나열된 레코드 수는 0~1,000개입니다. 기본값은 1,000개의 레코드입니다. |
기타 제한사항 유형
| 기타 제한사항 유형 | 제한사항 및 가이드라인 |
|---|---|
| 데이터 형식, 기본값 | 기본 데이터 형식은 JSON입니다. API는 Atom 형식도 지원합니다. |
| 승인되지 않은 요청 | Google은 API에 대한 승인되지 않은 요청을 허용하지 않습니다. 승인 토큰이 제공되지 않으면 요청이 승인되지 않은 것으로 간주됩니다. 자세한 내용은 요청 승인을 참고하세요. |
| 경고 메시지 |
|
activities.list 권장사항
activities.list
메서드는 감사 조사를 위해 사용해야 합니다. 최상의
성능을 위해 요청에는 기간이 포함되어야 합니다.
startTime 및 endTime 매개변수를 사용합니다. 기간이 좁을수록 응답 시간이 훨씬 빨라집니다. 이 메서드는 대량의 감사 로그를 검색하는 데 적합하지 않습니다. activities.list 필터 요청 할당량이 정기적으로
소진되는 경우 다음
옵션을 고려하세요.
- Google Workspace 로그를 BigQuery로 내보내도록 설정하고 BigQuery의 강력한 쿼리 API 를 사용하여 API 할당량 제약 없이 필요한 데이터를 가져오고 분석합니다.
- 필터 요청을 사용하는 대신 기간이 있는 비필터 요청을 사용하고 클라이언트 측 필터링 (즉, 애플리케이션에서 필터링 로직 실행)을 수행합니다. 이렇게 하면 분당 250개의 필터 쿼리 한도를 초과할 수 있지만 Google Cloud 프로젝트당 사용자당 분당 쿼리 수 2,400개의 한도는 여전히 적용됩니다.