Nutzungsbeschränkungen

Für die Gmail API gelten Nutzungslimits, die die Häufigkeit einschränken, mit der Methoden der API aufgerufen werden können. Limits werden in Kontingent einheiten definiert. Das ist eine abstrakte Maßeinheit, die die Nutzung von Gmail-Ressourcen darstellt. Es gibt zwei Nutzungslimits, die gleichzeitig angewendet werden: ein Ratenlimit pro Projekt und ein Ratenlimit pro Nutzer.

In der folgenden Tabelle werden diese Limits näher erläutert:

Art des Nutzungslimits Limit Fehlercode
Ratenlimit pro Projekt 1.200.000 Kontingenteinheiten pro Minute rateLimitExceeded
Ratenlimit pro Nutzer 15.000 Kontingenteinheiten pro Minute und Nutzer userRateLimitExceeded

Informationen zum Beheben von Limitfehlern finden Sie unter Fehler beheben.

Kontingentnutzung pro Methode

Die Anzahl der Kontingenteinheiten, die von einer Anfrage verbraucht werden, hängt von der aufgerufenen Methode ab. In der folgenden Tabelle ist die Nutzung von Kontingenteinheiten pro Methode aufgeführt:

Methode Kontingenteinheiten
drafts.create 10
drafts.delete 10
drafts.get 5
drafts.list 5
drafts.send 100
drafts.update 15
getProfile 1
history.list 2
labels.create 5
labels.delete 5
labels.get 1
labels.list 1
labels.update 5
messages.attachments.get 5
messages.batchDelete 50
messages.batchModify 50
messages.delete 10
messages.get 5
messages.import 25
messages.insert 25
messages.list 5
messages.modify 5
messages.send 100
messages.trash 5
messages.untrash 5
settings.delegates.create 100
settings.delegates.delete 5
settings.delegates.get 1
settings.delegates.list 1
settings.filters.create 5
settings.filters.delete 5
settings.filters.get 1
settings.filters.list 1
settings.forwardingAddresses.create 100
settings.forwardingAddresses.delete 5
settings.forwardingAddresses.get 1
settings.forwardingAddresses.list 1
settings.getAutoForwarding 1
settings.getImap 1
settings.getPop 1
settings.getVacation 1
settings.sendAs.create 100
settings.sendAs.delete 5
settings.sendAs.get 1
settings.sendAs.list 1
settings.sendAs.update 100
settings.sendAs.verify 100
settings.updateAutoForwarding 5
settings.updateImap 5
settings.updatePop 100
settings.updateVacation 5
stop 50
threads.delete 20
threads.get 10
threads.list 10
threads.modify 10
threads.trash 10
threads.untrash 10
watch 100

Bei Verwendung der Gmail API gilt außerdem ein Limit von 500 Empfängern pro E-Mail.

Zeitbasierte Kontingentfehler beheben

Bei allen zeitbasierten Fehlern (maximal N Anfragen pro X Minuten) empfehlen wir dass Ihr Code die Ausnahme abfängt und einen abgeschnittenen exponentiellen Backoff verwendet, damit Ihre Geräte keine übermäßige Last erzeugen.

Ein exponentieller Backoff ist eine Standardstrategie zur Fehlerbehebung für Netzwerkanwendungen. Ein exponentieller Backoff-Algorithmus wiederholt Anfragen mit exponentiell zunehmenden Wartezeiten zwischen den Anfragen bis zur maximalen Backoff-Zeit. Wenn Anfragen weiterhin fehlschlagen, müssen die Verzögerungen zwischen den Anfragen mit der Zeit zunehmen, bis die Anfrage erfolgreich ist.

Beispielalgorithmus

Ein exponentieller Backoff-Algorithmus wiederholt Anfragen exponentiell und verlängert dabei die Wartezeit zwischen zwei Wiederholungen bis zur maximalen Backoff-Zeit. Beispiel:

  1. Stellen Sie eine Anfrage an die Gmail API.
  2. Wenn die Anfrage fehlschlägt, warten Sie 1 + random_number_milliseconds und wiederholen Sie die Anfrage.
  3. Wenn die Anfrage fehlschlägt, warten Sie 2 + random_number_milliseconds und wiederholen Sie die Anfrage.
  4. Wenn die Anfrage fehlschlägt, warten Sie 4 + random_number_milliseconds und wiederholen Sie die Anfrage.
  5. Und so weiter bis zur maximum_backoff-Zeit.
  6. Das System wartet weiter und führt erneute Versuche bis zu einer maximalen Anzahl an Wiederholungsversuchen aus, jedoch ohne den zeitlichen Abstand zwischen zwei Versuchen zu erhöhen.

Dabei gilt:

  • Die Wartezeit beträgt min(((2^n)+random_number_milliseconds), maximum_backoff), wobei n bei jeder Ausführung (Anfrage) um 1 erhöht wird.
  • random_number_milliseconds steht für eine zufällige Anzahl von Millisekunden,deren Wert größer oder gleich 1.000 ist. So lassen sich Situationen vermeiden, in denen viele Clients synchronisiert werden durch eine Situation und alle gleichzeitig Anfragen wiederholen und diese in synchronisierten Wellen senden. Der Wert von random_number_milliseconds wird nach jeder Anfragewiederholung neu berechnet.
  • maximum_backoff ist normalerweise 32 oder 64 Sekunden lang. Der geeignete Wert hängt vom jeweiligen Anwendungsfall ab.

Der Client kann den Vorgang wiederholen, nachdem er die maximum_backoff-Zeit erreicht hat. Die Backoff-Zeit muss dabei nicht mehr verlängert werden. Wenn ein Client beispielsweise eine maximum_backoff Zeit von 64 Sekunden verwendet, kann er den Vorgang nach Erreichen dieses Werts alle 64 Sekunden noch einmal versuchen. Sie sollten jedoch dafür sorgen, dass er dies nicht unbegrenzt tut.

Die Wartezeit zwischen den Wiederholungen und der Anzahl der Wiederholungen hängt von Ihrem Anwendungsfall und den Netzwerkbedingungen ab.

Preise

Die Nutzung der Gmail API ist kostenlos. Wenn Sie die Limits für Kontingent anfragen überschreiten, fallen keine zusätzlichen Kosten an und Ihr Konto wird nicht belastet.

Kontingenterhöhung anfordern

Abhängig von der Ressourcennutzung Ihres Projekts können Sie eine Kontingent anpassung anfordern. API-Aufrufe durch ein Dienstkonto werden als Nutzung eines einzelnen Kontos betrachtet. Wenn Sie ein angepasstes Kontingent beantragen, bedeutet dies nicht, dass Ihr Antrag auch genehmigt wird. Anfragen zur Kontingentanpassung , die den Kontingentwert erheblich erhöhen würden, können länger dauern, bis sie genehmigt werden.

Es gelten nicht für alle Projekte dieselben Kontingente. Wenn Sie Google Cloud im Laufe der Zeit häufiger nutzen, müssen Ihre Kontingentwerte möglicherweise erhöht werden. Falls Sie eine deutlich stärkere Auslastung erwarten, können Sie proaktiv eine Anpassung Ihres Kontingents anfordern auf der Seite Kontingente der Google Cloud Console.

Weitere Informationen finden Sie in folgenden Dokumenten: