한도 및 할당량을 통해 부적절한 방식으로 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명 이상의 사용자를 만들 수 없습니다. |
| 그룹이 다른 그룹에 구성원으로 추가되었습니다. | 하위 그룹의 회원이 상위 그룹의 회원으로 표시되기까지 최대 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 서비스를 사용 설정하기 전에 그룹의 이메일 주소를 변경할 수 있습니다. 관리 콘솔을 사용하여 그룹 회원의 이메일 주소를 변경합니다. 변경하면 API에 이메일 주소 변경사항이 자동으로 반영됩니다. |
| 그룹, 설정 | 관리 콘솔을 사용하여 그룹스 액세스 설정, 공유 옵션, 모니터링, 토론 자료실을 관리합니다. 그룹 설정에 대한 자세한 내용은 관리 고객센터를 참고하세요. |
| 그룹, 메시지 전송 | 스팸 및 이메일 악용을 방지하기 위해 Google에서는 외부 수신자에게 한 번에 보낼 수 있는 메일 수를 제한합니다. 그룹에 메일을 보내면 각 외부 회원이 수신자 한 명으로 계산됩니다. 자세한 내용은 이메일 전송 한도 및 Gmail 사용자에게 보낸 메일이 차단되거나 스팸으로 분류되는 것을 방지하기 를 참고하세요. |
| 그룹스, NDR 메시지 전송 | '반송 메일'이라고도 하는 전송 실패 확인 (NDR)은 그룹에 보내거나 전달할 수 없습니다. |
| 사용자가 만든 그룹, 제한사항 | 사용자가 만든 그룹 한도에 대해서는 관리 고객센터를 참고하세요. |
| 조직 단위, 서비스 사용/사용 중지 | 관리 콘솔을 사용하여 조직 단위에 대해 서비스를 사용 또는 사용 중지할 수 있습니다. |
| 비밀번호 | 모든 문자 조합을 포함할 수 있습니다. 8자 이상이어야 합니다. 최대 길이는 100자입니다. |
| 사진 | 이 버전의 API에서 사진은 사용자의 최신 Google 프로필 사진입니다. |
| 사용자 이름 | 사용자 이름에는 문자 (a~z), 숫자 (0~9), 대시 (-), 밑줄 (_)이 포함될 수 있으며 Google Workspace에서는 점 또는 마침표 (.)를 인식합니다. 이는 Gmail과 다릅니다. 사용자 이름에 등호 (=), 괄호 (<,>) 또는 연속으로 둘 이상의 마침표 (.)를 포함할 수 없습니다. 자세한 내용은 관리 고객센터를 참고하세요. |
| 사용자 이름, 이름 바꾸기 | 이름을 변경한 후 Google 행아웃에서 저장된 모든 채팅 초대를 삭제합니다. 사용자는 친구와 다시 채팅하기 위한 권한을 요청해야 합니다. 이메일 전달 설정의 경우 메일이 계속 전송되도록 하기 위해 기존 사용자 이름은 이메일 별칭으로 유지되고 새 사용자 이름으로 사용할 수 없습니다. 사용자 이름 변경이 미치는 영향에 대한 중요한 세부정보는 관리 고객센터를 참고하세요. 이름을 변경한 후 이메일 별칭을 삭제하려면 사용자 별칭 삭제 작업을 사용하세요. |
| 여러 도메인의 사용자 | Google Workspace 계정에는 모든 도메인이 포함될 수 있습니다. 여러 도메인 계정에서 한 도메인의 사용자가 다른 계정 도메인의 사용자와 서비스를 공유할 수 있습니다. 여러 도메인 구성요소는 다음과 같습니다.
|
| 경고, 그룹 구성원 | GROUP_CANNOT_CONTAIN_CYCLE – API가 그룹 멤버십에서 주기를 허용하지 않습니다. 예를 들어 group1이 group2의 멤버인 경우 group2는 group1의 구성원이 될 수 없습니다. |