한도와 할당량을 사용하면 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, 000회 실행할 수 있습니다.
|
| 사용자 이름 변경 | 모든 서비스에 전파되는 데 최대 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에서는 스팸 및 이메일 악용을 방지하기 위해 외부 수신자에게 한 번에 보낼 수 있는 메일 수를 제한합니다. 그룹에 메시지를 보내면 외부 회원 1명당 수신자로 1명씩 집계됩니다. 자세한 내용은 이메일 전송 한도 및 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의 구성원이 될 수 없습니다. |