Directory API: Limits und Kontingente

Limits und Kontingente schützen die Google-Infrastruktur vor einem automatisierten Prozess, der die Directory API auf unangemessene Weise verwendet. Übermäßig viele Anfragen von einer API können durch einen harmlosen Tippfehler oder durch ein ineffizientes System, das unnötige API-Aufrufe durchführt, verursacht werden. Unabhängig von der Ursache ist es für den Gesamtzustand des Google Workspace-Systems notwendig, den Traffic von einer bestimmten Quelle zu blockieren, sobald er ein bestimmtes Niveau erreicht. Es wird sichergestellt, dass sich die Handlungen eines Entwicklers nicht negativ auf die gesamte Community auswirken.

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. Außerdem enthält der Antworttext eine detaillierte Beschreibung der Fehlerursache.

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

Code Grund Beschreibung Empfohlene Maßnahme
403 userRateLimit Überschritten Gibt an, dass die Ratenbegrenzung für Nutzer überschritten wurde. Der Standardwert in der Google Cloud Console beträgt 2.400 Abfragen pro Minute,Nutzer und Google Cloud-Projekt. Erhöhen Sie die Limits pro Nutzer auf der Admin SDK API-Kontingentseite Ihres Google Cloud-Projekts oder verlangsamen Sie die Geschwindigkeit, mit der Sie die Anfragen mithilfe des exponentiellen Backoffs senden.
403 quotaExceeded Gibt an, dass das Limit gleichzeitiger Anfragen für einen bestimmten Vorgang erreicht wurde. Wiederholen Sie den Vorgang mit dem exponentiellen Backoff. Sie müssen die Geschwindigkeit verringern, mit der Sie die Anfragen senden.
429 rateLimitExceeded Gibt an, dass das Limit gleichzeitiger Anfragen für einen bestimmten Vorgang erreicht wurde. Wiederholen Sie den Vorgang mit dem exponentiellen Backoff. Sie müssen die Geschwindigkeit verringern, 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

Exponentieller Backoff ist der Prozess, bei dem ein Client eine fehlgeschlagene Anfrage regelmäßig über einen längeren Zeitraum wiederholt. Es ist eine standardmäßige Fehlerbehandlungsstrategie für Netzwerkanwendungen. Der exponentielle Backoff erhöht die Effizienz der Bandbreitennutzung, reduziert die Anzahl der Anfragen, die für eine erfolgreiche Antwort erforderlich sind, und maximiert den Durchsatz von Anfragen in gleichzeitigen Umgebungen.

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 Sekunde + 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 eine Fehlermeldung erhalten, beenden Sie den Vorgang und protokollieren Sie den Fehler.

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 kontinuierlich 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 dient lediglich dazu, zu verhindern, dass Clients es unbegrenzt wiederholen. 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-Beschränkungen und -Kontingente

API-Grenzwertkategorien Einschränkungen
Nutzer erstellen Mit der Directory API können Sie nicht mehr als 10 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, sollten Sie ihn aus allen Browsersitzungen und Diensten abmelden. 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 begrenzt.
  • 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 Die Notizen zu einem Gerät können höchstens 500 Zeichen enthalten.
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 Zeichenanzahl 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 Ein 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 – Standard und maximal 100 Einträge pro Seite.
  • Gruppen und Gruppenmitglieder: Standardmäßig und maximal 200 Einträge pro Seite.
  • Nutzer: Standardmäßig 100 Einträge pro Seite und maximal 500 Einträge.
Für den Nutzeralias und die Ressourcen der Organisationseinheit wird keine Antwortpaginierung verwendet. 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 in einem Konto 600 (1 primäre Domain + 599 zusätzliche Domains)
Organisationseinheit, maximale Anzahl der Nutzer gleichzeitig verschoben 20 Nutzer können gleichzeitig verschoben werden. Außerdem müssen die primären E-Mail-Adressen des Nutzers bereits im Konto vorhanden sein.
Nutzeraliasse Für jedes Nutzerkonto sind maximal 30 Aliasse zulässig.
Nutzeralias mit gelöschtem Alias Ein gelöschter Nutzeralias kann sofort wieder verwendet werden.

Andere Arten von Limits Einschränkungen und Richtlinien
Abrechnung und Nutzererstellung Für Nutzer mit einem flexiblen Tarif für Google Workspace hat das Erstellen von Nutzern, die diese API verwenden, finanzielle Auswirkungen. Dadurch werden Ihrem Kundenrechnungskonto Gebühren in Rechnung gestellt. Wenn Sie beispielsweise einen flexiblen Tarif für Google Workspace haben und 10 Nutzer erstellen, werden ab dem Zeitpunkt der Erstellung anteilig Gebühren für 10 Google Workspace-Lizenzen an Ihr Konto gesendet. Wenn Sie einen Jahrestarif haben, hätten Sie sich bereits verpflichtet, im Voraus für eine bestimmte Anzahl von Lizenzen zu zahlen, und Sie können nur so viele Nutzer erstellen, wie von Ihrem Vertrag abgedeckt. Weitere Informationen zu Abrechnungstarifen und zu Ihrem Rechnungskonto finden Sie in der Hilfe für Administratoren.
Vor- und Nachname 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 Zeichennutzungsregeln finden Sie in der Hilfe für Administratoren.
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. Verwenden Sie die Admin-Konsole, um die E-Mail-Adresse eines Gruppenmitglieds zu ändern. Nach der Änderung werden die Änderungen der E-Mail-Adresse automatisch in der API übernommen.
Gruppen, Einstellungen Zugriffseinstellungen für Gruppen, Freigabeoptionen, Überwachung und das Diskussionsarchiv 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 gleichzeitig 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 Gmail-Sendebeschränkungen in der G Suite und im Hilfeartikel Vermeiden, dass E-Mails an Gmail-Nutzer blockiert oder an den Spamordner gesendet werden .
Gruppen, Senden von Unzustellbarkeitsnachrichten Unzustellbarkeitsnachrichten (Non-Delivery Empfangsbestätigungen, Unzustellbarkeitsnachrichten) können nicht an eine Gruppe gesendet oder weitergeleitet werden.
Von Nutzern erstellte Gruppen, Einschränkungen Informationen zu 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 das Aktivieren und Deaktivieren von Diensten für eine Organisationseinheit verwalten.
Passwörter Kann eine beliebige Kombination von Zeichen enthalten. Mindestens 8 Zeichen sind erforderlich. Die maximale Länge beträgt 100 Zeichen.
Fotos In dieser Version der API ist ein Foto das neueste Google-Profilbild des Nutzers.
Nutzernamen Nutzernamen dürfen Buchstaben (a–z), Ziffern (0–9), Bindestriche (-) und Unterstriche (_) enthalten. Außerdem werden in Google Workspace Punkte oder Punkte (.) erkannt. Das ist nicht dasselbe wie Gmail. Ein User-Name darf kein 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 die Berechtigung zum Chatten mit Freunden noch einmal anfordern. Der alte Nutzername wird als E-Mail-Alias beibehalten, um eine unterbrechungsfreie E-Mail-Zustellung bei Einstellungen für die E-Mail-Weiterleitung 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. Mit dem Vorgang Nutzer-Alias löschen können Sie den E-Mail-Alias nach der Umbenennung entfernen.
Nutzer in mehreren Domains Ein Google Workspace-Konto kann jede Ihrer Domains enthalten. In einem Konto mit mehreren Domains können Nutzer 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 zu den 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, sollten Sie Ihre Unternehmensdomain als primäre Domain verwenden und die anderen Domains für spezielle Zwecke wie Pilotprojekte und Tests reservieren.
    • Alle Poweruser können das gesamte Konto verwalten.
    • Die primäre Domain des Google Workspace-Kontos kann mit der API weder geändert noch verschoben werden. Die API kann jedoch das Konto eines Nutzers umbenennen, wobei die E-Mail-Adresse der Domain 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 die 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 Domains, die mit dem Konto verknüpft sind, mit Ausnahme des Nutzerzugriffs auf die Google Workspace-Dienste.
  • Zusätzliche Kontodomains: Nachdem Sie Ihre primäre Domain eingerichtet und Ihr Konto eingerichtet haben, können Sie dem Konto zusätzliche Domains hinzufügen. Bei weiteren Domains müssen Sie Ihre Inhaberschaft bestätigen, wenn Sie diese Domain einrichten und bevor Sie die Domain als primäre E-Mail-Adresse eines Nutzers verwenden.
  • Home-Domain des Nutzers – Die Domain, die in der primären E-Mail-Adresse eines Nutzers verwendet wird, ist die Home-Domain des Nutzers. Dabei kann es sich um eine beliebige Domain im Konto handeln, auch um die primäre Domain.
Die aktuellen Beschrä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.