Devices-API

Die Devices-API listet Geräte auf, ruft sie ab, aktualisiert und löscht sie und versetzt sie in den Wartungsmodus — einzeln oder für viele Geräte auf einmal. Hinweis: Alle Geräte-Endpoints verwenden den Pfadpräfix /api/assets. Der Begriff „asset“ wird intern im Backend verwendet; die UI und Dokumentation sprechen von Geräten (Devices).

Die vollständige, stets aktuelle Liste der Endpoints, Parameter und Antwortfelder für die Version, die du betreibst, findest du in der interaktiven OpenAPI-Oberfläche (Swagger) unter https://<deine-octoja-instanz>/openapi/index.html.

Endpoints

Hinweis zur Abruf-Antwort: settings enthält die sieben gerätebezogenen Agent-Einstellungen (jeweils mit ihrem effektiven Wert, einer eventuellen gerätebezogenen Übersteuerung und den Konfigurationspaketen, die sie aktivieren), und canBypassRemoteDesktopConsent spiegelt die eigene Berechtigung des Aufrufers wider und ist keine Geräteeinstellung. customFields enthält die Werte der eigenen Felder des Geräts, jeweils unter ihrem Feldschlüssel. agentlessData und agentlessInventoryAt tragen den separaten Inventar-Snapshot eines agentenlosen Geräts und den Zeitpunkt, zu dem er geschrieben wurde; monitoringAssetName nennt das Gerät, das es überwacht, und bleibt null, wenn dieses Gerät außerhalb deines Zugriffsbereichs liegt. deviceMaintenanceWindow ist das an diesem Gerät hinterlegte Wartungsfenster oder null, wenn es keines hat. Die vollständige Feldstruktur findest du in Swagger.

Hinweis zu den Berechtigungen: Das Aktualisieren und Löschen eines Geräts nutzt octojas gerätebezogene Aktionsberechtigungen — die Berechtigungen Gerät bearbeiten und Gerät löschen, die deine Gruppe für genau dieses Gerät besitzt — und keine einzelne globale Berechtigung. Der Gruppenzugriff steuert, für welche Geräte die jeweilige Berechtigung gilt.

Hinweis zu den Bulk-Endpoints: Jeder erwartet ein assetIds-Array mit bis zu 500 Geräte-IDs und antwortet mit der Anzahl der geänderten Geräte. Sie gelten nach dem Alles-oder-nichts-Prinzip: Sobald eine ID in der Liste außerhalb deines Zugriffsbereichs liegt oder die nötige Berechtigung fehlt, liefert der gesamte Aufruf 404 Not Found, und kein Gerät wird geändert.

Ein Gerät aktualisieren

Alle Aktualisierungsfelder sind optional — sende nur die zu ändernden Felder. Jedes Feld wird in eine UpdateValue<T>-Hülle der Form { "hasValue": true, "value": <T> } verpackt; lass das Feld komplett weg, um es unverändert zu lassen. Ein nackter Wert (zum Beispiel "deviceAlias": "web-01") wird nicht gebunden. Mit { "hasValue": true, "value": null } kannst du einen Wert löschen.

{
  "deviceAlias": { "hasValue": true, "value": "web-01" },
  "customerId": { "hasValue": true, "value": null }
}

Die aktualisierbaren Felder sind deviceAlias, customerId, customerSiteId, tags, deviceKind und customFields (die genauen Typen stehen in Swagger). Einige Verhaltensweisen und Validierungen sind im Schema nicht sichtbar:

• deviceAlias — wird getrimmt, max. 100 Zeichen; ein null-Wert leert den Alias.
• customerId — ein null-Wert hebt die Kundenzuweisung auf; das ist Aufrufern vorbehalten, deren Gruppe Alle Kunden umfasst — alle anderen erhalten 400 Bad Request. Beim Wechsel des Kunden wird die gespeicherte customerSiteId auf null zurückgesetzt; sende customerSiteId in derselben Anfrage mit, wenn das Gerät seine Standortzuweisung behalten soll.
• customerSiteId — setzt einen effektiven Kunden voraus: entweder die mitgesendete customerId oder die aktuell gespeicherte customerId des Geräts darf nicht null sein.
• tags — ersetzt nur benutzerdefinierte Tags; inventar-basierte Tags bleiben immer erhalten und können nicht über die API entfernt werden. Maximal 50 Tags, je 100 Zeichen. Werte, die bereits im Tag-Katalog für Geräte stehen, darf jeder anwenden; einen noch nicht vorhandenen Wert einzuführen erfordert die Berechtigung Benutzerdefinierte Tags erstellen und liefert ohne sie 403 Forbidden.
• deviceKind — überschreibt die klassifizierte Gerätekategorie. Sie ist einer aus einer festen Menge von Werten (siehe Swagger); ein ungültiger Wert führt zu 400 Bad Request.
• customFields — ein Objekt aus Feldschlüssel und Wert, geprüft gegen die Definitionen der eigenen Felder für Geräte. Ein Wert, der nicht zum Typ seines Felds passt, führt zu 400 Bad Request; ein leerer Wert leert das Feld, und Schlüssel ohne passende Definition werden ignoriert. Die gesendete Map ersetzt alle gespeicherten eigenen Felder. Verpacke sie als { "customFields": { "hasValue": true, "value": { … } } } und nimm jedes Feld auf, das erhalten bleiben soll. Nicht mitgesendete Schlüssel verlieren ihren Wert; lass customFields komplett weg, um alle Werte unverändert zu lassen.

Um nur ein eigenes Feld zu ändern, nutze POST /api/assets/bulk-set-custom-field mit den einfachen Feldern assetIds, key und value, ohne UpdateValue-Hülle. Du kannst ein einzelnes Gerät oder bis zu 500 Geräte angeben. key muss zu einer vorhandenen Definition für eigene Gerätefelder gehören, und value muss zu deren Typ passen. Mit "value": null entfernst du nur diesen Feldwert; alle anderen Schlüssel bleiben erhalten. Die Antwort enthält updatedCount. Es gelten dieselben Zugriffsprüfungen wie für die anderen Bulk-Endpoints oben.

Der Update-Endpoint akzeptiert außerdem sieben gerätebezogene Übersteuerungen der Agent-Einstellungen. Jede ist ein nullbarer Boolean: true erzwingt die Einstellung, false deaktiviert sie erzwungen, und null entfernt die Übersteuerung, sodass das Gerät den Wert aus seinen Konfigurationspaketen erbt:

• requiresRemoteDesktopConsent — den angemeldeten Benutzer vor jeder Remotedesktop-Sitzung um Erlaubnis bitten.
• allowRdsHostPhysicalConsoleWithoutConsent — auf Terminalservern die Abfrage nur für eine Windows-Sitzung an der physischen Konsole überspringen. RDP-Sitzungen erfordern weiterhin eine Zustimmung.
• showAgentInTray — das Agent-Symbol im Traybereich des Geräts anzeigen.
• softwareKioskEnabled — den Self-Service-Software-Kiosk aktivieren.
• ticketingEnabled — das Erstellen von Supportfällen von diesem Gerät aus aktivieren.
• autoLockOnDisconnect — das Gerät automatisch sperren, wenn eine Remotedesktop-Sitzung getrennt wird.
• uninstallProtection — den Agent auf diesem Gerät aus „Programme und Features“ ausblenden, sodass Benutzer ihn dort nicht deinstallieren können. Über das Löschen des Geräts in octoja lässt er sich weiterhin entfernen.

Ein Gerät löschen

Entfernt das Gerät aus octoja — es erscheint nicht mehr in der Geräteliste und kann nicht mehr über die API abgerufen werden. Der zugehörige Agenten-Datensatz wird ebenfalls gelöscht.

Wartungsmodus

Ein Wartungsfenster pausiert die von dir gewählten Aktivitäten auf einem Gerät, solange es offen ist. Der Request-Body lautet { "window": { … } }; mit { "window": null } beendest du die Wartung sofort. Jedes Fenster trägt die Schalter suppressChecks, suppressAutomations, suppressAlerts, suppressDeployments und suppressPatches sowie einen kind, der bestimmt, welche Zeitfelder gelten:

• AdHoc — startet, sobald die Anfrage eintrifft. endsAt ist optional; lässt du es weg, bleibt das Fenster offen, bis es aufgehoben wird.
• OneTime — benötigt startsAt und ein endsAt, das danach liegt.
• Recurring — benötigt einen cron-Ausdruck und ein durationMinutes zwischen 15 und 1439, beide in der Zeitzone der Instanz ausgewertet.

Ein Fenster, das diese Regeln verletzt, führt zu 400 Bad Request. Der Endpoint für ein einzelnes Gerät antwortet mit dem Geräte-Header, dessen Feld maintenance dann den neuen Zustand widerspiegelt.

Wichtige Gerätefelder

Das vollständige Geräteobjekt ist Feld für Feld in Swagger dokumentiert. Einige Felder haben ein Verhalten, das leicht übersehen wird:

• checkStatus — eine Zusammenfassung der Checks des Geräts ({ total, ok, warning, critical, details }, wobei details ein Array aus { name, status }-Einträgen ist). Wird nur vom Listen-Endpoint befüllt; bei GET /api/assets/{id} immer null.
• tags — ein Array aus { value, source }, wobei source entweder Inventory (automatisch vom Agent aus Hardware und Software zugewiesen, nicht über die API bearbeitbar) oder User (manuell über den Update-Endpoint oder die UI gesetzt) ist.
• lywandScore — der aktuelle Lywand-Sicherheitswert oder null, wenn das Gerät nicht der Lywand-Integration zugeordnet ist.
• allowedActions — ein Array der Geräteaktionen, die dir deine Gruppe für genau dieses Gerät gewährt, als Aktionsnamen (zum Beispiel ["RemoteDesktop", "Terminal", "EditAsset"]). Es ist auf den aufrufenden Benutzer bezogen — zwei Aufrufer können dasselbe Gerät mit unterschiedlichen allowedActions sehen — und wird sowohl in der Listen- als auch in der Abruf-Antwort zurückgegeben. Ein leeres Array bedeutet, dass du das Gerät sehen kannst, aber keine Operationen darauf gewährt bekommst (nur Ansicht). Drei dieser Namen schalten die Endpoints oben frei: EditAsset den Update-Endpoint, DeleteAsset den Lösch-Endpoint und ManageMaintenance den Wartungsmodus. Neue Geräteoperationen bringen mit der Zeit weitere Namen mit — lies die Liste deshalb als offen; die aktuellen Werte stehen in Swagger.
• deviceKind — die klassifizierte Gerätekategorie, einer aus einer festen Menge von Werten (siehe Swagger).
• maintenance — null, solange sich das Gerät nicht im Wartungsmodus befindet. Andernfalls trägt das Objekt die geltenden Schalter (suppressChecks, suppressAutomations, suppressAlerts, suppressDeployments, suppressPatches), enteredAt und effectiveUntil — das Ende des längsten aktiven Fensters oder null, wenn eines davon offen ist. Wird sowohl in der Listen- als auch in der Abruf-Antwort zurückgegeben.

Check-Status geräteübergreifend abfragen

Für eine Statusübersicht des Bestands rufe GET /api/assets?page=1&pageSize=500 ab und lies items[].checkStatus.details. Erhöhe page, bis du die unter total gezählten Geräte verarbeitet hast. Auch erfolgreiche Checks mit Status Success sind enthalten; filtere auf Warning, Critical und Failure, wenn du nur Probleme benötigst. Deaktivierte Checks und Checks ohne Ergebnis fehlen — dies ist daher keine vollständige Liste der konfigurierten Checks.

Für die gespeicherte Ausgabe und den Ergebniszeitpunkt rufe je relevantem Gerät GET /api/assets/{assetId}/checks ab und prüfe latestResult. Einen gleichwertigen Sammelabruf vollständiger Ergebnisse gibt es derzeit nicht. Nutze zuerst die seitenweise Statusübersicht, um unnötige Einzelabfragen zu vermeiden.

Begrenze parallele Anfragen, statt für jedes Gerät gleichzeitig eine Anfrage zu senden. Wiederhole Leseabfragen bei 429 oder vorübergehenden 5xx mit zunehmenden Pausen und beachte einen vorhandenen Retry-After-Header.

Verwandte Artikel

• Schritt 3 – Ersten Agent bereitstellen
• So funktionieren Kunden, Standorte und Geräte
• API-Authentifizierung
• Fehlercodes

FAQ