Diese Seite richtet sich an Administratoren und Integratoren, die Gerät« einstellungen über Hermetry ändern, manuell oder über die API, auf einem Gerät oder auf vielen. Sie erklärt die Regeln hinter dem Reiter Settings und wie man sie sicher nutzt. Wie man den Reiter öffnet, Baselines anlegt und Jobs startet, steht unter Remote device settings; die Routen stehen unter Firmware and device settings API.
Soll- und Istwerte
Für jeden Einstellungsabschnitt eines Geräts führt Hermetry zwei Dokumente:
- Soll: was Hermetry dem Gerät zuletzt zu betreiben aufgetragen hat, mit einer Revisionsnummer, die mit jeder Änderung steigt.
- Ist: was das Gerät meldet, dass es betreibt, mit der Revision, die es angewendet hat.
Jede Änderung sendet den gesamten Abschnitt an das Gerät, nicht nur die geänderten Schlüssel. Das Gerät wendet einen Abschnitt nur an, wenn seine Revision höher ist als die zuletzt angewendete. Ein Abschnitt, der zu lange auf das Gerät gewartet hat, wird zurückgezogen; das Gerät behält dann die Einstellungen, die es hat.
| Status im Reiter Settings | Bedeutung |
|---|---|
| Unterwegs | Gesendet oder wartet darauf, dass das Gerät online kommt |
| Gerät probiert es aus | Das Gerät führt die Änderung probeweise aus und macht sie selbstständig rückgängig, wenn es die Cloud nicht wieder erreicht |
| Angewendet | Das Gerät führt die Änderung aus |
| Vom Gerät rückgängig gemacht | Das Gerät hat sie probiert und ist zurückgegangen |
| Vom Gerät abgelehnt | Das Gerät hat sie nicht akzeptiert |
| Gerät war offline | Die Änderung hat zu lange gewartet (7 Tage für eine einzelne Änderung) und wurde zurückgezogen |
| Prüfung nach Update | Ein Firmware-Update hat die Beschreibung des Abschnitts geändert; eine Person muss prüfen und speichern |
| Am Gerät geändert | Drift: Das Gerät betreibt andere Werte, als Hermetry angefordert hat (siehe unten) |
| Von hier aus nicht geändert | Hermetry hat diesen Abschnitt nie gesetzt; es zeigt nur an, was das Gerät meldet |
Wie eine Änderung aufgebaut wird
Es gibt zwei Arten, einen Abschnitt zu schreiben, und sie behandeln Weggelassenes unterschiedlich.
| Art | Verwendet von | Was man sendet |
|---|---|---|
| Ganzer Abschnitt | Der Reiter Settings, PUT | Jeder Wert des Abschnitts. Was man weglässt, gehört nicht zum neuen Abschnitt. |
| Merge-Patch | PATCH, Baselines, Einstellungsjobs | Nur das, was sich ändert, als JSON Merge Patch (RFC 7386) |
Ein Merge-Patch folgt genau diesen Regeln:
- Objekte werden Schlüssel für Schlüssel zusammengeführt. Ein Schlüssel, den man nicht nennt, behält seinen Wert.
nullentfernt den Schlüssel.- Jeder andere Wert ersetzt den alten vollständig. Eine Liste wird immer vollständig ersetzt: Um einen Eintrag einer Liste zu ändern, sendet man die komplette Liste.
Der Patch wird auf das letzte Soll-Dokument des Abschnitts angewendet, nicht auf das, was das Gerät meldet. Nur wenn Hermetry den Abschnitt nie gesetzt hat, startet ein Patch bei den gemeldeten Werten; hat das Gerät den Abschnitt auch noch nicht gemeldet, wird der Schreibvorgang abgelehnt (section_not_reported).
Bewährte Praxis:
- Nur das in eine Baseline aufnehmen, was man ändern will. Alles andere bleibt auf jedem Gerät, wie es ist.
nullnur dann in eine Baseline aufnehmen, wenn der Schlüssel auf jedem Gerät des Jobs verschwinden soll.- Gerätespezifische Listen (zum Beispiel Adresslisten, die sich je Standort unterscheiden) nicht in Baselines aufnehmen: Die Liste der Baseline ersetzt die Liste jedes Geräts.
- Einstellungen, die die Beschreibung als nur am Gerät änderbar kennzeichnet, werden aus dem Bericht des Geräts übernommen. Eine Änderung daran wird abgelehnt (
remote_forbidden). - Mit
?dryRun=true(oder Check in einem Job) prüfen, welche Einstellungen eine Änderung berührt und ob sie eine Bestätigung braucht, bevor etwas gesendet wird.
Revisionen und If-Match
Beim Lesen eines Abschnitts wird seine Soll-Revision als ETag-Header in der Form W/"7" zurückgegeben. Jeder Schreibvorgang muss diese Revision in If-Match zurücksenden; "7" und 7 werden ebenfalls akzeptiert.
| Antwort | Bedeutung |
|---|---|
428 if_match_required | Der Schreibvorgang hatte kein If-Match |
412 rev_mismatch | Jemand hat den Abschnitt geändert, nachdem Sie ihn gelesen haben |
Bei 412 den Abschnitt erneut lesen, die Änderung auf dem neuen Dokument neu aufbauen und erneut schreiben. Die neue Revision nicht in den Header kopieren und das alte Dokument erneut senden: Das würde die Änderung der anderen Person überschreiben. Der Reiter Settings führt dieselbe Prüfung durch („Someone else changed these settings since you opened them. Load them again to see the latest.“).
Drift
Ein Abschnitt ist abgewichen, wenn das Gerät eine Änderung von Hermetry angewendet hat und später abweichende Werte meldet, meist weil jemand sie direkt am Gerät geändert hat. Der Reiter zeigt „Changed on the device“ und die Unterschiede. Hermetry korrigiert Drift nicht von selbst. Sie wählen:
| Aktion | Wirkung |
|---|---|
| Unsere erneut senden | Sendet die Soll-Werte von Hermetry erneut als neue Revision |
| Die des Geräts behalten | Speichert die aktuellen Werte des Geräts als neue Soll-Werte |
Drift auflösen, bevor man einen abgewichenen Abschnitt auf andere Weise ändert. Ein Merge-Patch und damit ein Einstellungsjob startet beim letzten Soll-Dokument und sendet daher auch die Werte von Hermetry für die abgewichenen Einstellungen zurück.
Festlegen, wer jede Einstellung verantwortet. Wenn Techniker vor Ort etwas ändern können müssen, das Element aus Baselines und Jobs heraushalten.
Geheimnisse
- Geheime Einstellungen (Passwörter, Schlüssel) werden nie angezeigt oder zurückgegeben. Sie erscheinen als
{ "set": true }. - Ein neues Geheimnis gelangt als einmalige Referenz an das Gerät. Das Gerät holt den Wert einmal über eine signierte Anfrage ab; eine Referenz, die nicht abgeholt wird, verfällt nach 30 Tagen. Ein Gerät, dessen Firmware keine Referenzen abrufen kann, erhält gar kein Geheimnis: Die Änderung wird abgelehnt (
secret_ref_unsupported). - Um das aktuelle Geheimnis des Geräts beizubehalten, das Feld unverändert lassen (in der API
{ "$keep": true }). - Baselines können keine Geheimnisse enthalten (
secret_not_allowed). Sie auf jedem Gerät einzeln setzen. secret_pending: Eine frühere Änderung enthält ein Geheimnis, das das Gerät noch nicht abgeholt hat. Darauf warten oder das Geheimnis erneut eingeben.secrets_need_rewritebei Erneut senden: Die Änderung enthält Geheimnisse, die das Gerät nicht mehr abholen kann. Sie erneut eingeben und speichern.
Einstellungsjobs
Ein Job wendet eine Baseline oder eine einzelne Änderung auf viele Geräte in Wellen an. Bewährte Praxis:
- Nach Modell und Firmware auswählen, die Sie getestet haben. Der Schritt Check zeigt die Geräte je Modell und Firmware sowie die Abschnitte, die ein Modell nicht hat.
- Die Wellen beibehalten. Standard sind 1 %, dann 10 %, dann der Rest. Die erste Welle ist ein fester Zufallsquerschnitt der ausgewählten Geräte.
- Die Freigabebedingung verstehen. Eine Welle gilt als bestanden, wenn unter den Geräten, die geantwortet haben, mindestens 95 % die Änderung angewendet und höchstens 1 % sie rückgängig gemacht haben (die Standardwerte). Geräte, die abgelehnt haben, zählen zu den antwortenden und senken daher den Anteil angewendeter Änderungen. Noch offline befindliche Geräte zählen nicht. Eine Welle wird bewertet, wenn alle ihre Geräte geantwortet haben, oder 30 Minuten nach ihrem Start (Standard) bei den bis dahin antwortenden Geräten; die übrigen laufen im Hintergrund weiter. Eine bestandene Welle startet die nächste sofort, ohne Wartezeit. Eine Welle, in der kein Gerät geantwortet hat, hält den Job an.
- Festlegen, was bei einem Konflikt geschieht. Auf dem Abschnitt eines Geräts darf nur eine Änderung zur Zeit laufen. Ein Job wartet auf die Änderung eines anderen Jobs (und überspringt das Gerät nach 24 Stunden) oder überspringt es sofort. Eine Änderung, die eine Person während des Wartens des Jobs vornimmt, hat Vorrang.
- Festlegen, wie lange auf Offline-Geräte gewartet wird: standardmäßig 7 Tage, 1 bis 90.
- Beachten, dass Abbrechen nicht zurückrollt. Bereits geänderte Geräte behalten ihre neuen Einstellungen.
Ein Job schreibt mit den Berechtigungen seines Erstellers, und ein Job, der gefährliche Einstellungen ändert, muss bei der Erstellung bestätigt werden. Höchstens 5 Jobs laufen oder warten pausiert gleichzeitig, ein Job umfasst bis zu 5.000 Geräte, und es werden Änderungen an höchstens 200 Geräte pro Minute gesendet.
Firmware-Updates und alte Firmware
- Nach einem Firmware-Update überführt Hermetry die gespeicherten Sollwerte in die Einstellungsbeschreibung der neuen Firmware. Was sich nicht sicher überführen lässt, wird mit „Check after update“ markiert. Der Abschnitt bleibt in diesem Zustand, bis eine Person ihn speichert; Meldungen vom Gerät schließen ihn nicht, und ein Job zählt ein solches Gerät als abgelehnt.
- Unterstützungszeitraum: Schreibzugriffe auf Einstellungen enden 24 Monate nach dem Veröffentlichungsdatum der Firmware des Geräts, wie es in dessen Einstellungsbeschreibung vermerkt ist. Die Einstellungen bleiben lesbar („Read only: update the firmware to change settings“). Ein Schreibzugriff beantwortet
409firmware_too_oldmit dem Datum, an dem der Zeitraum endete. - Ein Job schließt solche Geräte nicht im Voraus aus. Sie werden abgelehnt, wenn sie an die Reihe kommen, und zählen gegen die Schranke der Welle. Aktualisieren Sie zuerst ihre Firmware oder nehmen Sie sie nicht in die Auswahl auf.
Änderungsrate
Einzelne Änderungen über den Reiter Settings und die API, einschließlich Send again, sind auf 600 pro Minute und Organisation begrenzt; darüber hinaus 429 write_rate_limited. Schreibzugriffe eines Jobs auf seine Geräte zählen nicht dazu.

