Durch Limits und Kontingente wird die Google-Infrastruktur vor automatisierten Prozessen geschützt, die die Directory API auf unangemessene Weise verwenden. Eine übermäßige Anzahl von Anfragen von einer API kann durch einen harmlosen Tippfehler oder ein ineffizient gestaltetes System verursacht werden, das unnötige API-Aufrufe ausführt. Unabhängig von der Ursache ist es für den Gesamtzustand des Google Workspace-Systems wichtig, den Traffic von einer bestimmten Quelle zu blockieren, sobald er einen bestimmten Wert erreicht. So wird sichergestellt, dass die Aktionen eines Entwicklers keine negativen Auswirkungen auf die gesamte Community haben.
Im unwahrscheinlichen Fall, dass Ihre API-Anfrage fehlschlägt, gibt die API einen HTTP-Statuscode und einen Grund für den Fehler zurück. Außerdem enthält der Antworttext eine detaillierte Beschreibung der Ursache des Fehlers.
In der folgenden Liste finden Sie die möglichen Fehlercodes, Gründe, entsprechenden Beschreibungen und empfohlenen Maßnahmen für Fehler, die durch das Erreichen von Kontingentlimits verursacht werden.
| Code | Grund | Beschreibung | Empfohlene Maßnahme |
|---|---|---|---|
| 403 | userRateLimitExceeded | Gibt an, dass das Nutzer-Ratenlimit überschritten wurde. Der in der Google Cloud Console festgelegte Standardwert beträgt 2.400 Anfragen pro Minute pro Nutzer und Google Cloud-Projekt. | Erhöhen Sie die Limits pro Nutzer auf der Seite Admin SDK API Quotas Ihres Google Cloud-Projekts oder verlangsamen Sie die Rate, mit der Sie die Anfragen senden, indem Sie exponentielles Backoff verwenden. |
| 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, mit der Sie die Anfragen senden, verlangsamen. |
| 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, mit der Sie die Anfragen senden, verlangsamen. Dieses Limit gilt pro Google Workspace-Konto, nicht pro API-Client oder pro Nutzer. Dieses Limit kann nicht erhöht werden. |
Exponentiellen Backoff implementieren
Exponentieller Backoff ist der Prozess, bei dem ein Client eine fehlgeschlagene Anfrage über einen immer länger werdenden Zeitraum periodisch wiederholt. Es handelt sich um eine Standardstrategie zur Fehlerbehebung für Netzwerkanwendungen. Bei richtigem Einsatz erhöht der exponentielle Backoff die Effizienz der Bandbreitennutzung, verringert die Anzahl der Anfragen, die für den Erhalt einer erfolgreichen Antwort erforderlich sind, und maximiert den Durchsatz von Anfragen in Umgebungen mit Gleichzeitigkeit.
Der Ablauf für das Implementieren eines einfachen exponentiellen Backoffs sieht so aus.
- Anfrage an die API stellen
- Fehlerantwort mit einem wiederholbaren Fehlercode erhalten
- Warte 1 Sekunde +
random_number_millisecondsSekunden. - Anfrage wiederholen
- Fehlerantwort mit einem wiederholbaren Fehlercode erhalten
- 2 Sekunden +
random_number_millisecondsSekunden warten - Anfrage wiederholen
- Fehlerantwort mit einem wiederholbaren Fehlercode erhalten
- Warte 4 Sekunden +
random_number_millisecondsSekunden - Anfrage wiederholen
- Fehlerantwort mit einem wiederholbaren Fehlercode erhalten
- Warte 8 Sekunden +
random_number_millisecondsSekunden - Anfrage wiederholen
- Fehlerantwort mit einem wiederholbaren Fehlercode erhalten
- Warte 16 Sekunden +
random_number_millisecondsSekunden. - Anfrage wiederholen
- Wenn Sie weiterhin eine Fehlermeldung erhalten, beenden Sie den Vorgang und protokollieren Sie den Fehler.
Im oben beschriebenen Ablauf steht random_number_milliseconds für eine zufällige Anzahl von Millisekunden, deren Wert größer 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 gleichförmig ansteigende Ganzzahl ist, die anfänglich auf 0 gesetzt 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 soll nur verhindern, dass Clients unendlich oft wiederholt werden, und führt zu einer Verzögerung von insgesamt etwa 32 Sekunden, bevor eine Anfrage als „nicht behebbarer Fehler“ gilt. 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 pro Sekunde erstellen. |
| Gruppe als Mitglied einer anderen Gruppe 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 Kapazität des Systems ändern. |
| Mobilgeräte |
Mit der Directory API können Sie bis zu:
|
| Nutzer umbenennen | Es kann bis zu 10 Minuten dauern, bis die Änderungen in allen Diensten übernommen 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 |
|
| 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 Zeichenanzahl für die Notizen eines Geräts beträgt 500. |
Chrome-Geräte, maximal user Zeichen
|
Der Name eines Gerätenutzers darf maximal 100 Zeichen lang sein. |
| Maximale Anzahl von Domain-Aliassen | Die maximale Anzahl von Domainaliasen beträgt 20. |
| Gruppen, Beschreibung | Eine Beschreibung darf maximal 4.096 Zeichen lang sein. |
| Gruppen pro Konto | Mit einem Konto der früheren, kostenlosen Version der G Suite ist die Anzahl der Gruppen auf 10 begrenzt. Bei anderen Versionen gibt es keine Begrenzung der Anzahl der Gruppen. |
| Gruppen, Mitglieder pro Gruppe | Mit einem Konto der früheren kostenlosen G Suite-Version kann eine Gruppe bis zu 100 Mitglieder enthalten. Bei anderen Versionen gibt es keine Begrenzung der Mitgliederzahl einer Gruppe. Informationen zu den Beschränkungen für die Gruppenmitgliedschaft pro Nutzer finden Sie im Hilfeartikel Gruppenrichtlinien und -beschränkungen. |
| Abfragestring „maxResults“ | Die API gibt Folgendes zurück:
|
| Mehrere Domains, maximale Anzahl von Domains in einem Konto | 600 (1 primäre Domain + 599 zusätzliche Domains) |
| Organisationseinheit, maximale Anzahl der Nutzer, die gleichzeitig verschoben werden können | Es können jeweils 20 Nutzer verschoben werden. Die primären E‑Mail-Adressen des Nutzers müssen bereits im Konto vorhanden sein. |
| Nutzer-Aliasse | Die Gesamtzahl der Aliase, die für jedes Nutzerkonto zulässig sind, beträgt 30. |
| Nutzeraliasse mit einem gelöschten Alias | Ein gelöschter Nutzeralias kann sofort wieder verwendet werden. |
| Andere Arten von Limits | Einschränkungen und Richtlinien |
|---|---|
| Abrechnung und Nutzer erstellen | Wenn Sie Nutzer mit dieser API für Google Workspace-Nutzer mit einem flexiblen Tarif erstellen, hat dies finanzielle Auswirkungen und führt zu Gebühren für das Abrechnungskonto Ihres Kunden. Wenn Sie beispielsweise einen flexiblen Tarif für Google Workspace haben und 10 Nutzer erstellen, werden Ihrem Konto 10 Google Workspace-Lizenzen in Rechnung gestellt, anteilig ab dem Zeitpunkt der Erstellung. 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 Lizenzen haben. Weitere Informationen zu Abrechnungsmodellen und Ihrem Abrechnungskonto finden Sie in der Hilfe für Administratoren. |
| Vor- und Nachname | Vor- und Nachname 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 Administratorhilfe. |
| Gruppen löschen | Durch das Löschen einer Gruppe werden die Nutzerkonten der Gruppenmitglieder 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 berücksichtigt. |
| 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 Administratorhilfe. |
| 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 Vermeiden, dass E-Mails an Gmail-Nutzer blockiert oder an den Spamordner gesendet werden . |
| Gruppen, die Unzustellbarkeitsberichte senden | Unzustellbarkeitsnachrichten (non-delivery receipts – NDRs) können nicht an Gruppen gesendet oder weitergeleitet werden. |
| Von Nutzern erstellte Gruppen – Einschränkungen | Informationen zu Limits für nutzererstellte Gruppen finden Sie in der Administratorhilfe. |
| Organisationseinheit, Aktivieren/Deaktivieren von Diensten | In der Google Admin-Konsole können Sie Dienste für eine Organisationseinheit aktivieren und deaktivieren. |
| Passwörter | Kann eine beliebige Kombination aus Zeichen enthalten. Es sind 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 dürfen Buchstaben (a–z), Zahlen (0–9), Bindestriche (-) und Unterstriche (_) enthalten. Punkte (.) werden in Google Workspace erkannt, in Gmail jedoch nicht. Ein Nutzername darf kein Gleichheitszeichen (=), keine spitzen Klammern (<,>) und nicht mehrere Punkte (.) nacheinander enthalten. Weitere Informationen finden Sie in der Hilfe für Administratoren. |
| Nutzernamen, Umbenennung | Google Hangouts verwirft nach dem Umbenennen alle gespeicherten Chateinladungen. 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 im Falle von E-Mail-Weiterleitungseinstellungen zu gewährleisten. Er ist nicht als neuer Nutzername verfügbar. Wichtige Informationen zu den Auswirkungen der Umbenennung von Nutzern finden Sie in der Administratorhilfe. Verwenden Sie den Vorgang Alias eines Nutzers löschen, um den E-Mail-Alias nach der Umbenennung zu entfernen. |
| Nutzer in mehreren Domains | Ein Google Workspace-Konto kann alle Ihre Domains enthalten. In einem Konto mit mehreren Domains können Nutzer in einer Domain Dienste mit Nutzern in anderen Kontodomains teilen. Mehrere Domainkomponenten sind:
|
| Warnungen, Gruppenmitglieder | GROUP_CANNOT_CONTAIN_CYCLE: Die API lässt keine Zyklen in Gruppenmitgliedschaften zu. Wenn beispielsweise „group1“ Mitglied von „group2“ ist, kann „group2“ nicht Mitglied von „group1“ sein. |