Devices-API

Geräte auflisten, abrufen, aktualisieren und löschen

Geschrieben von Erdinc Akay

Zuletzt aktualisiert Vor 8 Tagen

Die Devices-API listet Geräte auf, ruft sie ab, aktualisiert und löscht sie. 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

OperationEndpointHinweise
Geräte auflistenGET /api/assetsGibt eine paginierte Hülle { items, total } mit Geräte-Headern zurück. Standardsortierung ist LastSeen absteigend; über sortBy / sortDir überschreibbar. pageSize ist auf 100 begrenzt (Standard 25).
Ein Gerät abrufenGET /api/assets/{id}Gibt { asset, assetData, updatedAt, settings, canBypassRemoteDesktopConsent } zurück — den Geräte-Header plus den vollständigen Inventar-Snapshot (Hardware, installierte Software, laufende Dienste, ausstehende OS-Updates, lokale Benutzer, Netzwerkadapter) und wann er zuletzt vom Agent empfangen wurde. Siehe die Hinweise unter der Tabelle.
Ein Gerät aktualisierenPOST /api/assets/{id}Die Gruppe des Aufrufers muss die gerätebezogene Berechtigung Gerät bearbeiten für das Gerät besitzen. Verwendet die UpdateValue<T>-Hülle — siehe unten.
Ein Gerät löschenDELETE /api/assets/{id}Die Gruppe des Aufrufers muss die gerätebezogene Berechtigung Gerät löschen für das Gerät besitzen. Siehe Löschverhalten unten.

Hinweis zur Abruf-Antwort: settings enthält die 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. 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.

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 und deviceKind (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. 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.
  • 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.

Der Update-Endpoint akzeptiert außerdem fünf 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.
  • 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.

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 und die Realtime-Verbindung des Agents wird sofort getrennt. Die Agenten-Software muss separat auf dem Gerät deinstalliert werden.

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). EditAsset und DeleteAsset in diesem Array schalten den Update- bzw. Lösch-Endpoint für dieses Gerät frei.
  • deviceKind — die klassifizierte Gerätekategorie, einer aus einer festen Menge von Werten (siehe Swagger).

Verwandte Artikel