Durch Limits und Kontingente wird die Google-Infrastruktur vor automatisierten Prozessen geschützt, die die Reports API auf unangemessene Weise verwenden. Eine übermäßige Anzahl von Anfragen an eine API kann durch einen harmlosen Tippfehler oder ein ineffizient gestaltetes System verursacht werden, das unnötige API-Aufrufe ausführt. Unabhängig von der Ursache ist es für den Gesamtzustand des Google Workspace-Systems wichtig, den Traffic von einer bestimmten Quelle zu blockieren, sobald er einen bestimmten Wert erreicht. So wird sichergestellt, dass die Aktionen eines Entwicklers keine negativen Auswirkungen auf die gesamte Community haben.
Im unwahrscheinlichen Fall, dass Ihre API-Anfrage fehlschlägt, erhalten Sie eine Antwort mit einem HTTP-Statuscode. Ein Statuscode 403 enthält Fehlerinformationen zu einer falschen Eingabe und ein HTTP-Statuscode 503 enthält Fehlerinformationen, die angeben, welche API-Kontingente überschritten wurden. Anhand dieser Antworten kann Ihre benutzerdefinierte Anwendung diese Fehler erkennen und entsprechende Maßnahmen ergreifen.
Wenn Ihre Anfragen innerhalb eines bestimmten Zeitraums abgeschlossen werden müssen, senden Sie sie parallel oder verwenden Sie mehrere Threads in Ihrer Java- oder C#-Anwendung. Ein Beispiel für parallele Anfragen ist das Anfordern kleiner Batches von E-Mails von verschiedenen Nutzern, anstatt viele E-Mails von einem Nutzer gleichzeitig hinzuzufügen oder zu entfernen. Bei Threads sollten Sie mit 10 Threads beginnen, einem Thread pro E-Mail-Adresse des Nutzers. Die Empfehlung für Threads hat Nachteile und ist nicht für alle API-Situationen nützlich. Wenn die Anzahl der Anfragen zu hoch ist, treten Kontingentfehler auf.
Bei allen zeitbasierten Fehlern (maximal N Vorgänge für N Sekunden pro Thread), insbesondere bei Fehlern mit dem Statuscode 503, empfehlen wir, dass Ihr Code die Ausnahme abfängt und mit einem exponentiellen Backoff-Algorithmus eine kurze Zeit wartet, bevor er den fehlgeschlagenen Aufruf wiederholt. Ein Beispiel für die Reports API für einen Thread ist, 5 Sekunden zu warten und den fehlgeschlagenen Aufruf noch einmal zu versuchen. Wenn die Anfrage erfolgreich ist, wiederholen Sie diesen Vorgang für die anderen Threads. Wenn die zweite Anfrage nicht erfolgreich ist, sollte die Häufigkeit der Anfragen in Ihrer Anwendung reduziert werden, bis ein Aufruf erfolgreich ist. Erhöhen Sie beispielsweise die anfängliche Verzögerung von 5 Sekunden auf 10 Sekunden und versuchen Sie es noch einmal. Legen Sie außerdem ein Limit für Wiederholungsversuche fest. Wiederholen Sie eine Anfrage beispielsweise 5- bis 7-mal mit unterschiedlichen Verzögerungszeiten, bevor Ihre Anwendung einen Fehler an den Nutzer zurückgibt.
Limits
| API-Limitkategorien | Limits |
|---|---|
| Raten für Abfragen pro Sekunde und Abfragen pro Tag melden | Die API begrenzt die Anzahl der Anfragen für Ihr Google Cloud-Projekt.
Der in der Google Cloud Console festgelegte Standardwert beträgt 2.400 Anfragen pro Minute pro Nutzer und Google Cloud-Projekt.
Sie können dieses Limit auf der Seite Admin SDK API Quotas Ihres Google Cloud-Projekts erhöhen.
Wenn diese Limits überschritten werden, gibt der Server den HTTP-Statuscode 503 zurück. Verwenden Sie den exponentiellen Backoff-Algorithmus, wenn Sie Anfragen wiederholen. |
Zusätzliche Limits für activities.list |
Für die activities.list API gilt ein zusätzliches Limit von 250 Filterabfragen pro Minute (15.000 Filterabfragen pro Stunde).
Eine Filterabfrage ist eine API-Anfrage, die mindestens einen der folgenden Abfrageparameter enthält:
|
| API-Kontingentkategorien | Kontingente |
| maxResults | Die Anzahl der Datensätze, die auf jeder Seite der Antwort einer API aufgeführt sind, liegt zwischen 0 und 1.000. Der Standardwert ist 1.000 Datensätze. |
Andere Arten von Limits
| Andere Arten von Limits | Einschränkungen und Richtlinien |
|---|---|
| Standarddatenformat | Das Standarddatenformat ist JSON. Die API unterstützt auch das Atom-Format. |
| Nicht autorisierte Anfragen | Google lässt keine unautorisierten Anfragen an die API zu. Eine Anfrage gilt als nicht autorisiert, wenn kein Autorisierungstoken angegeben wird. Weitere Informationen finden Sie unter Anfragen autorisieren. |
| Warnmeldungen |
|
Best Practices für activities.list
Die Methode activities.list soll für Audit-Untersuchungen verwendet werden.
Für eine optimale Leistung sollte Ihre Anfrage einen Zeitraum enthalten, der mit den Parametern startTime und endTime angegeben wird. Bei kürzeren Zeiträumen sind die Reaktionszeiten deutlich kürzer.
Diese Methode ist nicht für den Abruf großer Mengen von Audit-Logs vorgesehen. Wenn Sie Ihr Kontingent für Filteranfragen für activities.list regelmäßig ausschöpfen, sollten Sie die folgenden Optionen in Betracht ziehen:
- Richten Sie den Export von Google Workspace-Logs nach BigQuery ein und verwenden Sie die leistungsstarken BigQuery-Abfrage-APIs, um die benötigten Daten ohne API-Kontingentbeschränkungen abzurufen und zu analysieren.
- Verwenden Sie Anfragen ohne Filter mit einem Zeitraum und führen Sie die Filterung clientseitig durch (d.h. die Filterlogik in Ihrer Anwendung), anstatt Filteranfragen zu verwenden. So können Sie das Limit von 250 Filterabfragen pro Minute überschreiten. Das Limit von 2.400 Abfragen pro Minute und Nutzer und Google Cloud-Projekt gilt jedoch weiterhin.