Directory API: Limits und Kontingente

Limits und Kontingente schützen die Google-Infrastruktur vor einem automatisierten Prozess, bei dem die Directory API auf unangemessene Weise verwendet wird. Übermäßig viele Anfragen von einer API können auf einen harmlosen Tippfehler zurückzuführen sein oder auf ein ineffizient gestaltetes System zurückzuführen sein, das unnötige API-Aufrufe durchführt. Unabhängig von der Ursache ist es für den Gesamtzustand des Google Workspace-Systems erforderlich, den Traffic von einer bestimmten Quelle zu blockieren, sobald dieser ein bestimmtes Niveau erreicht. Es wird sichergestellt, dass die Aktionen eines Entwicklers keine negativen Auswirkungen auf die gesamte Community haben.

Für den unwahrscheinlichen Fall, dass Ihre API-Anfrage fehlschlägt, gibt die API einen HTTP-Statuscode und die Ursache für den Fehler zurück. Darüber hinaus enthält der Text der Antwort eine detaillierte Beschreibung der Fehlerursache.

Die folgende Liste enthält mögliche Fehlercodes, Gründe, entsprechende Beschreibungen und empfohlene Maßnahmen für Fehler, die durch das Erreichen von Kontingentlimits verursacht werden.

Code Grund Beschreibung Empfohlene Maßnahme
403 userRateLimitExceeded Gibt an, dass die Ratenbegrenzung für Nutzer überschritten wurde. Der in der Google Cloud Console festgelegte Standardwert ist 2.400 Abfragen pro Minute,Nutzer und Google Cloud-Projekt. Erhöhen Sie die Limits pro Nutzer auf der Seite Admin SDK API-Kontingente in Ihrem Google Cloud-Projekt oder verlangsamen Sie die Geschwindigkeit, mit der Anfragen mit dem exponentiellen Backoff gesendet werden.
403 quotaExceeded Gibt an, dass das Limit für gleichzeitige Anfragen für einen bestimmten Vorgang erreicht wurde. Wiederholen Sie den Vorgang mit dem exponentiellen Backoff. Sie müssen die Geschwindigkeit, mit der Sie die Anfragen senden, verringern.
429 rateLimitExceeded Gibt an, dass das Limit für gleichzeitige Anfragen für einen bestimmten Vorgang erreicht wurde. Wiederholen Sie den Vorgang mit dem exponentiellen Backoff. Sie müssen die Rate verlangsamen, mit der Sie die Anfragen senden. Dieses Limit gilt pro Google Workspace-Konto, nicht pro API-Client oder Nutzer. Dieses Limit kann nicht erhöht werden.

Exponentiellen Backoff implementieren

Ein exponentieller Backoff ist der Prozess, bei dem ein Client eine fehlgeschlagene Anfrage regelmäßig wiederholt, während er immer länger wird. Es ist eine standardmäßige Fehlerbehandlungsstrategie für Netzwerkanwendungen. Der exponentielle Backoff erhöht die Effizienz der Bandbreitennutzung, reduziert die Anzahl der Anfragen für eine erfolgreiche Antwort und maximiert den Durchsatz von Anfragen in Umgebungen, die gleichzeitig ausgeführt werden.

Der Ablauf zur Implementierung eines einfachen exponentiellen Backoffs sieht so aus:

  1. Anfrage an die API stellen
  2. Sie erhalten eine Fehlerantwort mit einem wiederholbaren Fehlercode
  3. 1 Sek. + random_number_milliseconds Sekunden warten
  4. Anfrage wiederholen
  5. Sie erhalten eine Fehlerantwort mit einem wiederholbaren Fehlercode
  6. 2 Sek. + random_number_milliseconds Sekunden warten
  7. Anfrage wiederholen
  8. Sie erhalten eine Fehlerantwort mit einem wiederholbaren Fehlercode
  9. 4 Sek. + random_number_milliseconds Sekunden warten
  10. Anfrage wiederholen
  11. Sie erhalten eine Fehlerantwort mit einem wiederholbaren Fehlercode
  12. 8 Sek. + random_number_milliseconds Sekunden warten
  13. Anfrage wiederholen
  14. Sie erhalten eine Fehlerantwort mit einem wiederholbaren Fehlercode
  15. 16 Sek. + random_number_milliseconds Sekunden warten
  16. Anfrage wiederholen
  17. Wenn Sie weiterhin einen Fehler erhalten, beenden Sie den Vorgang und protokollieren Sie ihn.

Im obigen Ablauf ist random_number_milliseconds eine zufällige Anzahl von Millisekunden, die kleiner oder gleich 1.000 ist. Dies ist erforderlich, um bestimmte Sperrfehler in einigen gleichzeitigen Implementierungen zu vermeiden. random_number_milliseconds muss nach jeder Wartezeit neu definiert werden.

Hinweis: Die Wartezeit beträgt immer (2 ^ n) + random_number_milliseconds, wobei n eine monoton ansteigende Ganzzahl ist, die anfänglich als 0 definiert ist. n wird bei jeder Iteration (jede Anfrage) um 1 erhöht.

Der Algorithmus ist so eingerichtet, dass er endet, wenn n = 5. Diese Obergrenze verhindert nur, dass Clients unbegrenzte Wiederholungen ausführen. Sie führt zu einer Gesamtverzögerung von etwa 32 Sekunden, bevor eine Anfrage als "nicht behebbarer Fehler" gilt. Ihr API-Client kann bei Bedarf eine größere Anzahl von Versuchen implementieren.

API-Limits und Kontingente

API-Grenzwertkategorien Limits
Nutzer erstellen Mit der Directory API können Sie nicht mehr als zehn Nutzer pro Domain und Sekunde erstellen.
Gruppe wurde einer anderen Gruppe als Mitglied hinzugefügt Es kann bis zu 10 Minuten dauern, bis die Mitglieder der untergeordneten Gruppe als Mitglieder der übergeordneten Gruppe angezeigt werden. Dieses Limit kann sich je nach Systemkapazität ändern.
Mobilgeräte

Mit der Directory API können Sie Folgendes tun:

  • 20 Aktionsanfragen pro Sekunde
  • 20 Löschanfragen pro Sekunde
  • 10 „get“-Anfragen pro Sekunde.
  • 10 Listenanfragen pro Sekunde.
Umbenennen von Nutzern Es kann bis zu 10 Minuten dauern, bis die Änderungen für alle Dienste wirksam werden. Bevor Sie einen Nutzer umbenennen, wird empfohlen, ihn aus allen Browsersitzungen und Diensten abzumelden. Weitere Informationen finden Sie unter Nutzer aktualisieren.
Organisationseinheiten erstellen/aktualisieren
  • Mit der Directory API können Sie nicht mehr als eine Organisationseinheit pro Kunde und Sekunde erstellen/aktualisieren.
  • Die Hierarchie der Organisationseinheiten des Kunden ist auf 35 Tiefenebenen beschränkt.
  • Die Gesamtzahl der Organisationseinheiten pro Kunde darf 40.000 nicht überschreiten.
API-Kontingentkategorien Kontingente
Chrome-Geräte: annotatedLocation, max. Zeichen Die Standortinformationen eines Geräts können maximal 200 Zeichen enthalten.
Chrome-Geräte: notes, max. Zeichen Für Notizeninformationen auf einem Gerät sind maximal 500 Zeichen zulässig.
Chrome-Geräte, maximal user Zeichen Der Name eines Gerätenutzers darf maximal 100 Zeichen enthalten.
Domain-Aliasse, maximal Es sind maximal 20 Domain-Aliasse möglich.
Gruppen, Beschreibung Die maximale Anzahl der Zeichen für eine Beschreibung beträgt 4.096.
Gruppen, pro Konto Bei Konten der alten, kostenlosen Version der G Suite ist die Anzahl der Gruppen auf zehn begrenzt. In anderen Versionen ist die Anzahl der Gruppen nicht begrenzt.
Gruppen, Mitglieder pro Gruppe Mit einem Konto der alten, kostenlosen Version der G Suite kann eine Gruppe bis zu 100 Mitglieder haben. In anderen Versionen ist die Anzahl der Mitglieder einer Gruppe nicht begrenzt. Informationen zu den Beschränkungen für die Gruppenmitgliedschaft pro Nutzer finden Sie unter Gruppenrichtlinien und -beschränkungen.
Abfragestring „maxResults“ Die API gibt Folgendes zurück:
  • Chrome und Mobilgeräte: Standardeinstellung und maximal 100 Einträge pro Seite.
  • Gruppen und Gruppenmitglieder: Standardmäßig und maximal 200 Einträge pro Seite.
  • Nutzer: Der Standardwert beträgt 100 Einträge und maximal 500 Einträge pro Seite.
Der Nutzeralias und die Ressourcen der Organisationseinheit verwenden keine Antwortpaginierung. Alle primären E-Mail-Adressen von Nutzern werden in alphabetischer Reihenfolge zurückgegeben. Bei der Reihenfolge der Antworten wird die Groß-/Kleinschreibung nicht berücksichtigt.
Mehrere Domains, maximal zulässige Anzahl von Domains pro Konto 600 (1 primäre Domain + 599 zusätzliche Domains)
Organisationseinheit, maximale Anzahl von Nutzern gleichzeitig verschoben Es können 20 Nutzer gleichzeitig verschoben werden. Außerdem müssen die primären E-Mail-Adressen des Nutzers bereits im Konto vorhanden sein.
Nutzeraliasse Pro Nutzerkonto sind maximal 30 Aliasse zulässig.
Nutzeraliasse mit einem gelöschten Alias Ein gelöschter Nutzer-Alias kann sofort wieder verwendet werden.

Andere Arten von Beschränkungen Beschränkungen und Richtlinien
Abrechnung und Erstellung von Nutzern Wenn Sie Nutzer mit einem flexiblen Tarif für Google Workspace erstellen, hat das Erstellen von Nutzern, die diese API verwenden, Auswirkungen auf die Einnahmen. Dadurch fallen Gebühren für das Rechnungskonto des Kunden an. Wenn Sie beispielsweise einen flexiblen Tarif für Google Workspace haben und 10 Nutzer erstellen, fallen Kosten für die Veröffentlichung von 10 Google Workspace-Lizenzen an Ihr Konto an. Diese werden anteilig ab dem Zeitpunkt der Erstellung berechnet. Wenn Sie einen Jahrestarif haben, wären Sie bereits verpflichtet, für eine bestimmte Anzahl von Lizenzen im Voraus zu zahlen, und Sie können nur so viele Nutzer erstellen, wie Sie sich verpflichten. Weitere Informationen zu Tarifen und Ihrem Rechnungskonto finden Sie in der Hilfe für Administratoren.
Vor- und Nachnamen Vor- und Nachnamen dürfen maximal 40 Zeichen lang sein. Sie unterstützen Unicode/UTF-8-Zeichen und können Leerzeichen, Buchstaben (a–z), Ziffern (0–9), Bindestriche (-), Schrägstriche (/) und Punkte (.) enthalten. Weitere Informationen zu den Regeln für die Verwendung von Zeichen finden Sie in der Admin-Hilfe.
Gruppen, wird gelöscht Durch das Löschen einer Gruppe werden die Nutzerkonten des Gruppenmitglieds nicht gelöscht.
Gruppen und Gruppenmitglieder, Änderung der E-Mail-Adresse In dieser Version der API kann die E-Mail-Adresse einer Gruppe geändert werden, bevor der Google Workspace-Dienst aktiviert wird. Über die Admin-Konsole können Sie die E-Mail-Adresse eines Gruppenmitglieds ändern. Nach der Änderung werden die Änderungen an der E-Mail-Adresse automatisch in der API übernommen.
Gruppen, Einstellungen Zugriffseinstellungen, Freigabeoptionen, Monitoring und das Diskussionsarchiv für Gruppen werden über die Admin-Konsole verwaltet. Weitere Informationen zu Gruppeneinstellungen finden Sie in der Hilfe für Administratoren.
Gruppen, Nachrichten senden Um Spam und E-Mail-Missbrauch zu verhindern, beschränkt Google die Anzahl der Nachrichten, die Sie auf einmal an externe Empfänger senden können. Wenn Sie eine Nachricht an eine Gruppe senden, wird jedes externe Mitglied als ein Empfänger gezählt. Weitere Informationen finden Sie unter E-Mail-Sendebeschränkungen und Verhindern, dass E-Mails an Gmail-Nutzer blockiert oder an den Spamordner gesendet werden .
Gruppen, NDR-Nachrichten werden gesendet Unzustellbarkeitsnachrichten (Non-Delivery Lesebestätigungen, NDRs) können nicht an eine Gruppe gesendet oder weitergeleitet werden.
Von Nutzern erstellte Gruppen, Einschränkungen Informationen zu den Beschränkungen für von Nutzern erstellte Gruppen finden Sie in der Hilfe für Administratoren.
Organisationseinheit, Dienste aktivieren/deaktivieren In der Admin-Konsole können Sie die Aktivierung und Deaktivierung von Diensten für eine Organisationseinheit verwalten.
Passwörter Kann eine beliebige Kombination von Zeichen enthalten. Es sind mindestens 8 Zeichen erforderlich. Die maximale Länge beträgt 100 Zeichen.
Fotos In dieser Version der API ist das Foto das neueste Google-Profilbild des Nutzers.
Nutzernamen Nutzernamen können Buchstaben (a–z), Ziffern (0–9), Bindestriche (-), Unterstriche (_) enthalten. In Google Workspace werden Punkte oder Punkte (.) erkannt. Das ist nicht dasselbe wie Gmail. Ein Nutzername darf keine Gleichheitszeichen (=), Klammern (<,>) oder mehrere Punkte (.) hintereinander enthalten. Weitere Informationen finden Sie in der Hilfe für Administratoren.
Nutzernamen, Umbenennung Google Hangouts verwirft alle gespeicherten Chateinladungen nach der Umbenennung. Der Nutzer muss erneut eine Berechtigung anfordern, um mit Freunden chatten zu können. Der alte Nutzername wird als E-Mail-Alias beibehalten, um bei den Einstellungen für die E-Mail-Weiterleitung eine kontinuierliche E-Mail-Zustellung zu gewährleisten. Er ist nicht als neuer Nutzername verfügbar. Weitere Informationen zu den Auswirkungen der Umbenennung von Nutzern finden Sie in der Hilfe für Administratoren. Verwenden Sie den Vorgang Nutzer-Alias löschen, um den E-Mail-Alias nach einer Umbenennung zu entfernen.
Nutzer in mehreren Domains Ein Google Workspace-Konto kann jede Ihrer Domains enthalten. In einem Konto mit mehreren Domains können Nutzer in einer Domain Dienste für Nutzer in anderen Kontodomains freigeben. Es gibt mehrere Domainkomponenten:
  • Primäre Domain: Die primäre Domain Ihres Kontos ist die Domain des Administrators, der die Vereinbarung über die Google Workspace-Nutzungsbedingungen akzeptiert hat. Diese Domain befindet sich auf Kontoebene in der obersten Organisationseinheit. Wenn Sie sich für ein Google Workspace-Konto registrieren, empfehlen wir Ihnen, Ihre Unternehmensdomain als primäre Domain zu verwenden und die anderen Domains für spezielle Zwecke wie Pilotprojekte und Tests zu reservieren.
    • Alle Super Admins können das gesamte Konto verwalten.
    • Die API kann die primäre Domain des Google Workspace-Kontos weder ändern noch verschieben. Die API kann jedoch das Konto eines Nutzers umbenennen, wobei die E-Mail-Adresse von einer Domain in eine andere geändert wird.
    • Bei Google Workspace-Konten haben Sie 21 Tage Zeit, um die Inhaberschaft der primären Domain zu bestätigen. Bei weiteren Domains müssen Sie Ihre Domaininhaberschaft bestätigen, bevor Sie die Domain als primäre E-Mail-Adresse eines Nutzers verwenden können. In diesen Fällen gilt der Kulanzzeitraum von 21 Tagen nicht.
    • In dieser Version der API gelten die Einstellungen der primären Domain für alle mit dem Konto verknüpften Domains mit Ausnahme des Nutzerzugriffs auf die Google Workspace-Dienste.
  • Zusätzliche Kontodomains – Nachdem Sie Ihre primäre Domain festgelegt und Ihr Konto eingerichtet haben, können Sie dem Konto weitere Domains hinzufügen. Bestätigen Sie Ihre Inhaberschaft für weitere Domains, wenn Sie diese Domain einrichten und bevor Sie die Domain als primäre E-Mail-Adresse eines Nutzers verwenden.
  • Heimdomain des Nutzers: Die in der primären E-Mail-Adresse eines Nutzers verwendete Domain ist die private Domain des Nutzers. Das kann eine beliebige Domain im Konto sein, auch die primäre Domain.
Die aktuellen Einschränkungen für mehrere Domains finden Sie unter Einschränkungen für mehrere Domains. Dazu gehören Informationen zu Domain-Aliassen, Kontenzusammenführung usw.
Warnungen, Gruppenmitglieder GROUP_CANNOT_CONTAIN_CYCLE: Die API lässt keinen Zyklus in Gruppenmitgliedschaften zu. Wenn z. B. „gruppe1“ Mitglied von „gruppe2“ ist, kann „gruppe2“ kein Mitglied von „gruppe1“ sein.