Directory API: 한도 및 할당량

한도 및 할당량을 통해 부적절한 방식으로 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 계정별로 적용됩니다. 이 한도는 늘릴 수 없습니다.

지수 백오프 구현

지수 백오프는 클라이언트가 일정 시간 동안 실패한 요청을 주기적으로 재시도하는 프로세스입니다. 이는 네트워크 애플리케이션을 위한 표준 오류 처리 전략입니다. 지수 백오프를 사용하면 대역폭 사용량의 효율성을 높이고, 성공적인 응답을 가져오는 데 필요한 요청 수를 줄이며, 동시 환경에서의 요청 처리량을 극대화할 수 있습니다.

간단한 지수 백오프 구현 흐름은 다음과 같습니다.

  1. API에 요청
  2. 재시도 가능한 오류 코드가 포함된 오류 응답 수신
  3. 대기 1초 + random_number_milliseconds
  4. 요청 재시도
  5. 재시도 가능한 오류 코드가 포함된 오류 응답 수신
  6. 대기 2초 + random_number_milliseconds
  7. 요청 재시도
  8. 재시도 가능한 오류 코드가 포함된 오류 응답 수신
  9. 대기 4초 + random_number_milliseconds
  10. 요청 재시도
  11. 재시도 가능한 오류 코드가 포함된 오류 응답 수신
  12. 대기 8초 + random_number_milliseconds
  13. 요청 재시도
  14. 재시도 가능한 오류 코드가 포함된 오류 응답 수신
  15. 대기 16초 + random_number_milliseconds
  16. 요청 재시도
  17. 오류가 계속 발생하면 중지하고 오류를 로깅합니다.

위의 흐름에서 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를 사용하여 최대 다음 작업을 수행할 수 있습니다.

  • 초당 작업 요청 20개
  • 초당 삭제 요청 20개
  • 초당 get 요청 10개
  • 초당 목록 요청 10개
사용자 이름 변경 모든 서비스에 전파되는 데 최대 10분이 걸릴 수 있습니다. 사용자 이름을 변경하기 전에 모든 브라우저 세션 및 서비스에서 사용자를 로그아웃하는 것이 좋습니다. 자세한 내용은 사용자 업데이트를 참고하세요.
조직 단위 만들기/업데이트
  • Directory API를 사용하여 고객별로 초당 2개 이상의 조직 단위를 만들거나 업데이트할 수 없습니다.
  • 고객의 조직 단위 계층 구조는 35개 수준으로 제한됩니다.
  • 고객당 조직 단위의 총합은 40,000개를 초과할 수 없습니다.
API 할당량 카테고리 할당량
Chrome 기기 annotatedLocation자, 최대 자 기기 위치 정보의 최대 문자 수는 200자(영문 기준)입니다.
Chrome 기기 notes자, 최대 자 기기 메모 정보의 최대 문자 수는 500자(영문 기준)입니다.
Chrome 기기, 최대 user자(영문 기준) 기기 사용자 이름의 최대 문자 수는 100자입니다.
도메인 별칭(최대) 최대 도메인 별칭 수는 20개입니다.
그룹, 설명 설명의 최대 문자 수는 4,096자(영문 기준)입니다.
그룹, 계정당 기존 G Suite 무료 버전 계정의 경우 그룹 수가 10개로 제한됩니다. 다른 버전에는 그룹 수에 제한이 없습니다.
그룹, 그룹당 구성원 기존 G Suite 무료 버전 계정의 경우 그룹에 회원을 100명까지 포함할 수 있습니다. 다른 버전에는 그룹 회원 수에 제한이 없습니다. 사용자당 그룹 멤버십 한도는 그룹스 정책 및 한도 이해하기를 참고하세요.
maxResults 쿼리 문자열 API에서 다음을 반환합니다.
  • Chrome 및 휴대기기 – 기본값이며 페이지당 최대 100개의 항목이 있습니다.
  • 그룹 및 그룹 회원 – 기본값(페이지당 최대 200개 항목)
  • 사용자 – 기본값은 100개이고 페이지당 최대 500개 항목입니다.
사용자 별칭 및 조직 단위 리소스는 응답 페이지로 나누기를 사용하지 않습니다. 사용자의 모든 기본 이메일은 알파벳순으로 반환되며 응답 순서는 대소문자를 구분하지 않습니다.
복수 도메인, 계정당 허용되는 최대 도메인 수 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 계정에는 모든 도메인이 포함될 수 있습니다. 여러 도메인 계정에서 한 도메인의 사용자가 다른 계정 도메인의 사용자와 서비스를 공유할 수 있습니다. 여러 도메인 구성요소는 다음과 같습니다.
  • 기본 도메인: 계정의 기본 도메인은 Google Workspace 서비스 약관에 동의한 관리자의 도메인입니다. 이 도메인은 최상위 조직 단위의 계정 수준에 있습니다. Google Workspace 계정에 가입할 때 기본 도메인에는 비즈니스 도메인을 사용하고 다른 도메인은 파일럿이나 테스트와 같은 특수한 사용을 위해 예약하는 것이 좋습니다.
    • 모든 최고 관리자는 전체 계정을 관리할 수 있습니다.
    • API는 Google Workspace 계정의 기본 도메인을 변경하거나 이동할 수 없습니다. 하지만 API는 사용자 계정의 이메일 주소를 한 도메인에서 다른 도메인으로 변경하여 사용자 계정의 이름을 변경할 수 있습니다.
    • Google Workspace 계정의 경우 21일 이내에 기본 도메인의 소유권을 확인해야 합니다. 추가 도메인의 경우 사용자의 기본 이메일 주소에 해당 도메인을 사용하기 전에 도메인 소유권을 확인해야 합니다. 이러한 경우 21일의 유예 기간이 적용되지 않습니다.
    • 이 버전의 API에서 기본 도메인의 설정은 Google Workspace 서비스에 대한 사용자 액세스를 제외하고 계정과 연결된 모든 도메인에 적용됩니다.
  • 추가 계정 도메인 -- 기본 도메인을 설정하고 계정을 설정한 후 계정에 다른 도메인을 추가할 수 있습니다. 추가 도메인의 경우 이 도메인을 설정할 때 그리고 사용자의 기본 이메일 주소에 도메인을 사용하기 전에 소유권을 확인해야 합니다.
  • 사용자의 홈 도메인 -- 사용자의 기본 이메일 주소에 사용되는 도메인이 사용자의 홈 도메인입니다. 이 도메인은 기본 도메인을 포함하여 계정의 모든 도메인이 될 수 있습니다.
여러 도메인 관련 최근 제한사항은 복수 도메인 제한사항을 참고하세요. 여기에는 도메인 별칭, 계정 병합 등에 대한 정보가 포함됩니다.
경고, 그룹 구성원 GROUP_CANNOT_CONTAIN_CYCLE – API가 그룹 멤버십에서 주기를 허용하지 않습니다. 예를 들어 group1이 group2의 멤버인 경우 group2는 group1의 구성원이 될 수 없습니다.