한도 및 할당량은 Directory 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명 이상의 사용자를 만들 수 없습니다. |
| 사용자 삭제 | Directory API를 사용하여 도메인당 초당 최대 5명의 사용자를 삭제할 수 있습니다. 이는 도메인별 백엔드 서비스 한도로, Google Cloud 콘솔 프로젝트 할당량에서 조정할 수 없습니다. 일괄 요청을 전송할 때는 일괄 요청 전반의 총 작업이 초당 쿼리 수(QPS) 5개 미만으로 유지되도록 하세요. |
| 그룹 구성원 삭제 | Directory API를 사용하면 도메인당 초당 최대 30명의 그룹 회원을 삭제할 수 있습니다. 이는 도메인별 백엔드 서비스 한도로, Google Cloud 콘솔 프로젝트 할당량에서 조정할 수 없습니다. 일괄 요청을 전송할 때는 일괄 요청 전체의 총 작업이 초당 쿼리 수(QPS) 30개 미만으로 유지되도록 하세요. |
| 그룹이 다른 그룹의 구성원으로 추가됨 | 하위 그룹의 회원이 상위 그룹의 회원으로 표시되기까지 최대 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명을 만들면 Google Workspace 라이선스 10개에 대한 요금이 계정에 청구되며, 생성 시점부터 일할 계산됩니다. 연간 요금제를 사용 중인 경우 이미 일정 수의 라이선스에 대해 선불로 결제하기로 약정했으므로 약정한 수만큼만 사용자를 만들 수 있습니다. 요금제 및 결제 계정에 대한 자세한 내용은 관리 고객센터를 참고하세요. |
| 성명 | 이름과 성은 최대 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과 다릅니다. 사용자 이름에는 등호(=), 괄호(<,>) 또는 연속된 마침표(.)를 2개 이상 포함할 수 없습니다. 자세한 내용은 관리 고객센터를 참고하세요. |
| 사용자 이름, 이름 바꾸기 | Google 행아웃은 이름을 바꾼 후 기억된 모든 채팅 초대를 삭제합니다. 사용자가 친구와 다시 채팅하려면 권한을 요청해야 합니다. 이전 사용자 이름은 이메일 전달 설정 시 지속적인 메일 전송을 위해 이메일 별칭으로 유지되며 새 사용자 이름으로 사용할 수 없습니다. 사용자 이름 변경이 미치는 영향에 관한 중요한 세부정보는 관리 고객센터를 참고하세요. 사용자 별칭 삭제 작업을 사용하여 이름을 변경한 후 이메일 별칭을 삭제합니다. |
| 여러 도메인의 사용자 | Google Workspace 계정에는 모든 도메인이 포함될 수 있습니다. 여러 도메인 계정에서 한 도메인의 사용자는 다른 계정 도메인의 사용자와 서비스를 공유할 수 있습니다. 여러 도메인 구성요소는 다음과 같습니다.
|
| 경고, 그룹 구성원 | GROUP_CANNOT_CONTAIN_CYCLE – API는 그룹 멤버십의 순환을 허용하지 않습니다. 예를 들어 group1이 group2의 구성원인 경우 group2는 group1의 구성원이 될 수 없습니다. |