Nutzer- und Ratenlimits

Device Access -Projekte sind je nach Umgebung und Art des kommerziellen Angebots durch Nutzer-, Struktur- und Ratenlimits eingeschränkt.

Wir möchten, dass Entwickler ansprechende Nutzererfahrungen schaffen, aber auch, dass der Nest-Dienst und die Nest-Geräte immer für Nutzer verfügbar sind. Integrationen, die innerhalb eines bestimmten Zeitraums eine große Anzahl von Anfragen stellen, können sich auf die Verfügbarkeit von Diensten und Geräten auswirken. Daher gelten für die SDM API Ratenbeschränkungen. Durch die Begrenzung der Rate wird die Anzahl der API-Aufrufe für einen bestimmten Zeitraum eingeschränkt und eine Übernutzung der Ressourcen verhindert.

Limits nach Umgebung

Alle Projekte beginnen in der   Sandbox-Umgebung  . Die Sandbox ist für die Bewertung der SDM API und den persönlichen Gebrauch gedacht. Die Limits sind entsprechend eingeschränkt. Für Umgebungen mit einer größeren Nutzerbasis, z. B.   kommerzielle Entwicklung  , gelten andere Limits.

Limits für Sandbox-Nutzer

Ein Entwicklerkonto in der Sandbox ist auf 25 Nutzer in 5 Strukturen in allen Projekten beschränkt. Pro Konto sind maximal drei Projekte zulässig.

Gebäude sind auf jeweils 5 Nutzer beschränkt. Das Nutzerlimit wird also erst erreicht, wenn alle 5 Gebäude mit jeweils 5 Nutzern belegt sind. Das Entwicklerkonto (zu dem das Projekt gehört) wird nicht auf das Limit von fünf Nutzern für ein Gebäude angerechnet.

Wenn ein Projekt hingegen 15 Nutzer in 5 Gebäuden hat, können zusätzliche Nutzer nur den vorhandenen 5 Gebäuden hinzugefügt werden, da das Gebäudelimit bereits erreicht wurde.

Ratenlimits für die Sandbox

Die Sandbox ist auf drei verschiedenen Ebenen ratenbegrenzt. Sofern nicht anders angegeben, sind die Limits in Abfragen pro Minute (Queries per minute, QPM) festgelegt.

API-Ebene

API-Aufrufe sind pro Projekt und Nutzer begrenzt. Weitere Informationen zu den einzelnen Methoden finden Sie in der API-Referenz.

API-Methode Ratenbegrenzung
devices.executeCommand 10 Abfragen pro Minute
devices.get 10 Abfragen pro Minute
devices.list 5 Abfragen pro Minute
structures.get 5 Abfragen pro Minute
structures.list 5 Abfragen pro Minute
structures.rooms.get 5 Abfragen pro Minute
structures.rooms.list 5 Abfragen pro Minute

Befehlsebene

Jeder Merkmalsbefehl (devices.executeCommand) ist auf 5 Anfragen pro Minute pro Projekt, pro Nutzer und pro Gerät beschränkt.

Wenn ein Projekt also zwei Nutzer mit jeweils zwei Geräten hat (insgesamt vier Geräte), kann derselbe Befehl für jedes dieser vier Geräte fünfmal pro Minute aufgerufen werden.

Wenn ein Projekt jedoch zwei Nutzer mit jeweils drei Geräten hat, also insgesamt sechs Geräte, kann derselbe Befehl nicht für jedes dieser sechs Geräte fünfmal pro Minute aufgerufen werden. Das würde 15 QPM pro Nutzer ergeben, wenn die Ratenbeschränkung auf devices.executeCommand API-Ebene für den Nutzer eines Projekts 10 QPM beträgt.

Geräteinstanzebene

Außerdem werden für den Akkuschutz des Geräts Limits auf Geräteinstanzebene für alle Projekte und Befehle (devices.executeCommand) implementiert. Diese Limits gelten sowohl für Abfragen pro Minute als auch für Abfragen pro Stunde und nicht für die API-Methoden get und list.

Angenommen, Projekt A und Projekt B haben beide Zugriff auf dasselbe Gerät, Gerät A. Möglicherweise hat der Nutzer zwei verschiedene kommerzielle Integrationen autorisiert, die dasselbe Gerät verwenden. Wenn Projekt A innerhalb einer Minute vier Befehle an Gerät A gesendet hat, kann Projekt B in derselben Minute nur einen Befehl an Gerät A senden, bevor das Ratelimit auf Geräteinstanzenebene erreicht wird. Ab diesem Zeitpunkt werden Befehle von beiden Projekten an Gerät A bis zum Ende der Minute gedrosselt, die mit dem ersten Befehl an Gerät A begonnen hat.

Wenn ein Gerätetyp unten nicht aufgeführt ist, gelten für ihn keine Taktfrequenzlimits auf Geräteinstanzebene.

Gerätetyp Ratenlimit für Geräteinstanzen
THERMOSTAT 5 Abfragen pro Minute oder 100 Abfragen pro Stunde
KAMERA 30 Abfragen pro Minute oder 100 Abfragen pro Stunde
TÜRKLINGEL 30 Abfragen pro Minute oder 100 Abfragen pro Stunde

Fehler

In Bezug auf diesen Leitfaden können die folgenden Fehlercodes zurückgegeben werden:

Fehlermeldung RPC Fehlerbehebung
Ratenbegrenzung. RESOURCE_EXHAUSTED Für jeden Entwickler gilt ein Kontingent, das die Anzahl der Aufrufe begrenzt. Wenn Sie mehr Anrufe als Ihr Kontingent starten, erhalten Sie die Meldung „Anzahl der Anrufe begrenzt“. Reichen Sie den Anruf noch einmal ein, sobald das Kontingent abgelaufen ist.

Eine vollständige Liste der API-Fehlercodes findest du in der API-Fehlercode-Referenz.