Die Google Kalender API verfügt über Kontingente, um sicherzustellen, dass sie von allen Nutzern fair genutzt wird. Bei der Verwendung der Kalender API sind drei wichtige Einschränkungen zu beachten:
- API-Nutzungskontingente werden pro Projekt und pro Nutzer erzwungen. Weitere Informationen finden Sie im nächsten Abschnitt.
- Allgemeine Nutzungslimits für Kalender: Vermeiden Sie Nutzungslimits für Kalender.
- Betriebslimits:Die Ratenbegrenzung kann jederzeit gelten. Das ist beispielsweise der Fall, wenn Sie schnell hintereinander in einen einzelnen Kalender schreiben möchten.
Arten von Nutzungskontingenten für die Kalender API
Es werden zwei Arten von Kontingenten erzwungen:
- Pro Minute und Projekt:Dies ist die Anzahl der Anfragen, die von Ihrem Google Cloud-Projekt gestellt wurden.
- Pro Minute, Projekt und Nutzer: Dies ist die Anzahl der Anfragen, die von einem bestimmten Nutzer in Ihrem Cloud-Projekt gestellt werden. Diese Beschränkung soll Ihnen dabei helfen, eine faire Verteilung der Nutzung unter Ihren Nutzern sicherzustellen.
Kontingente werden pro Minute mithilfe eines gleitenden Fensters berechnet. Ein schneller Traffic-Burst, der Ihr Kontingent pro Minute während einer Minute überschreitet, führt also zu einer Ratenbegrenzung im nächsten Fenster, um sicherzustellen, dass Ihre Nutzung durchschnittlich innerhalb der Kontingente bleibt.
Wird eines der Kontingente überschritten, gilt für Sie eine Ratenbegrenzung und Sie erhalten für Ihre Abfragen einen Statuscode 403 usageLimits oder einen Statuscode 429 usageLimits. In diesem Fall haben Sie folgende Möglichkeiten:
- Beachten Sie alle Best Practices: exponentiellen Backoff verwenden, Traffic-Muster zufällig anordnen, Push-Benachrichtigungen verwenden.
- Wenn Ihr Projekt wächst und Sie mehr Nutzer haben, können Sie eine Erhöhung des Kontingents pro Projekt anfordern.
- Wenn das Kontingentlimit pro Nutzer erreicht ist, 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 aber im Allgemeinen nicht empfohlen, es über den Standardwert hinaus zu erhöhen, da Ihre Anwendung möglicherweise andere Arten von Limits erreicht, z. B. allgemeine Limits für die Kalendernutzung oder Betriebslimits.
Anfrage zur Kontingenterhöhung
Wenn Sie die Nutzungslimits für Ihr Projekt aufrufen oder ändern bzw. eine Erhöhung Ihres Kontingents anfragen möchten, gehen Sie so vor:
- Wenn Sie für Ihr Projekt noch kein Rechnungskonto haben, erstellen Sie dieses.
- Rufen Sie in der API Console die Seite „Aktivierte APIs“ auf und wählen Sie eine API aus der Liste aus.
- Klicken Sie auf Kontingente, um die Einstellungen zum Kontingent aufzurufen und zu ändern. Klicken Sie auf Nutzung, um die Nutzungsstatistik einzusehen.
Exponentiellen Backoff verwenden
Wenn Sie möchten, dass Ihre Anfragerate verlangsamt wird, erhalten Sie die Antwort „usageLimits“ 403 oder 429. Weitere Informationen finden Sie in der vollständigen Fehlerdokumentation. Dies ist kein schwerwiegender Fehler. Wir erwarten, dass Sie die Anfrage nach einer kurzen Wartezeit wiederholen. Wenn Anfragen immer noch zu schnell eintreffen, fragen wir noch einmal nach usw. Damit dies korrekt funktioniert, ist es wichtig, dass die Verzögerungen zwischen den Anfragen mit der Zeit ansteigen.
Im Allgemeinen sollten Sie den abgeschnittenen exponentiellen Backoff verwenden. In der Cloud Storage-Dokumentation finden Sie eine gute Erklärung zur Funktionsweise und den bevorzugten Algorithmus. Wenn Sie eine Google-Clientbibliothek verwenden, wird das normalerweise für Sie erledigt. Weitere Informationen finden Sie in der Dokumentation Ihrer Bibliothek. Normalerweise sollten Sie die Implementierung der Bibliothek verwenden, anstatt eine eigene zu schreiben.
Traffic-Muster zufällig anordnen
Kalenderclients neigen zu Traffic-Spitzen, die dadurch verursacht werden, dass mehrere Clients gleichzeitig Vorgänge ausführen. Eine gängige Best Practice für einen Kalender-Client besteht beispielsweise darin, um Mitternacht eine vollständige Synchronisierung durchzuführen. Dies würde höchstwahrscheinlich zur Überschreitung Ihres Minutenkontingents und zu Ratenbegrenzung und Backoffs führen.
Um dies zu vermeiden, solltest du dafür sorgen, dass die Zugriffe über den Tag verteilt sind, wo immer es möglich ist. Wenn Ihr Client täglich eine Synchronisierung durchführen muss, lassen Sie ihn eine zufällige Zeit bestimmen, die für jeden Client unterschiedlich ist. Wenn Sie regelmäßig einen Vorgang ausführen müssen, variieren Sie das Intervall +/- 25%. Dadurch wird der Traffic gleichmäßiger verteilt und die Nutzererfahrung deutlich verbessert.
Push-Benachrichtigungen verwenden
Ein häufiger Anwendungsfall ist, dass eine Aktion immer dann ausgeführt werden soll, wenn sich im Kalender des Nutzers etwas ändert. Ein Anti-Muster ist es, jeden relevanten 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 abfragt, ist ein Minutenkontingent von mindestens 5.000 erforderlich, bevor die Arbeit erledigt wird.
Serverseitige Anwendungen können sich für Push-Benachrichtigungen registrieren. Dadurch können wir Sie benachrichtigen, wenn etwas von Interesse ist. Die Einrichtung dieser Lösungen erfordert mehr Arbeit, ermöglicht aber eine deutlich effizientere Nutzung Ihres Kontingents und eine bessere Nutzererfahrung. Achte darauf, die eventType anzugeben, über die du benachrichtigt werden möchtest. Weitere Informationen findest du unter Push-Benachrichtigungen.
Korrekte Buchhaltung mit Dienstkonten
Wenn Ihre Anwendung Anfragen über die domainweite Delegierung ausführt, wird für das Dienstkonto standardmäßig das Kontingent „pro Minute, Projekt und Nutzer“ berechnet und nicht nach dem Nutzer, den Sie imitieren. Das bedeutet, dass für das Dienstkonto wahrscheinlich das Kontingent erschöpft ist und die Ratenbegrenzung gilt, obwohl es möglicherweise in den Kalendern mehrerer Nutzer aktiv ist. Sie können das vermeiden, indem Sie mit dem URL-Parameter quotaUser (oder dem HTTP-Header x-goog-quota-user) angeben, welchem Nutzer Kosten in Rechnung gestellt werden. Dies wird nur für Kontingentberechnungen verwendet. Weitere Informationen finden Sie in der Cloud-Dokumentation unter Anfragen pro Nutzer begrenzen.
Umgang mit Testkontingentlimits
Damit Ihre Anwendung das Erreichen von Kontingentlimits in der Praxis problemlos bewältigen kann (z.B. durch Wiederholungsversuche mit exponentiellem Backoff) und mögliche Störungen für Ihre Nutzer minimieren können, empfehlen wir dringend, dieses Szenario in einer realen Umgebung zu testen.
Damit ein solcher Test Ihre tatsächliche Anwendungsnutzung nicht beeinträchtigt, sollten Sie in der Google API Console ein separates Testprojekt registrieren und auf ähnliche Weise wie in Ihrem Produktionsprojekt konfigurieren. Sie können dann künstlich niedrige Kontingente für dieses Projekt festlegen und das Verhalten Ihrer Anwendung beobachten.
Preise
Die Verwendung der Google Kalender API ist vollständig ohne zusätzliche Kosten möglich. Beim Überschreiten der Kontingentanfragelimits fallen keine zusätzlichen Kosten an und Ihr Konto wird nicht in Rechnung gestellt.