Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Nutzungsbeschränkungen

Für die Google Calendar API gelten Kontingente, damit sie von allen Nutzern fair verwendet wird. Bei der Verwendung der Calendar API müssen drei wichtige Einschränkungen berücksichtigt werden:

Kontingente für die API-Nutzung: Werden pro Projekt und pro Nutzer erzwungen. Weitere Informationen finden Sie unter Arten von Nutzungskontingenten für die Calendar API.
Allgemeine Nutzungslimits für Google Kalender: Die Google Calendar API ist ein gemeinsam genutzter Dienst, für den Einschränkungen gelten, um die Gesamtleistung des Google Workspace-Systems zu schützen. Weitere Informationen finden Sie unter Nutzungsbeschränkungen für Google Kalender vermeiden
Betriebliche Limits: Diese Limits können jederzeit eingeschränkt werden. Das kann beispielsweise passieren, wenn Sie versuchen, schnell hintereinander in einen einzelnen Kalender zu schreiben.

Kontingente für die Calendar API

Es werden zwei Arten von Kontingenten erzwungen:

Pro Minute und Projekt:Dies ist die Anzahl der Anfragen, die Ihr Google Cloud-Projekt in einer Minute senden kann.
Pro Minute, Nutzer und Projekt:Dies ist die Anzahl der Anfragen, die ein bestimmter Nutzer in Ihrem Cloud-Projekt senden kann. Mit diesem Limit können Sie eine faire Verteilung der Nutzung auf Ihre Nutzer gewährleisten.

Kontingente werden pro Minute mit einem gleitenden Fenster berechnet. Wenn Sie Ihr Kontingent pro Minute während einer Minute durch einen schnellen Trafficanstieg überschreiten, wird die Ratenbegrenzung während des nächsten Fensters angewendet, um sicherzustellen, dass Ihre Nutzung im Durchschnitt innerhalb der Kontingente bleibt.

In der folgenden Tabelle sind diese Limits aufgeführt:

Art des Nutzungslimits	Limit
Pro Minute und Projekt	10.000 Anfragen
Pro Minute, Nutzer und Projekt	600 Anfragen

Täglicher Abrechnungsschwellenwert

Dieses Limit pro Tag und Projekt definiert die maximale Anzahl von Anfragen, die Ihr Google Cloud-Projekt innerhalb von 24 Stunden verwenden kann, bevor Gebühren anfallen.

Bei einer Nutzung unter diesem Schwellenwert fallen keine zusätzlichen Gebühren an und Ihr Google Cloud-Konto wird nicht belastet. Vollständige Abrechnungsdetails werden später im Jahr 2026 mindestens 90 Tage vor Inkrafttreten von Änderungen bekannt gegeben.

Sie können keine Erhöhung dieses täglichen Schwellenwertlimits anfordern.

In der folgenden Tabelle ist das Limit aufgeführt:

Art des Schwellenwertlimits	Limit
Pro Tag und Projekt	1.000.000 Anfragen

Weitere Informationen finden Sie unter Standardisiertes Google Workspace-Modell für Agent-Tools und APIs.

Zeitbasierte Kontingentfehler beheben

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

Ein exponentieller Backoff ist eine Standardstrategie zur Fehlerbehandlung für Netzwerkanwendungen. Ein exponentieller Backoff-Algorithmus wiederholt Anfragen mit exponentiell zunehmenden Wartezeiten zwischen den Anfragen bis zur maximalen Backoff-Zeit. Wenn Anfragen weiterhin nicht erfolgreich sind, müssen die Verzögerungen zwischen den Anfragen im Laufe 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:

Stellen Sie eine Anfrage an die Google Calendar API.
Wenn die Anfrage fehlschlägt, warten Sie 1 + random_number_milliseconds und wiederholen Sie die Anfrage.
Wenn die Anfrage fehlschlägt, warten Sie 2 + random_number_milliseconds und wiederholen Sie die Anfrage.
Wenn die Anfrage fehlschlägt, warten Sie 4 + random_number_milliseconds und wiederholen Sie die Anfrage.
Und so weiter bis zur Zeit maximum_backoff.
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 bei jeder Ausführung (Anfrage) n 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 Zeit maximum_backoff 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 nach Erreichen dieses Werts alle 64 Sekunden einen neuen Versuch starten. 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 gesamte Standardnutzung der Google Calendar API ist kostenlos. Wenn die Kontingent anfragelimits überschritten werden, fallen voraussichtlich später im Jahr 2026 Gebühren für Ihr Google Cloud-Rechnungskonto an. Weitere Informationen finden Sie unter Standardisiertes Google Workspace-Modell für Agent-Tools und APIs.

Kontingenterhöhung anfordern

Abhängig von der Ressourcennutzung Ihres Projekts möchten Sie möglicherweise eine Kontingentanpassung 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. Die Genehmigung von Anfragen zur Kontingentanpassung, die den Kontingentwert erheblich erhöhen würden, kann länger dauern.

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 und Systemlimits der Google Cloud Console.

Weitere Informationen finden Sie in den folgenden Ressourcen:

Fehlerbehebung

Wenn eines der Kontingente überschritten wird, wird die Ratenbegrenzung angewendet und Sie erhalten als Antwort auf Ihre Anfragen den 403 usageLimits Statuscode oder den 429 usageLimits Statuscode.

In diesem Fall können Sie Folgendes versuchen:

Achten Sie darauf, alle Best Practices zu befolgen: Verwenden Sie den exponentiellen Backoff, randomisieren Sie Traffic-Muster, und verwenden Sie Push-Benachrichtigungen.
Wenn Ihr Projekt wächst und Sie mehr Nutzer haben, können Sie eine Kontingenterhöhung anfordern.
Wenn Sie Kontingentlimits pro Nutzer erreichen, können Sie Folgendes tun:
- Wenn Sie ein Dienstkonto verwenden, verteilen Sie die Last auf Nutzer oder teilen Sie sie auf mehrere Dienstkonten auf.
- Sie können zwar eine Erhöhung des Kontingents pro Nutzer anfordern, es wird jedoch im Allgemeinen nicht empfohlen, es über den Standardwert hinaus zu erhöhen, da Ihre Anwendung sonst möglicherweise andere Arten von Limits erreicht, z. B. allgemeine Nutzungslimits für Google Kalender oder betriebliche Limits.
Testen Sie Ihre Kontingentlimits, indem Sie ein separates Projekt nur für Tests registrieren, das eine ähnliche Konfiguration wie Ihr Produktionsprojekt hat. Weitere Informationen finden Sie unter Umgang mit Kontingentlimits testen.

Traffic-Muster randomisieren

Bei Kalender-Clients kommt es häufig zu Trafficspitzen, da mehrere Clients gleichzeitig Vorgänge ausführen. Eine häufige schlechte Praxis für einen Kalender-Client ist beispielsweise die Durchführung einer vollständigen Synchronisierung um Mitternacht. Dies würde mit ziemlicher Sicherheit dazu führen, dass Ihr Kontingent pro Minute überschritten wird, und zu Ratenbegrenzung und Backoffs führen.

Um dies zu vermeiden, sollte Ihr Traffic nach Möglichkeit über den Tag verteilt werden. Wenn Ihr Client eine tägliche Synchronisierung durchführen muss, sollte er eine zufällige Zeit festlegen (die für jeden Client unterschiedlich ist). Wenn Sie regelmäßig einen Vorgang ausführen müssen, variieren Sie das Intervall um +/- 25%. Dadurch wird der Traffic gleichmäßiger verteilt und die Nutzerfreundlichkeit erheblich verbessert.

Push-Benachrichtigungen verwenden

Ein häufiger Anwendungsfall ist die Ausführung einer Aktion, wenn sich etwas im Kalender des Nutzers ändert. Ein Anti-Pattern ist hier, jeden interessanten Kalender wiederholt abzufragen. Dadurch wird Ihr Kontingent sehr schnell aufgebraucht. Wenn Ihre Anwendung beispielsweise 5.000 Nutzer hat und den Kalender jedes Nutzers einmal pro Minute abfragt, ist dafür ein Kontingent von mindestens 5.000 pro Minute erforderlich, noch bevor überhaupt etwas getan wird.

Serverseitige Anwendungen können sich für Push-Benachrichtigungen registrieren, damit wir Sie benachrichtigen können, wenn etwas Interessantes passiert. Die Einrichtung ist zwar aufwendiger, ermöglicht aber eine wesentlich effizientere Nutzung Ihres Kontingents und bietet eine bessere Nutzerfreundlichkeit. Geben Sie den eventType an, für den Sie benachrichtigt werden möchten. Weitere Informationen finden Sie unter Push Benachrichtigungen.

Richtige Zuweisung mit Dienstkonten

Wenn Ihre Anwendung Anfragen mit domainweiter Delegierung ausführt, wird standardmäßig das Dienstkonto in Bezug auf die Kontingente "pro Minute, Nutzer und Projekt" belastet und nicht der Nutzer, den Sie imitieren. Das bedeutet, dass das Kontingent des Dienstkontos wahrscheinlich aufgebraucht wird und die Ratenbegrenzung angewendet wird, obwohl es möglicherweise in den Kalendern mehrerer Nutzer aktiv ist.

Sie können dies vermeiden, indem Sie mit dem URL-Parameter quotaUser (oder dem HTTP-Header x-goog-quota-user) angeben, welcher Nutzer belastet wird. Dieser wird nur für Kontingentberechnungen verwendet. Weitere Informationen finden Sie unter Anfragen pro Nutzer begrenzen.

Umgang mit Kontingentlimits testen

Damit Ihre Anwendung in der Praxis ordnungsgemäß mit dem Erreichen von Kontingentlimits umgehen kann (z. B. durch Wiederholungen mit exponentiellem Backoff) und um potenzielle Störungen für Ihre Nutzer zu minimieren, empfehlen wir dringend, Ihr Szenario in einer realen Umgebung zu testen.

Um Tests durchzuführen, ohne die tatsächliche Nutzung Ihrer Anwendung zu beeinträchtigen, empfehlen wir, in der Google Cloud Console ein separates Projekt nur für Tests zu registrieren und dann den OAuth-Zustimmungs bildschirm ähnlich wie bei Ihrem Produktions projekt zu konfigurieren. Anschließend können Sie für dieses Projekt künstlich niedrige Kontingent limits festlegen und das Verhalten Ihrer Anwendung beobachten.

Kontingente für den Calendar MCP-Server

Der Calendar MCP-Server verwendet eine Messwert für die Zuweisung von Abfragekosten. In den folgenden Tabellen sind die Abfragekosten für jede Calendar MCP-Servermethode nach Abschnitt aufgeführt:

Kontingente für den Calendar MCP