Für die Google Calendar API gelten Quoten, damit sie von allen Nutzern fair genutzt werden kann. Bei der Verwendung der Calendar API sind drei wichtige Einschränkungen zu beachten:
- Kontingente für die API-Nutzung werden pro Projekt und pro Nutzer erzwungen. Weitere Informationen finden Sie im nächsten Abschnitt.
- Allgemeine Nutzungsbeschränkungen für Google Kalender: Vermeiden Sie Nutzungsbeschränkungen für Google Kalender.
- Betriebsbeschränkungen:Die Rate kann jederzeit begrenzt werden. Das kann beispielsweise passieren, wenn Sie in schneller Folge in einen einzelnen Kalender schreiben.
Arten von Kontingenten für die Nutzung der Kalender API
Es werden zwei Arten von Kontingenten erzwungen:
- Pro Minute und Projekt:Das ist die Anzahl der Anfragen, die von Ihrem Google Cloud-Projekt gesendet werden.
- Pro Minute und Projekt und Nutzer:Das ist die Anzahl der Anfragen, die von einem bestimmten Nutzer in Ihrem Cloud-Projekt gesendet werden. Mit diesem Limit möchten wir Ihnen helfen, die Nutzung unter Ihren Nutzern fair zu verteilen.
Kontingente werden pro Minute mithilfe eines gleitenden Fensters berechnet. Wenn also ein plötzlicher Trafficanstieg Ihr Minutenkontingent überschreitet, wird die Rate im nächsten Fenster begrenzt, damit Ihre Nutzung durchschnittlich innerhalb der Kontingente bleibt.
Wenn eines der Kontingente überschritten wird, wird die Rate begrenzt und Sie erhalten für Ihre Abfragen den Statuscode 403 usageLimits oder 429 usageLimits. In diesem Fall haben Sie folgende Möglichkeiten:
- Beachten Sie alle Best Practices: Verwenden Sie die exponentielle Backoff-Methode, generieren Sie zufällige Traffic-Muster und verwenden Sie Push-Benachrichtigungen.
- Wenn Ihr Projekt wächst und Sie mehr Nutzer haben, können Sie eine Erhöhung des pro Projekt verfügbaren Kontingents beantragen.
- Wenn das Kontingent pro Nutzer erreicht wurde, haben Sie folgende Möglichkeiten:
- Wenn Sie ein Dienstkonto verwenden, teilen Sie die Last auf Nutzer auf oder verteilen Sie sie auf mehrere Dienstkonten.
- Sie können eine Erhöhung des pro Nutzer zugewiesenen Kontingents beantragen. Wir empfehlen jedoch, es nicht über den Standardwert zu erhöhen, da Ihre Anwendung sonst möglicherweise andere Arten von Limits erreicht, z. B. allgemeine Limits für die Kalendernutzung oder Betriebslimits.
Kontingenterhöhung beantragen
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“ in der API-Bibliothek 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 einzublenden.
Exponentiellen Backoff verwenden
Wenn wir Sie bitten möchten, die Anzahl Ihrer Anfragen zu reduzieren, geben wir die Antwort 403 „usageLimits“ oder 429 zurück (siehe vollständige Fehlerdokumentation). Dies ist kein schwerwiegender Fehler. Wir empfehlen Ihnen, die Anfrage nach kurzer Zeit noch einmal zu senden. Wenn Anfragen immer noch zu schnell eingehen, fragen wir noch einmal usw. Damit dies ordnungsgemäß funktioniert, ist es wichtig, dass die Verzögerungen zwischen den Anfragen im Laufe der Zeit zunehmen.
Im Allgemeinen sollten Sie den abgeschnittenen exponentiellen Backoff verwenden. In der Cloud Storage-Dokumentation wird die Funktionsweise und der bevorzugte Algorithmus ausführlich erläutert. Wenn Sie eine Google-Clientbibliothek verwenden, wird dies normalerweise für Sie erledigt. Lesen Sie dazu die Dokumentation der Bibliothek. Normalerweise sollten Sie die Bibliothekimplementierung verwenden, anstatt eine eigene zu schreiben.
Zugriffsmuster zufälligisieren
Bei Kalenderclients kommt es häufig zu Spitzen bei den Zugriffsmustern, die durch mehrere Clients verursacht werden, die gleichzeitig Vorgänge ausführen. Eine häufige schlechte Praxis bei einem Kalenderclient ist beispielsweise die Durchführung einer vollständigen Synchronisierung um Mitternacht. Das würde fast mit Sicherheit dazu führen, dass Ihr pro Minute zulässiges Kontingent überschritten wird, was zu einer Drosselung der Rate und zu Rückschritten führt.
Um dies zu vermeiden, sollten Sie Ihre Zugriffe nach Möglichkeit auf den ganzen Tag verteilen. Wenn Ihr Kunde eine tägliche Synchronisierung durchführen muss, bitte ihn, eine zufällige Uhrzeit festzulegen (für jeden Kunden unterschiedlich). Wenn Sie eine Aktion regelmäßig ausführen müssen, variieren Sie das Intervall um +/- 25%. Dadurch wird der Traffic gleichmäßiger verteilt und die Nutzerfreundlichkeit wird deutlich verbessert.
Push-Benachrichtigungen verwenden
Ein häufiger Anwendungsfall ist die Ausführung einer Aktion, wenn sich etwas im Kalender des Nutzers ändert. Ein Anti-Muster besteht darin, jeden relevanten 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 ein Minutenkontingent von mindestens 5.000 erforderlich, bevor überhaupt etwas passiert.
Serverseitige Anwendungen können sich für Push-Benachrichtigungen registrieren. So können wir Sie benachrichtigen, wenn etwas Interessantes passiert. Die Einrichtung ist etwas aufwendiger, aber Sie können Ihr Kontingent so deutlich effizienter nutzen und die Nutzerfreundlichkeit verbessern. Geben Sie die eventType an, für die Sie benachrichtigt werden möchten. Weitere Informationen finden Sie unter Push-Benachrichtigungen.
Korrekte Abrechnung mit Dienstkonten
Wenn Ihre Anwendung Anfragen mithilfe der domainweiten Delegierung ausführt, werden die Kontingente „pro Minute pro Projekt pro Nutzer“ standardmäßig dem Dienstkonto und nicht dem Nutzer in Rechnung gestellt, für den Sie sich ausgeben. Das bedeutet, dass das Dienstkonto wahrscheinlich das Kontingent aufbrauchen und eine Ratenbegrenzung erhalten wird, auch wenn es möglicherweise in den Kalendern mehrerer Nutzer verwendet wird. Sie können dies vermeiden, indem Sie mit dem URL-Parameter quotaUser (oder dem HTTP-Header x-goog-quota-user) angeben, welcher Nutzer belastet werden soll. Dieser Wert wird nur für die Berechnung von Kontingenten verwendet. Weitere Informationen finden Sie in der Cloud-Dokumentation 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 Ihnen dringend, dieses Szenario in einer echten Umgebung zu testen.
Damit ein solcher Test nicht die tatsächliche Anwendung beeinträchtigt, empfehlen wir, ein separates Testprojekt in der Google API Console zu registrieren und es ähnlich wie Ihr Produktionsprojekt zu konfigurieren. Sie können dann künstlich niedrige Kontingente für dieses Projekt festlegen und das Verhalten Ihrer Anwendung beobachten.
Preise
Die Nutzung der Google Calendar API ist kostenlos. Wenn Sie die Kontingentlimits für Anfragen überschreiten, fallen keine zusätzlichen Kosten an und es werden keine Kosten in Ihrem Konto in Rechnung gestellt.