Limits und Kontingente schützen die Google-Infrastruktur vor automatisierten Prozessen, die die Directory API auf unangemessene Weise verwenden. Übermäßige Anfragen an eine API können 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 einen funktionsfähigen Gesamtstatus des Google Workspace-Systems wichtig, den Traffic von einer bestimmten Quelle zu blockieren, sobald er einen bestimmten Wert erreicht. So wird verhindert, dass die Aktionen eines Entwicklers sich negativ auf die gesamte Community auswirken.
Für den unwahrscheinlichen Fall, dass Ihre API-Anfrage fehlschlägt, gibt die API einen HTTP-Statuscode und den Grund für den Fehler zurück. Außerdem enthält der Antworttext eine ausführliche Beschreibung der Ursache des Fehlers.
In der folgenden Liste finden Sie die möglichen Fehlercodes, Gründe, entsprechenden Beschreibungen und empfohlene Maßnahmen für Fehler, die durch 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 beträgt 2.400 Abfragen pro Minute und Nutzer und Google Cloud-Projekt. | Erhöhen Sie die Limits pro Nutzer auf der Seite „Kontingente“ der Admin SDK API Ihres Google Cloud-Projekts oder verlangsamen Sie die Rate, mit der Sie die Anfragen senden, mithilfe des Exponential Backoff. |
| 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. Diese Beschränkung gilt pro Google Workspace-Konto, nicht pro API-Client oder pro Nutzer. Dieses Limit kann nicht erhöht werden. |
Exponentiellen Backoff implementieren
Ein exponentieller Backoff ist ein Vorgang, bei dem ein Client eine fehlgeschlagene Anfrage über einen immer länger werdenden Zeitraum periodisch wiederholt. Es ist eine Standardstrategie zur Fehlerbehebung für Netzwerkanwendungen. Mithilfe des exponentiellen Backoffs wird die Effizienz der Bandbreitennutzung erhöht, die Anzahl der Anfragen, die für den Erhalt einer erfolgreichen Antwort erforderlich sind, verringert und der Durchsatz von Anfragen in Umgebungen mit Gleichzeitigkeit maximiert.
Der Ablauf für das Implementieren eines einfachen exponentiellen Backoffs sieht so aus:
- Anfrage an die API stellen
- Sie erhalten eine Fehlermeldung mit einem wiederholbaren Fehlercode.
- 1 Sekunde +
random_number_millisecondsSekunden warten - Anfrage wiederholen
- Sie erhalten eine Fehlermeldung mit einem wiederholbaren Fehlercode.
- 2 Sekunden +
random_number_millisecondsSekunden warten - Anfrage wiederholen
- Sie erhalten eine Fehlermeldung mit einem wiederholbaren Fehlercode.
- 4 Sekunden +
random_number_millisecondsSekunden warten - Anfrage wiederholen
- Sie erhalten eine Fehlermeldung mit einem wiederholbaren Fehlercode.
- 8 Sekunden +
random_number_millisecondsSekunden warten - Anfrage wiederholen
- Sie erhalten eine Fehlermeldung mit einem wiederholbaren Fehlercode.
- 16 Sekunden +
random_number_millisecondsSekunden warten - Anfrage wiederholen
- Wenn der Fehler weiterhin auftritt, 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 kleiner oder gleich 1.000 ist. Dies ist erforderlich, um bestimmte Sperrfehler bei einigen parallelen 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 dient nur dazu, zu verhindern, dass Clients unendlich oft wiederholen. Sie führt zu einer Verzögerung von insgesamt 32 Sekunden, bevor eine Anfrage als „nicht zu behebender 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 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 Kapazität des Systems ändern. |
| Mobilgeräte |
Mit der Directory API können Sie Folgendes tun:
|
| Nutzer umbenennen | Es kann bis zu 10 Minuten dauern, bis die Änderungen in allen Diensten übernommen wurden. Bevor Sie einen Nutzer umbenennen, sollten Sie ihn von allen Browsersitzungen und ‑diensten abmelden. Weitere Informationen finden Sie im Hilfeartikel 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 Notizeninformationen eines Geräts 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 Domainaliassen beträgt 20. |
| Gruppen, Beschreibung | Die maximale Anzahl von Zeichen in einer Beschreibung beträgt 4.096. |
| Gruppen, pro Konto | Bei einem Konto mit der früheren, kostenlosen Version der G Suite ist die Anzahl der Gruppen auf zehn beschränkt. Bei anderen Versionen ist die Anzahl der Gruppen unbegrenzt. |
| Gruppen, Mitglieder pro Gruppe | Bei einem Konto mit der früheren, 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 Gruppenmitgliedschaftsbeschränkungen 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 | Es können jeweils 20 Nutzer 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 insgesamt 30 Aliasse zulässig. |
| Nutzeraliasse, bei denen ein gelöschter Alias verwendet wird | Ein gelöschter Nutzeralias kann sofort wiederverwendet werden. |
| Andere Arten von Limits | Einschränkungen und Richtlinien |
|---|---|
| Abrechnung und Nutzer erstellen | Wenn Sie einen flexiblen Google Workspace-Tarif haben, hat das Erstellen von Nutzern mit dieser API finanzielle Auswirkungen und führt zu Abbuchungen von Ihrem Kundenrechnungskonto. Wenn Sie beispielsweise einen flexiblen Google Workspace-Tarif haben, werden Ihnen für das Erstellen von zehn Nutzern zehn Google Workspace-Lizenzen in Rechnung gestellt, die anteilig ab dem Zeitpunkt der Erstellung auf Ihr Konto gebucht werden. Wenn Sie einen Jahrestarif haben, haben Sie sich bereits verpflichtet, eine bestimmte Anzahl von Lizenzen im Voraus zu bezahlen. Sie können also nur so viele Nutzer erstellen, wie Sie vertraglich vereinbart haben. Weitere Informationen zu Abrechnungsmodellen und Ihrem Abrechnungskonto finden Sie in der Verwaltungshilfe. |
| 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 Zeichennutzung finden Sie in der Verwaltungshilfe. |
| 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 an der E-Mail-Adresse automatisch in der API übernommen. |
| Gruppen, Einstellungen | Die Zugriffseinstellungen für Gruppen, Freigabeoptionen, Überwachung und das Diskussionsarchiv werden über die Admin-Konsole verwaltet. Weitere Informationen zu Gruppeneinstellungen finden Sie in der Verwaltungshilfe. |
| Gruppen, Senden von Nachrichten | 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 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 Nichtzustellbarkeitsbenachrichtigungen senden | 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 Verwaltungshilfe. |
| Organisationseinheit, Dienste aktivieren/deaktivieren | In der Admin-Konsole können Sie Dienste für eine Organisationseinheit aktivieren und deaktivieren. |
| Passwörter | Sie können beliebige Zeichen enthalten. Er muss mindestens 8 Zeichen lang sein. 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. In Google Workspace werden auch Punkte (.) erkannt. Das ist nicht der Fall bei Gmail. Ein Nutzername darf kein Gleichheitszeichen (=), spitze Klammern (<,>) oder mehrere Punkte (.) nacheinander enthalten. Weitere Informationen finden Sie in der Hilfe für Administratoren. |
| Nutzernamen, Umbenennung | 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, um eine unterbrechungsfreie E-Mail-Zustellung bei 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 Verwaltungshilfe. 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 beliebige Ihrer Domains enthalten. In einem Mehrfachdomainkonto können Nutzer in einer Domain Dienste mit Nutzern in anderen Kontodomains teilen. Mehrere Domainkomponenten:
|
| Warnungen, Gruppenmitglieder | GROUP_CANNOT_CONTAIN_CYCLE: Die API erlaubt keine Schleifen bei Gruppenmitgliedschaften. Wenn beispielsweise Gruppe 1 Mitglied von Gruppe 2 ist, kann Gruppe 2 kein Mitglied von Gruppe 1 sein. |