Nutzungsbeschränkungen

Für die Google Calendar API gelten Kontingente, damit sie von allen Nutzern fair verwendet wird. Bei der Verwendung der Calendar API sind drei wichtige Einschränkungen zu beachten:

  • Kontingente für die API-Nutzung: Werden pro Projekt und Nutzer erzwungen. Weitere Informationen finden Sie unter Kontingenttypen für die Calendar API.

  • Allgemeine Nutzungslimits für Google Kalender: Die Google Calendar API ist ein gemeinsamer Dienst, der Einschränkungen unterliegt, um die Gesamtleistung des Google Workspace-Systems zu schützen. Weitere Informationen finden Sie unter Nutzungslimits für Google Kalender vermeiden.

  • Betriebliche Einschränkungen: Diese Limits können jederzeit eingeschränkt werden. Das kann z. B. passieren, wenn Sie versuchen, in kurzer Abfolge in einen einzelnen Kalender zu schreiben.

Kontingente für die Calendar API

Es werden zwei Arten von Kontingenten erzwungen:

  • Pro Minute und Projekt:Das 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 stellen kann. Dieses Limit soll Ihnen helfen, eine faire Verteilung der Nutzung auf Ihre Nutzer zu gewährleisten.

Kontingente werden pro Minute mit einem Gleitfenster berechnet. Wenn in einer Minute ein schneller Traffic-Burst auftritt, der Ihr Kontingent pro Minute überschreitet, wird die Ratenbegrenzung im nächsten Zeitfenster angewendet, um sicherzustellen, dass Ihre Nutzung im Durchschnitt innerhalb der Kontingente bleibt.

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

Nutzungslimit-Typ Limit
Pro Minute und Projekt 10.000 Anfragen
Pro Minute, Nutzer und Projekt 600 Anfragen

Täglicher Abrechnungsgrenzbetrag

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

Bei einer Nutzung unter diesem Grenzwert fallen keine zusätzlichen Gebühren an und Ihr Google Cloud-Konto wird nicht belastet. Die vollständigen Abrechnungsdetails werden später im Jahr 2026 mitgeteilt, mindestens 90 Tage vor Inkrafttreten von Änderungen.

Eine Erhöhung dieses Tageslimit kann nicht beantragt werden.

In der folgenden Tabelle wird das Limit näher erläutert:

Typ 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, dass Ihr Code die Ausnahme abfängt und einen abgeschnittenen exponentiellen Backoff verwendet, um sicherzustellen, dass Ihre Geräte keine übermäßige Last erzeugen.

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, ist es wichtig, dass 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 Google Calendar API.
  2. Wenn die Anfrage fehlschlägt, wartet das System 1 + random_number_milliseconds Sekunden und wiederholt dann die Anfrage.
  3. Wenn die Anfrage fehlschlägt, wartet das System 2 + random_number_milliseconds Sekunden und wiederholt dann die Anfrage.
  4. Wenn die Anfrage fehlschlägt, wartet das System 4 + random_number_milliseconds Sekunden und wiederholt dann 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 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 die Anzahl der Wiederholungen hängen von Ihrem Anwendungsfall und den Netzwerkbedingungen ab.

Preise

Die Standardnutzung der Google Calendar API ist kostenlos. Wenn Sie die Kontingentanfragelimits überschreiten, 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 können Sie eine Kontingentanpassung beantragen. 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 auf der Seite Kontingente und Systemlimits der Google Cloud Console eine Anpassung Ihres Kontingents anfordern.

Weitere Informationen finden Sie in den folgenden Ressourcen:

Fehlerbehebung

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

Falls das passiert, können Sie Folgendes versuchen:

  1. Achten Sie darauf, alle Best Practices zu befolgen: Verwenden Sie exponentiellen Backoff, randomisieren Sie Traffic-Muster und verwenden Sie Push-Benachrichtigungen.

  2. Wenn Ihr Projekt wächst und Sie mehr Nutzer haben, können Sie eine Kontingenterhöhung anfordern.

  3. Wenn Sie die Kontingentlimits pro Nutzer erreichen, haben Sie folgende Möglichkeiten:

    • Wenn Sie ein Dienstkonto verwenden, weisen Sie die Last Nutzern zu 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 Kalendernutzungs- oder Betriebslimits.

  4. Testen Sie Ihre Kontingentlimits, indem Sie ein separates reines Testprojekt registrieren, das eine ähnliche Konfiguration wie Ihr Produktionsprojekt hat. Weitere Informationen finden Sie unter Umgang mit Kontingentlimits testen.

Traffic-Muster zufällig anordnen

Kalenderclients sind anfällig für Trafficspitzen, die dadurch entstehen, dass mehrere Clients gleichzeitig Vorgänge ausführen. Ein häufiges Beispiel für eine schlechte Vorgehensweise bei einem Kalenderclient ist die Durchführung einer vollständigen Synchronisierung um Mitternacht. Dies würde mit ziemlicher Sicherheit dazu führen, dass Sie Ihr Kontingent pro Minute überschreiten, was zu Ratenbegrenzung und Backoffs führen würde.

Um dies zu vermeiden, sollten Sie Ihren Traffic nach Möglichkeit über den Tag verteilen. Wenn Ihr Kunde eine tägliche Synchronisierung durchführen muss, soll er eine zufällige Zeit festlegen (für jeden Kunden eine andere). Wenn Sie einen Vorgang regelmäßig ausführen müssen, variieren Sie das Intervall um +/- 25%. So wird der Traffic gleichmäßiger verteilt und die Nutzerfreundlichkeit deutlich verbessert.

Push-Benachrichtigungen verwenden

Ein häufiger Anwendungsfall ist das Ausführen einer Aktion, wenn sich etwas im Kalender des Nutzers ändert. Ein Anti-Pattern ist es, alle interessierenden Kalender wiederholt abzufragen. Dadurch wird Ihr gesamtes Kontingent sehr schnell aufgebraucht. Wenn Ihre Anwendung beispielsweise 5.000 Nutzer hat und den Kalender jedes Nutzers einmal pro Minute abruft, ist ein Kontingent von mindestens 5.000 Anfragen pro Minute erforderlich, noch bevor die eigentliche Arbeit erledigt wird.

Serverseitige Anwendungen können sich für Push-Benachrichtigungen registrieren. So können wir Sie benachrichtigen, wenn etwas passiert, das für Sie von Interesse ist. Diese erfordern mehr Aufwand bei der Einrichtung, ermöglichen aber eine deutlich effizientere Nutzung Ihres Kontingents und bieten eine bessere Nutzererfahrung. Geben Sie die eventType an, über die Sie benachrichtigt werden möchten. Weitere Informationen finden Sie unter Push-Benachrichtigungen.

Ordnungsgemäße Zuweisung mit Dienstkonten

Wenn Ihre Anwendung Anfragen mit domainweiter Delegierung ausführt, wird das Dienstkonto standardmäßig in Bezug auf die Kontingente „pro Minute pro Nutzer pro Projekt“ belastet und nicht der Nutzer, den Sie imitieren. Das bedeutet, dass das Dienstkonto wahrscheinlich das Kontingent überschreitet und die Ratenbegrenzung erreicht, auch wenn es möglicherweise auf die Kalender mehrerer Nutzer zugreift.

Sie können dies vermeiden, indem Sie den URL-Parameter quotaUser (oder den HTTP-Header x-goog-quota-user) verwenden, um anzugeben, welcher Nutzer abgerechnet wird. Dieser Wert wird nur für Kontingentberechnungen verwendet. Weitere Informationen finden Sie unter Anfragen pro Nutzer begrenzen.

Umgang mit Kontingentlimits testen

Damit Ihre Anwendung das Erreichen von Kontingentlimits in der Praxis problemlos verarbeiten kann (z. B. durch Wiederholungsversuche 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 ohne Beeinträchtigung Ihrer tatsächlichen App-Nutzung durchzuführen, empfehlen wir, ein separates reines Testprojekt in der Google Cloud Console zu registrieren und dann den OAuth-Zustimmungsbildschirm ähnlich wie bei Ihrem Produktionsprojekt zu konfigurieren. Anschließend können Sie für dieses Projekt künstlich niedrige Kontingentlimits festlegen und das Verhalten Ihrer Anwendung beobachten.