한도와 할당량은 디렉터리 API를 부적절한 방식으로 사용하는 자동 프로세스로부터 Google 인프라를 보호합니다. API의 과도한 요청은 무해한 철자 오류로 인해 발생할 수도 있고, 불필요한 API 호출을 하는 비효율적으로 설계된 시스템으로 인해 발생할 수도 있습니다. 원인과 무관하게 Google Workspace 시스템을 전반적으로 정상 상태로 유지하려면 특정 소스의 트래픽이 일정 수준에 도달할 때 트래픽을 차단해야 합니다. 이를 통해 한 개발자의 행위가 더 큰 커뮤니티에 부정적인 영향을 미치지 않도록 할 수 있습니다.
API 요청이 실패할 가능성은 낮지만, 실패할 경우 API는 HTTP 상태 코드와 오류 이유를 반환합니다. 또한 응답 본문에는 오류의 원인에 대한 자세한 설명이 포함되어 있습니다.
다음 목록에는 할당량 한도 도달로 인해 발생하는 오류의 가능한 오류 코드, 이유, 해당 설명, 권장 조치가 나와 있습니다.
| 코드 | 이유 | 설명 | 권장 작업 |
|---|---|---|---|
| 403 | userRateLimitExceeded | 사용자 비율 제한이 초과되었음을 나타냅니다. Google Cloud 콘솔에 설정된 기본값은 Google Cloud 프로젝트당 사용자당 분당 2,400개의 쿼리입니다. | Google Cloud 프로젝트의 Admin SDK API 할당량 페이지에서 사용자별 한도를 늘리거나 지수 백오프를 사용하여 요청을 보내는 속도를 늦춥니다. |
| 403 | quotaExceeded | 특정 작업의 동시 요청 한도에 도달했음을 나타냅니다. | 지수 백오프를 사용하여 다시 시도하세요. 요청을 보내는 속도를 늦춰야 합니다. |
| 429 | rateLimitExceeded | 특정 작업의 동시 요청 한도에 도달했음을 나타냅니다. | 지수 백오프를 사용하여 다시 시도하세요. 요청을 보내는 속도를 늦춰야 합니다. 이 한도는 API 클라이언트별 또는 사용자별이 아닌 Google Workspace 계정별로 적용됩니다. 이 한도는 늘릴 수 없습니다. |
지수 백오프 구현
지수 백오프는 클라이언트가 시간 간격을 늘려 실패한 요청을 주기적으로 다시 시도하는 프로세스입니다. 네트워크 애플리케이션의 표준 오류 처리 전략입니다. 지수 백오프를 사용하면 대역폭 사용량의 효율성을 높이고, 성공적인 응답을 가져오는 데 필요한 요청 수를 줄이며, 동시 환경에서의 요청 처리량을 극대화할 수 있습니다.
간단한 지수 백오프 구현 흐름은 다음과 같습니다.
- API에 요청하기
- 재시도 가능한 오류 코드가 있는 오류 응답을 수신합니다.
- 1초 +
random_number_milliseconds초 대기 - 요청 재시도
- 재시도 가능한 오류 코드가 있는 오류 응답을 수신합니다.
- 2초 +
random_number_milliseconds초 동안 기다립니다. - 요청 재시도
- 재시도 가능한 오류 코드가 있는 오류 응답을 수신합니다.
- 4초 +
random_number_milliseconds초 대기 - 요청 재시도
- 재시도 가능한 오류 코드가 있는 오류 응답을 수신합니다.
- 8초 +
random_number_milliseconds초 동안 기다립니다. - 요청 재시도
- 재시도 가능한 오류 코드가 있는 오류 응답을 수신합니다.
- 16초 +
random_number_milliseconds초 동안 기다립니다. - 요청 재시도
- 오류가 계속 표시되면 중지하고 오류를 기록합니다.
위 흐름에서 random_number_milliseconds는 1, 000밀리초 이하의 임의의 숫자입니다. 이는 일부 동시 구현에서 특정 잠금 오류를 방지하는 데 필요합니다.
random_number_milliseconds은 대기 후 매번 재정의해야 합니다.
참고: 대기 시간은 항상 (2 ^ n) + random_number_milliseconds이며, 여기서 n은 단순 증가 정수로 처음에는 0으로 정의됩니다. n은 반복 (요청)할 때마다 1씩 증가합니다.
n이 5이면 종료하도록 알고리즘이 설정되어 있습니다. 이 제한은 클라이언트의 무제한 재시도를 방지하기 위해서만 적용되며 요청이 '복구 불가능한 오류'로 간주되기 전에 약 32초의 총 지연 시간을 발생시킵니다. 필요한 경우 API 클라이언트가 더 많은 시도 횟수를 구현할 수 있습니다.
API 한도 및 할당량
| API 한도 카테고리 | 한도 |
|---|---|
| 사용자 만들기 | Directory API를 사용하여 도메인당 초당 10명 이상의 사용자를 만들 수 없습니다. |
| 그룹이 다른 그룹의 구성원으로 추가됨 | 하위 그룹의 회원이 상위 그룹의 회원으로 표시되기까지 최대 10분이 걸릴 수 있습니다. 이 한도는 시스템의 용량에 따라 변경될 수 있습니다. |
| 휴대기기 |
Directory API를 사용하면 다음 작업을 최대 횟수까지 실행할 수 있습니다.
|
| 사용자 이름 바꾸기 | 모든 서비스에 전파되는 데 최대 10분이 걸릴 수 있습니다. 사용자의 이름을 바꾸기 전에 모든 브라우저 세션과 서비스에서 사용자를 로그아웃하는 것이 좋습니다. 자세한 내용은 사용자 업데이트를 참고하세요. |
| 조직 단위 생성/업데이트 |
|
| API 할당량 카테고리 | 할당량 |
Chrome 기기 annotatedLocation, 최대 글자 수
|
기기의 위치 정보의 최대 문자 수는 200자(영문 기준)입니다. |
Chrome 기기 notes, 최대 글자 수
|
기기의 메모 정보에 허용되는 최대 문자 수는 500자입니다. |
Chrome 기기, 최대 user자(영문 기준)
|
기기 사용자 이름의 최대 글자 수는 100자입니다. |
| 도메인 별칭, 최대 | 도메인 별칭의 최대 개수는 20개입니다. |
| 그룹, 설명 | 설명의 최대 문자 수는 4,096자입니다. |
| 계정별 그룹 | G Suite 기존 무료 버전 계정의 경우 그룹 수가 10개로 제한됩니다. 다른 버전에서는 그룹 수에 제한이 없습니다. |
| 그룹, 그룹당 회원 수 | G Suite 기존 무료 버전 계정의 경우 그룹에 최대 100명의 회원이 포함될 수 있습니다. 다른 버전에서는 그룹의 회원 수에 제한이 없습니다. 사용자당 그룹 멤버십 한도는 그룹스 정책 및 한도 이해하기를 참고하세요. |
| maxResults 쿼리 문자열 | API는 다음을 반환합니다.
|
| 다중 도메인, 계정에서 허용되는 최대 도메인 수 | 600개 (기본 도메인 1개 + 추가 도메인 599개) |
| 조직 단위, 한 번에 이동되는 최대 사용자 수 | 한 번에 20명의 사용자를 이동할 수 있습니다. 사용자의 기본 이메일 주소가 계정에 이미 있어야 합니다. |
| 사용자 별칭 | 모든 사용자 계정에 허용되는 총 별칭 수는 30개입니다. |
| 삭제된 별칭을 사용하는 사용자 별칭 | 삭제된 사용자 별칭은 즉시 다시 사용할 수 있습니다. |
| 기타 유형의 한도 | 제한사항 및 가이드라인 |
|---|---|
| 청구 및 사용자 만들기 | Google Workspace의 유연한 요금제를 사용하는 사용자의 경우 이 API를 사용하여 사용자를 만들면 금전적 영향이 발생하며 고객 결제 계정에 요금이 청구됩니다. 예를 들어 Google Workspace의 유연 요금제를 사용하는 경우 사용자를 10명 만들면 생성된 시점부터 일할 계산된 10개의 Google Workspace 라이선스에 대한 요금이 계정에 청구됩니다. 연간 요금제를 사용 중인 경우 이미 특정 수의 라이선스에 대해 선불로 약정했으므로 약정한 수만큼만 사용자를 만들 수 있습니다. 요금제 및 결제 계정에 대한 자세한 내용은 관리 고객센터를 참고하세요. |
| 성명 | 성과 이름은 최대 40자(영문 기준)입니다. 유니코드/UTF-8 문자가 지원되며 공백, 문자 (a~z), 숫자 (0~9), 대시 (-), 슬래시 (/), 마침표 (.)를 포함할 수 있습니다. 문자 사용 규칙에 대한 자세한 내용은 관리 도움말 센터를 참고하세요. |
| 그룹, 삭제 | 그룹을 삭제해도 그룹 구성원의 사용자 계정은 삭제되지 않습니다. |
| 그룹 및 그룹 구성원, 이메일 주소 변경 | 이 버전의 API에서는 Google Workspace 서비스가 사용 설정되기 전에 그룹의 이메일 주소를 변경할 수 있습니다. Google 관리 콘솔을 사용하여 그룹 구성원의 이메일 주소를 변경합니다. 변경되면 API에 이메일 주소 변경사항이 자동으로 반영됩니다. |
| 그룹, 설정 | 그룹 액세스 설정, 공유 옵션, 모니터링, 토론 보관 파일은 Google 관리 콘솔을 사용하여 관리됩니다. 그룹 설정에 대한 자세한 내용은 관리 고객센터를 참고하세요. |
| 그룹, 메시지 전송 | Google에서는 스팸 및 이메일 남용을 방지하기 위해 외부 수신자에게 한 번에 보낼 수 있는 메일 수를 제한합니다. 그룹에 메일을 보내면 각 외부 회원이 수신자 1명으로 계산됩니다. 자세한 내용은 이메일 전송 한도 및 Gmail 사용자에게 보낸 메일이 차단되거나 스팸으로 분류되지 않게 하기 를 참고하세요. |
| 그룹, NDR 메시지 전송 | '반송 메일'이라고도 하는 전송 실패 보고서 (NDR)는 그룹에 전송하거나 전달할 수 없습니다. |
| 사용자가 만든 그룹, 제한사항 | 사용자가 만든 그룹의 한도는 관리 고객센터를 참고하세요. |
| 조직 단위, 서비스 사용 설정/사용 중지 | Google 관리 콘솔을 사용하여 조직 단위의 서비스 사용 설정 및 사용 중지를 관리합니다. |
| 비밀번호 | 문자를 자유롭게 조합하여 만들 수 있습니다. 8자 이상이어야 합니다. 최대 길이는 100자입니다. |
| 사진 | 이 버전의 API에서 사진은 사용자의 최신 Google 프로필 사진입니다. |
| 사용자 이름 | 사용자 이름에는 문자 (a-z), 숫자 (0-9), 대시 (-), 밑줄 (_)을 포함할 수 있으며 Google Workspace에서는 점 또는 마침표 (.)를 인식합니다. Gmail과는 다릅니다. 사용자 이름에 등호 (=), 괄호 (<,>), 연속으로 두 개 이상의 마침표 (.)를 포함할 수 없습니다. 자세한 내용은 관리 고객센터를 참고하세요. |
| 사용자 이름, 이름 바꾸기 | 이름을 바꾼 후 Google 행아웃에서 기억된 모든 채팅 초대장이 삭제됩니다. 사용자가 친구와 채팅할 권한을 다시 요청해야 합니다. 이메일 전달 설정의 경우 메일이 계속 전송되도록 기존 사용자 이름이 이메일 별칭으로 유지되며 새 사용자 이름으로 사용할 수 없습니다. 사용자 이름 변경의 영향에 관한 중요한 세부정보는 관리 고객센터를 참고하세요. 이름을 바꾼 후 사용자의 별칭 삭제 작업을 사용하여 이메일 별칭을 삭제합니다. |
| 여러 도메인의 사용자 | Google Workspace 계정에는 모든 도메인이 포함될 수 있습니다. 여러 도메인 계정에서 한 도메인의 사용자는 다른 계정 도메인의 사용자와 서비스를 공유할 수 있습니다. 여러 도메인 구성요소는 다음과 같습니다.
|
| 경고, 그룹 구성원 | GROUP_CANNOT_CONTAIN_CYCLE: API는 그룹 멤버십의 순환을 허용하지 않습니다. 예를 들어 group1이 group2의 구성원인 경우 group2는 group1의 구성원이 될 수 없습니다. |