Kontingente verwalten

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:

  • API-Nutzungskontingente werden pro Projekt und pro Nutzer erzwungen. Weitere Informationen finden Sie im nächsten Abschnitt.
  • Allgemeine Nutzungsbeschränkungen für Kalender: Vermeiden Sie Nutzungsbeschränkungen für Kalender.
  • Betriebliche Einschränkungen:Es kann jederzeit zu einer Ratenbegrenzung kommen. Das kann beispielsweise passieren, wenn Sie versuchen, in kurzer Folge in einen einzelnen Kalender zu schreiben.

Arten von Kontingenten für die Nutzung der Calendar 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, Projekt und Nutzer:Dies ist die Anzahl der Anfragen, die von einem bestimmten Nutzer in Ihrem Cloud-Projekt gestellt werden. Dieses Limit soll Ihnen helfen, eine faire Verteilung der Nutzung auf Ihre Nutzer zu gewährleisten.

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

Wenn eines der beiden Kontingente überschritten wird, wird die Ratenbegrenzung angewendet und Sie erhalten für Ihre Anfragen den 403 usageLimits-Statuscode oder den 429 usageLimits-Statuscode. In diesem Fall haben Sie folgende Möglichkeiten:

  1. Achten Sie darauf, alle Best Practices zu befolgen: Exponentielles Backoff verwenden, Traffic-Muster randomisieren, Push-Benachrichtigungen verwenden.
  2. Wenn Ihr Projekt wächst und Sie mehr Nutzer haben, können Sie eine Erhöhung des Kontingents pro Projekt beantragen.
  3. 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 jedoch im Allgemeinen nicht empfohlen, es über den Standardwert hinaus zu erhöhen, da Ihre Anwendung sonst möglicherweise andere Arten von Beschränkungen erreicht, z. B. Beschränkungen für die allgemeine Kalendernutzung oder betriebliche Beschränkungen.

Kontingenterhöhung anfordern

Wenn Sie die Nutzungslimits für Ihr Projekt aufrufen oder ändern bzw. eine Erhöhung Ihres Kontingents anfragen möchten, gehen Sie so vor:

  1. Wenn Sie für Ihr Projekt noch kein Rechnungskonto haben, erstellen Sie dieses.
  2. 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.
  3. 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 möchten, dass Sie die Häufigkeit Ihrer Anfragen verringern, geben wir eine 403-Antwort vom Typ „usageLimits“ oder eine 429-Antwort zurück (siehe vollständige Fehlerdokumentation). Dies ist kein schwerwiegender Fehler. Wir empfehlen, die Anfrage nach kurzer Zeit noch einmal zu senden. Wenn Anfragen weiterhin zu schnell eingehen, werden wir Sie noch einmal bitten, die Geschwindigkeit zu reduzieren. Damit das richtig funktioniert, müssen die Verzögerungen zwischen den Anfragen mit der Zeit zunehmen.

Im Allgemeinen sollten Sie den abgeschnittenen exponentiellen Backoff verwenden. In der Cloud Storage-Dokumentation wird gut erklärt, wie dieser funktioniert und welcher Algorithmus bevorzugt wird. Wenn Sie eine Google-Clientbibliothek verwenden, wird dies normalerweise für Sie erledigt. Weitere Informationen finden Sie in der Dokumentation der Bibliothek. Normalerweise sollten Sie die Bibliotheksimplementierung verwenden, anstatt eine eigene zu schreiben.

Trafficmuster zufällig anordnen

Kalenderclients sind anfällig für unregelmäßige Trafficmuster, 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 Ratenbeschränkungen 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, die für jeden Kunden unterschiedlich ist. 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, dass Sie eine Aktion ausführen möchten, wenn sich etwas im Kalender des Nutzers ändert. Ein Anti-Pattern ist es, jeden interessierenden Kalender wiederholt abzufragen. Dadurch wird Ihr Kontingent sehr schnell aufgebraucht. Wenn Ihre Anwendung beispielsweise 5.000 Nutzer hat und der Kalender jedes Nutzers einmal pro Minute abgefragt wird, ist ein Minutenkontingent von mindestens 5.000 erforderlich, noch bevor überhaupt etwas passiert.

Serverseitige Anwendungen können sich für Push-Benachrichtigungen registrieren. So können wir Sie benachrichtigen, wenn etwas Interessantes passiert. 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, für die Sie benachrichtigt werden möchten. Weitere Informationen finden Sie unter Push-Benachrichtigungen.

Ordnungsgemäße Abrechnung mit Dienstkonten

Wenn Ihre Anwendung Anfragen mit domainweiter Delegierung ausführt, wird das Dienstkonto standardmäßig in Bezug auf die Kontingente „pro Minute pro Projekt pro Nutzer“ belastet und nicht der Nutzer, den Sie imitieren. Das bedeutet, dass das Dienstkonto wahrscheinlich das Kontingent überschreitet und die Ratenbegrenzung erreicht, auch wenn es für die Kalender mehrerer Nutzer verwendet wird. Sie können dies vermeiden, indem Sie den URL-Parameter quotaUser (oder den HTTP-Header x-goog-quota-user) verwenden, um anzugeben, welcher Nutzer in Rechnung gestellt wird. Dieser Wert wird nur für die Berechnung des Kontingents verwendet. Weitere Informationen finden Sie in der Clouddokumentation unter Anfragen pro Nutzer begrenzen.

Kontingentlimit-Verarbeitung 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, dieses Szenario in einer realen Umgebung zu testen.

Damit ein solcher Test nicht die Nutzung Ihrer echten Anwendung beeinträchtigt, empfehlen wir, ein separates reines Testprojekt in der Google API Console zu registrieren und es ähnlich wie Ihr Produktionsprojekt zu konfigurieren. Anschließend können Sie für dieses Projekt künstlich niedrige Kontingente 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 Gebühren an und Ihr Konto wird nicht belastet.