Directory API: ograniczenia

Ograniczenia i limity chronią infrastrukturę Google przed automatycznym procesem, który korzysta z interfejsu Directory API w niewłaściwy sposób. Nadmierna liczba żądań z interfejsu API może wynikać z nieszkodliwej literówki lub nieskutecznie zaprojektowanego systemu, który wykonuje niepotrzebne wywołania interfejsu API. Niezależnie od przyczyny blokowanie ruchu z określonego źródła po osiągnięciu określonego poziomu jest niezbędne dla ogólnego stanu systemu Google Workspace. Dzięki temu działania danego dewelopera nie wpływają negatywnie na całą społeczność.

W mało prawdopodobnym przypadku niepowodzenia żądania do interfejsu API interfejs API zwraca kod stanu HTTP i przyczyną błędu. Dodatkowo treść odpowiedzi zawiera szczegółowy opis przyczyny błędu.

Poniższa lista zawiera możliwe kody błędów, ich przyczyny, odpowiadające im opisy i zalecane działania w przypadku błędów spowodowanych przekroczeniem limitów.

Kod Przyczyna Opis Zalecane działanie
403 userRateLimitExceeded Wskazuje, że limit liczby użytkowników został przekroczony. Wartość domyślna ustawiona w konsoli Google Cloud to 2400 zapytań na minutę na użytkownika na projekt Google Cloud. Zwiększ limity na użytkownika na stronie limitów interfejsu API pakietu Admin SDK w projekcie Google Cloud lub zwolnij częstotliwość wysyłania żądań za pomocą wykładniczego ponowienia.
403 quotaExceeded Wskazuje, że został osiągnięty limit żądań równoczesnych dla określonej operacji. Spróbuj ponownie, korzystając z wykładniczego ponowienia. Musisz zmniejszyć częstotliwość wysyłania żądań.
429 rateLimitExceeded Wskazuje, że został osiągnięty limit żądań równoczesnych dla określonej operacji. Spróbuj ponownie, korzystając z wykładniczego ponowienia. Musisz zmniejszyć częstotliwość wysyłania żądań. Ten limit dotyczy konta Google Workspace, a nie klienta API ani użytkownika. Tego limitu nie można zwiększyć.

Wdrażanie wykładniczego ponawiania

Wykładnicze ponawianie to proces, w którym klient okresowo ponawia próbę nieudanego żądania przez dłuższy czas. Jest to standardowa strategia obsługi błędów w aplikacjach sieciowych. Wykorzystanie wykładniczego ponowienia zwiększa wydajność wykorzystania przepustowości, zmniejsza liczbę żądań wymaganych do uzyskania pomyślnej odpowiedzi oraz maksymalizuje przepustowość żądań w równoczesnych środowiskach.

Proces implementacji prostego, wykładniczego ponowienia jest opisany poniżej.

  1. Wyślij żądanie do interfejsu API
  2. otrzyma odpowiedź o błędzie zawierającą kod błędu umożliwiającego ponawianie próby;
  3. Zaczekaj 1 s i random_number_milliseconds s
  4. Ponów prośbę
  5. otrzyma odpowiedź o błędzie zawierającą kod błędu umożliwiającego ponawianie próby;
  6. Zaczekaj 2 s i random_number_milliseconds s
  7. Ponów prośbę
  8. otrzyma odpowiedź o błędzie zawierającą kod błędu umożliwiającego ponawianie próby;
  9. Zaczekaj 4 s i random_number_milliseconds s
  10. Ponów prośbę
  11. otrzyma odpowiedź o błędzie zawierającą kod błędu umożliwiającego ponawianie próby;
  12. Odczekaj 8 s + random_number_milliseconds s
  13. Ponów prośbę
  14. otrzyma odpowiedź o błędzie zawierającą kod błędu umożliwiającego ponawianie próby;
  15. Odczekaj 16 s + random_number_milliseconds s
  16. Ponów prośbę
  17. Jeśli błąd nadal występuje, zatrzymaj go i zarejestruj.

W powyższym procesie random_number_milliseconds jest losową liczbą milisekund równą lub mniejszą od 1000. Jest to konieczne, aby uniknąć pewnych błędów blokady w niektórych równoczesnych implementacjach. Po każdym oczekiwaniu trzeba ponownie określić właściwość random_number_milliseconds.

Uwaga: czas oczekiwania wynosi zawsze (2 ^ n) + random_number_milliseconds, gdzie n to monotonicznie rosnąca liczba całkowita, początkowo zdefiniowana jako 0. Wartość n zwiększa się o 1 z każdą iteracją (każde żądanie).

Algorytm kończy działanie, gdy wartość n wynosi 5. Ogranicza się go tylko po to, aby uniemożliwić klientom nieskończone ponawianie prób w nieskończoność, przez co powoduje całkowite opóźnienie (około 32 sekundy) przed uznaniem żądania za „nieodwracalny błąd”. W razie potrzeby Twój klient interfejsu API może wdrożyć większą liczbę prób.

Ograniczenia interfejsu API

Kategorie limitów interfejsu API Limity
Tworzenie użytkowników Przy użyciu interfejsu Directory API nie możesz utworzyć więcej niż 10 użytkowników na sekundę.
Grupa została dodana jako członek do innej grupy Zanim członkowie grupy podrzędnej pojawią się jako członkowie grupy nadrzędnej, może minąć do 10 minut. Ten limit może się zmienić w zależności od wydajności systemu.
Urządzenia mobilne

Przy użyciu interfejsu Directory API możesz:

  • 20 żądań działań na sekundę.
  • 20 żądań usunięcia na sekundę.
  • 10 żądań na sekundę.
  • 10 żądań listy na sekundę.
Zmiana nazw użytkowników Zastosowanie zmian we wszystkich usługach może potrwać do 10 minut. Przed zmianą nazwy użytkownika zalecamy wylogowanie go ze wszystkich sesji i usług przeglądarki. Więcej informacji znajdziesz w artykule Aktualizowanie użytkowników.
Tworzenie i aktualizowanie jednostek organizacyjnych
  • Przy użyciu interfejsu Directory API nie możesz utworzyć ani zaktualizować więcej niż 1 jednostki organizacyjnej na klienta.
  • Hierarchia jednostek organizacyjnych klienta jest ograniczona do 35 poziomów.
  • Łączna liczba jednostek organizacyjnych na klienta nie może przekraczać 40 000.
Kategorie limitów interfejsu API Limity
Urządzenia z Chrome: annotatedLocation, maksymalna liczba znaków Informacje o lokalizacji urządzenia mogą zawierać maksymalnie 200 znaków.
Urządzenia z Chrome: notes, maksymalna liczba znaków Informacje w notatkach na urządzeniu mogą mieć maksymalnie 500 znaków.
Urządzenia z Chrome, maksymalna liczba znaków: user Maksymalna liczba znaków w nazwie użytkownika urządzenia to 100.
Aliasy domen, maksymalna Maksymalna liczba aliasów domeny to 20.
Grupy, opis Maksymalna liczba znaków w opisie to 4096.
Liczba grup na konto Na koncie w wycofanej, bezpłatnej wersji G Suite liczba grup jest ograniczona do 10. Inne wersje nie mają limitu liczby grup.
Grupy, liczba członków na grupę W przypadku wycofanej, bezpłatnej wersji G Suite grupa może zawierać do 100 użytkowników. Inne wersje nie mają limitu liczby członków grupy. Informacje o limitach członkostwa w grupach na użytkownika znajdziesz w artykule Omówienie zasad i ograniczeń obowiązujących w Grupach dyskusyjnych.
Ciąg zapytania maxResults Interfejs API zwraca:
  • Chrome i urządzenia mobilne – wartość domyślna, maksymalnie 100 wpisów na stronę.
  • Grupy i członkowie grup – domyślnie, maksymalnie 200 wpisów na stronę.
  • Użytkownicy – domyślnie 100 pozycji, maksymalnie 500 pozycji na stronę.
Alias użytkownika i zasoby jednostki organizacyjnej nie używają podziału odpowiedzi na strony. Wszystkie główne adresy e-mail użytkowników są zwracane w kolejności alfabetycznej, a wielkość liter nie ma znaczenia.
Wiele domen, maksymalna dozwolona liczba domen na koncie 600 (1 domena podstawowa + 599 domen dodatkowych)
Jednostka organizacyjna, maksymalna liczba użytkowników przeniesionych naraz Jednocześnie można przenieść 20 użytkowników. Podstawowy adres e-mail użytkownika musi już istnieć na koncie.
Aliasy użytkowników Łączna liczba aliasów dozwolonych na każde konto użytkownika wynosi 30.
Aliasy użytkowników z usuniętym aliasem Usunięty alias użytkownika może być natychmiast użyty ponownie.

Inne typy limitów Ograniczenia i wytyczne
Płatności i tworzenie użytkowników W przypadku użytkowników korzystających z abonamentu elastycznego Google Workspace tworzenie użytkowników za pomocą tego interfejsu API będzie miało wpływ na finanse i spowoduje naliczenie opłat na koncie rozliczeniowym klienta. Jeśli na przykład korzystasz z abonamentu elastycznego Google Workspace, utworzenie 10 użytkowników spowoduje naliczenie opłat za 10 licencji Google Workspace, które będą naliczane proporcjonalnie od momentu utworzenia licencji. Jeśli korzystasz z abonamentu rocznego, zobowiązujesz się do płacenia z góry za określoną liczbę licencji. Możesz utworzyć tylko tyle kont użytkowników, ile wynosi Twoje zobowiązanie. Więcej informacji o abonamentach i koncie rozliczeniowym znajdziesz w Centrum pomocy dla administratorów.
Imię i nazwisko Imiona i nazwiska mogą mieć maksymalnie 40 znaków. Obsługujeją one znaki Unicode/UTF-8 oraz mogą zawierać spacje, litery (a–z), cyfry (0–9), łączniki (-), ukośniki (/) i kropki (.). Więcej informacji o regułach użycia znaków znajdziesz w Centrum pomocy dla administratorów.
Grupy, usuwanie Usunięcie grupy nie powoduje usunięcia kont użytkowników jej członków.
Grupy i członkowie grup, zmiana adresu e-mail W tej wersji interfejsu API adres e-mail grupy można zmienić przed włączeniem usługi Google Workspace. W konsoli administracyjnej możesz zmienić adres e-mail członka grupy. Po zmianie interfejs API automatycznie odzwierciedla zmiany adresu e-mail.
Grupy, ustawienia Do zarządzania ustawieniami dostępu do grup, opcjami udostępniania, monitorowania i archiwum dyskusji służy konsola administracyjna. Więcej informacji o ustawieniach grup znajdziesz w Centrum pomocy dotyczącym administrowania.
Grupy, wysyłanie wiadomości Aby zapobiec spamowaniu i nadużywaniu poczty e-mail, Google ogranicza liczbę wiadomości, które możesz wysłać naraz do adresatów zewnętrznych. Jeśli wysyłasz wiadomość do grupy, każdy członek z zewnątrz jest liczony jako jeden odbiorca. Więcej informacji znajdziesz w artykułach Limity wysyłania e-maili i Zapobieganie blokowaniu i umieszczaniu w folderze Spam e-maili wysyłanych do użytkowników Gmaila .
Grupy, wysyłanie wiadomości NDR Do grupy nie można wysyłać ani przekazywać potwierdzeń niedostarczenia wiadomości (tzw. odesłanych wiadomości).
Grupy utworzone przez użytkowników, ograniczenia Informacje o limitach dotyczących grup utworzonych przez użytkowników znajdziesz w Centrum pomocy dla administratorów
Jednostka organizacyjna, która włącza i wyłącza usługi Użyj konsoli administracyjnej, aby zarządzać włączaniem i wyłączaniem usług w jednostce organizacyjnej.
Hasła Może zawierać dowolną kombinację znaków. Minimalna liczba znaków to 8. Maksymalna długość to 100 znaków.
Zdjęcia W tej wersji interfejsu API zdjęcie to najnowsze zdjęcie profilowe użytkownika w Google.
Nazwy użytkownika Nazwy użytkowników mogą zawierać litery (a–z), cyfry (0–9), łączniki (-), podkreślenia (_), a Google Workspace rozpoznaje kropki (.). To nie to samo co Gmail. Nazwa użytkownika nie może zawierać znaku równości (=), nawiasów (<,>) ani więcej niż jednej kropki (.) pod rząd. Więcej informacji znajdziesz w Centrum pomocy dla administratorów.
Nazwy użytkowników, zmienianie nazw Po zmianie nazwy Google Hangouts odrzuca wszystkie zapamiętane zaproszenia na czat. Użytkownik musi ponownie poprosić o zgodę na czatowanie ze znajomymi. Stara nazwa użytkownika zostanie zachowana jako alias e-mail, aby zapewnić nieprzerwane dostarczanie poczty w przypadku ustawień przekierowania poczty elektronicznej. Nie będzie ona dostępna jako nowa nazwa użytkownika. Więcej informacji na temat wpływu zmiany nazw użytkowników znajdziesz w Centrum pomocy dla administratorów. Wykonaj operację Usuń alias użytkownika, aby usunąć alias e-mail po zmianie nazwy.
Użytkownicy w wielu domenach Konto Google Workspace może zawierać dowolną z Twoich domen. Na koncie z wieloma domenami użytkownicy w jednej domenie mogą udostępniać usługi użytkownikom w innych domenach. Kilka komponentów domeny:
  • Domena podstawowa – domena podstawowa Twojego konta jest domeną administratora, który zaakceptował Warunki korzystania z usługi Google Workspace. Ta domena znajduje się na poziomie konta w jednostce organizacyjnej najwyższego poziomu. Podczas rejestrowania konta Google Workspace zalecamy ustawienie domeny firmowej jako domeny podstawowej oraz zarezerwowanie innych domen na potrzeby specjalistycznych zastosowań, takich jak wdrożenia pilotażowe i testowanie.
    • Wszyscy superadministratorzy mogą zarządzać pełnym kontem.
    • Interfejs API nie może zmienić ani przenieść domeny podstawowej konta Google Workspace. Interfejs API może jednak zmienić nazwę konta użytkownika, zmieniając jego adres e-mail z jednej domeny na inną.
    • W przypadku kont Google Workspace masz 21 dni na potwierdzenie własności domeny podstawowej. W przypadku dodatkowych domen musisz zweryfikować swoje prawo własności do domeny, zanim użyjesz jej jako podstawowego adresu e-mail użytkownika. W takich przypadkach 21-dniowy okres prolongaty nie ma zastosowania.
    • W tej wersji interfejsu API ustawienia domeny podstawowej dotyczą wszystkich domen powiązanych z kontem z wyjątkiem dostępu użytkowników do usług Google Workspace.
  • Dodatkowe domeny kont – po utworzeniu domeny podstawowej i skonfigurowaniu konta możesz dodać do konta kolejne domeny. W przypadku dodatkowych domen zweryfikuj swoje prawo własności podczas konfigurowania tej domeny, a zanim użyjesz jej jako podstawowego adresu e-mail użytkownika.
  • Domena domowa użytkownika – domena używana w podstawowym adresie e-mail użytkownika jest jego domeną domową. Ta domena może być dowolną domeną na koncie, w tym domeną podstawową.
Najnowsze informacje o ograniczeniach dotyczących wielu domen znajdziesz w artykule o ograniczeniach dotyczących wielu domen. Obejmuje to informacje dotyczące aliasów domen, scalania kont itp.
Ostrzeżenia, członkowie grupy GROUP_CANNOT_CONTAIN_CYCLE – interfejs API nie zezwala na cykl członkostwa w grupie. Jeśli na przykład grupa1 jest członkiem grupy2, to grupa2 nie może być członkiem grupy1.