Directory API: Limits and Quotas

Durch Limits und Kontingente wird die Google-Infrastruktur vor automatisierten Prozessen geschützt, die die Directory API auf unangemessene Weise verwenden. Übermäßige Anfragen von einer API können auf einen harmlosen Tippfehler oder auf ein ineffizient konzipiertes System zurückzuführen sein, das unnötige API-Aufrufe ausführt. Unabhängig von der Ursache ist es für die allgemeine Integrität des Google Workspace-Systems erforderlich, den Traffic von einer bestimmten Quelle zu blockieren, sobald er ein bestimmtes Niveau erreicht. So wird sichergestellt, dass die Handlungen eines Entwicklers keine negativen Auswirkungen auf die gesamte Community haben.

Sollte Ihre API-Anfrage fehlschlagen, gibt die API einen HTTP-Statuscode und eine Fehlerursache zurück. Außerdem enthält der Text der Antwort eine detaillierte Beschreibung der Fehlerursache.

In der folgenden Liste finden Sie die möglichen 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 Nutzer-Ratenbegrenzung überschritten wurde. Der in der Google Cloud Console festgelegte Standardwert beträgt 2.400 Abfragen pro Minute pro Nutzer pro Google Cloud-Projekt. Erhöhen Sie die Limits pro Nutzer auf der Seite „Admin SDK API-Kontingente“ Ihres Google Cloud-Projekts oder verringern Sie die Rate, mit der Sie die Anfragen senden, mithilfe des exponentiellen Backoffs.
403 quotaExceeded Gibt an, dass das Limit für gleichzeitige Anfragen für einen bestimmten Vorgang erreicht wurde. Wiederholen Sie den Vorgang mit exponentiellem Backoff. Sie müssen die Rate verringern, mit der Sie die Anfragen senden.
429 rateLimitExceeded Gibt an, dass das Limit für gleichzeitige Anfragen für einen bestimmten Vorgang erreicht wurde. Wiederholen Sie den Vorgang mit exponentiellem Backoff. Sie müssen die Rate 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 zunehmenden Zeitraum wiederholt. Dies ist eine Standardstrategie zur Fehlerbehandlung für Netzwerkanwendungen. Durch die Verwendung des exponentiellen Backoffs wird die Bandbreitennutzung effizienter, die Anzahl der für eine erfolgreiche Antwort erforderlichen Anfragen reduziert und der Durchsatz von Anfragen in gleichzeitigen Umgebungen maximiert.

Der Ablauf für die Implementierung eines einfachen exponentiellen Backoffs sieht so aus:

  1. Anfrage an die API stellen
  2. Sie erhalten eine Fehlerantwort mit einem Fehlercode, der einen Wiederholungsversuch ermöglicht.
  3. 1 Sekunde + random_number_milliseconds Sekunden warten
  4. Anfrage wiederholen
  5. Sie erhalten eine Fehlerantwort mit einem Fehlercode, der einen Wiederholungsversuch zulässt.
  6. Warte 2 Sekunden + random_number_milliseconds Sekunden.
  7. Anfrage wiederholen
  8. Sie erhalten eine Fehlerantwort mit einem Fehlercode, der einen Wiederholungsversuch zulässt.
  9. 4 Sekunden + random_number_milliseconds Sekunden warten
  10. Anfrage wiederholen
  11. Sie erhalten eine Fehlerantwort mit einem Fehlercode, der einen Wiederholungsversuch zulässt.
  12. 8 Sekunden + random_number_milliseconds Sekunden warten
  13. Anfrage wiederholen
  14. Sie erhalten eine Fehlerantwort mit einem Fehlercode, der einen Wiederholungsversuch zulässt.
  15. 16 Sekunden + random_number_milliseconds Sekunden warten
  16. Anfrage wiederholen
  17. Wenn Sie weiterhin eine Fehlermeldung erhalten, brechen Sie den Vorgang ab 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 monoton steigende Ganzzahl ist, die anfänglich als 0 definiert ist. n wird bei jeder Iteration (jeder Anfrage) um 1 erhöht.

Der Algorithmus ist so eingerichtet, dass er endet, wenn n = 5. Diese Obergrenze dient nur dazu, zu verhindern, dass Clients unendlich viele Wiederholungsversuche ausführen. Sie führt zu einer Gesamtverzögerung von etwa 32 Sekunden, bevor eine Anfrage als „nicht behebbarer Fehler“ eingestuft wird. Ihr API-Client kann bei Bedarf eine höhere Anzahl von Versuchen implementieren.

API-Limits und -Kontingente

API-Limitkategorien Limits
Nutzer erstellen Mit der Directory API können Sie nicht mehr als 10 Nutzer pro Domain und Sekunde erstellen.
Nutzer löschen Mit der Directory API können Sie pro Domain und Sekunde bis zu 5 Nutzer löschen. Dies ist ein Limit für Backend-Dienste pro Domain, das in den Projektkontingenten der Google Cloud Console nicht angepasst werden kann. Achten Sie beim Senden von Batchanfragen darauf, dass die Gesamtzahl der Vorgänge über alle Batches hinweg unter 5 Abfragen pro Sekunde (QPS) bleibt.
Gruppenmitglieder löschen Mit der Directory API können Sie pro Domain und Sekunde bis zu 30 Gruppenmitglieder löschen. Dies ist ein Limit für Backend-Dienste pro Domain, das in den Projektkontingenten der Google Cloud Console nicht angepasst werden kann. Achten Sie beim Senden von Batchanfragen darauf, dass die Gesamtzahl der Vorgänge über alle Batches hinweg unter 30 Abfragen pro Sekunde (QPS) bleibt.
Gruppe wurde einer anderen Gruppe als Mitglied hinzugefügt Es kann bis zu 10 Minuten dauern, bis die Mitglieder der Untergruppe 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 ausführen:

  • 20 Aktionsanfragen pro Sekunde.
  • 20 Löschanfragen pro Sekunde.
  • 10 GET-Anfragen pro Sekunde.
  • 10 Listenanfragen pro Sekunde.
Nutzer umbenennen Es kann bis zu 10 Minuten dauern, bis die Änderungen auf alle Dienste übertragen werden. Bevor Sie einen Nutzer umbenennen, sollten Sie ihn von 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 oder aktualisieren.
  • Die Hierarchie der Organisationseinheiten des Kunden ist auf 35 Ebenen beschränkt.
  • Die Gesamtzahl der Organisationseinheiten pro Kunde darf 40.000 nicht überschreiten.
API-Kontingentkategorien Kontingente
Chrome-Geräte annotatedLocation, max. Zeichen Die maximale Anzahl von Zeichen für die Standortinformationen eines Geräts beträgt 200.
Chrome-Geräte notes, max. Zeichen Die maximale Anzahl von Zeichen für die Notizen zu einem Gerät beträgt 500.
Chrome-Geräte, maximal user Zeichen Der Name eines Gerätenutzers darf maximal 100 Zeichen lang sein.
Domain-Aliasse, maximal Die maximale Anzahl von Domain-Aliassen beträgt 20.
Gruppen, Beschreibung Die maximale Anzahl von Zeichen in einer Beschreibung beträgt 4.096.
Gruppen pro Konto Bei einem Konto der früheren, kostenlosen Version der G Suite ist die Anzahl der Gruppen auf 10 beschränkt. In anderen Versionen gibt es keine Beschränkung für die Anzahl der Gruppen.
Gruppen, Mitglieder pro Gruppe Mit einem Konto für die alte kostenlose Version der G Suite kann eine Gruppe bis zu 100 Mitglieder haben. In anderen Versionen gibt es keine Beschränkung für die Anzahl der Mitglieder einer Gruppe. Informationen zu den Limits für Gruppenmitgliedschaften pro Nutzer finden Sie im Hilfeartikel Gruppenrichtlinien und ‑beschränkungen.
Abfragestring „maxResults“ Die API gibt Folgendes zurück:
  • Chrome und Mobilgeräte: Standardmäßig 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 und maximal 500 Einträge pro Seite.
Für die Ressourcen „Nutzer-Alias“ und „Organisationseinheit“ wird keine Antwortpaginierung verwendet. Alle primären E-Mail-Adressen der Nutzer werden in alphabetischer Reihenfolge zurückgegeben. Bei der Reihenfolge der Antwort wird die Groß-/Kleinschreibung nicht berücksichtigt.
Mehrere Domains, maximale Anzahl von Domains, die in einem Konto zulässig sind 600 (1 primäre Domain + 599 zusätzliche Domains)
Organisationseinheit, maximale Anzahl von Nutzern, die gleichzeitig verschoben werden können Es können 20 Nutzer gleichzeitig verschoben werden. Außerdem müssen die primären E‑Mail-Adressen der Nutzer bereits im Konto vorhanden sein.
Nutzer-Aliasse Die Gesamtzahl der zulässigen Aliasse pro Nutzerkonto beträgt 30.
Nutzer-Aliasse, die einen gelöschten Alias verwenden Ein gelöschter Nutzer-Alias kann sofort wieder verwendet werden.

Andere Arten von Limits Einschränkungen und Richtlinien
Abrechnung und Erstellung von Nutzern Wenn Sie Nutzer mit einem flexiblen Tarif für Google Workspace über diese API erstellen, hat dies finanzielle Auswirkungen und führt zu Kosten für Ihr Kundenabrechnungskonto. Wenn Sie beispielsweise den flexiblen Tarif für Google Workspace nutzen und 10 Nutzer erstellen, werden Ihrem Konto die Kosten für 10 Google Workspace-Lizenzen anteilig ab dem Zeitpunkt der Erstellung in Rechnung gestellt. Wenn Sie einen Jahrestarif haben, haben Sie sich bereits verpflichtet, für eine bestimmte Anzahl von Lizenzen im Voraus zu bezahlen. Sie können nur so viele Nutzer erstellen, wie Sie zugesagt haben. Weitere Informationen zu Preismodellen und 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), Zahlen (0–9), Bindestriche (-), Schrägstriche (/) und Punkte (.) enthalten. Weitere Informationen zu den Regeln für die Verwendung von Zeichen finden Sie in der Hilfe für Administratoren.
Gruppen löschen Durch das Löschen einer Gruppe werden die Nutzerkonten der Gruppenmitglieder nicht gelöscht.
Änderung der E-Mail-Adresse von Gruppen und Gruppenmitgliedern In dieser Version der API kann die E-Mail-Adresse einer Gruppe geändert werden, bevor der Google Workspace-Dienst aktiviert wird. In der Admin-Konsole können Sie die E-Mail-Adresse eines Gruppenmitglieds ändern. Nach der Änderung werden die Änderungen der E-Mail-Adresse automatisch in der API übernommen.
Gruppen, Einstellungen Zugriffseinstellungen, Freigabeoptionen, Monitoring und Diskussionsarchiv für Gruppen werden über die Admin-Konsole verwaltet. Weitere Informationen zu den 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 in den Hilfeartikeln Sendebeschränkungen für E-Mails und Vermeiden, dass E-Mails an Gmail-Nutzer blockiert oder an den Spamordner gesendet werden.
Gruppen, Senden von Unzustellbarkeitsnachrichten Unzustellbarkeitsnachrichten (Non-Delivery Receipts, NDR) können nicht an Gruppen gesendet oder weitergeleitet werden.
Von Nutzern erstellte Gruppen, Einschränkungen Informationen zu den Limits für von Nutzern erstellte Gruppen finden Sie in der Admin-Hilfe.
Organisationseinheit, Dienste aktivieren/deaktivieren In der Admin-Konsole können Sie Dienste für eine Organisationseinheit aktivieren und deaktivieren.
Passwörter Kann eine beliebige Kombination von Zeichen enthalten. Mindestens 8 Zeichen erforderlich. Die maximale Länge beträgt 100 Zeichen.
Fotos In dieser Version der API ist ein Foto das aktuelle Google-Profilbild des Nutzers.
Nutzernamen Nutzernamen können Buchstaben (a–z), Zahlen (0–9), Bindestriche (-) und Unterstriche (_) enthalten. Google Workspace erkennt auch Punkte (.). Das ist bei Gmail anders. Ein Nutzername darf kein Gleichheitszeichen (=), keine spitzen Klammern (<,>) und nicht mehr als einen Punkt (.) nacheinander enthalten. Weitere Informationen finden Sie in der Hilfe für Administratoren.
Nutzernamen, Umbenennen In Google Hangouts werden alle gespeicherten Chateinladungen nach dem Umbenennen verworfen. Der Nutzer muss die Berechtigung zum Chatten mit Freunden noch einmal anfordern. Der alte Nutzername wird als E‑Mail-Alias beibehalten, damit E‑Mails auch bei E‑Mail-Weiterleitungseinstellungen weiterhin zugestellt werden. Er kann nicht als neuer Nutzername verwendet werden. Wichtige Informationen zu den Auswirkungen der Umbenennung von Nutzern finden Sie in der Admin-Hilfe. Verwenden Sie den Vorgang Alias eines Nutzers löschen, um den E-Mail-Alias nach dem Umbenennen 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 mit Nutzern in anderen Kontodomains teilen. Komponenten für mehrere Domains:
  • Primäre Domain: Die primäre Domain Ihres Kontos ist die Domain des Administrators, der 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, Ihre geschäftliche Domain als primäre Domain zu verwenden und Ihre 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 nicht ändern oder verschieben. Mit der API kann jedoch das Konto eines Nutzers umbenannt werden, sodass die E-Mail-Adresse von einer Domain in eine andere geändert wird.
    • Bei Google Workspace-Konten haben Sie 21 Tage Zeit, um Ihre Inhaberschaft der primären Domain zu bestätigen. Bei zusätzlichen Domains müssen Sie die Domaininhaberschaft bestätigen, bevor Sie die Domain für die 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 eingerichtet und Ihr Konto erstellt haben, können Sie dem Konto weitere Domains hinzufügen. Bei zusätzlichen Domains müssen Sie Ihre Inhaberschaft bestätigen, wenn Sie diese Domain einrichten und bevor Sie die Domain für die 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. Diese Domain kann eine beliebige Domain im Konto sein, einschließlich der primären Domain.
Die aktuellen Einschränkungen für mehrere Domains finden Sie unter Einschränkungen bei mehreren Domains. Dazu gehören Informationen zu Domain-Aliassen, zur Kontozusammenführung usw.
Warnungen, Gruppenmitglieder GROUP_CANNOT_CONTAIN_CYCLE: Die API lässt keine Zyklen in Gruppenmitgliedschaften zu. Wenn beispielsweise Gruppe 1 Mitglied von Gruppe 2 ist, kann Gruppe 2 nicht Mitglied von Gruppe 1 sein.