Appliance management API reference for on-premises management consoles
Стаття 10/18/2022
Співавторів: 2
Зворотний зв’язок
Зміст статті
This article lists the appliance management REST APIs supported for Microsoft Defender for IoT on-premises management consoles.
appliances (Manage OT sensor appliances)
Use this API to manage your OT sensor appliances from an on-premises management console.
URI : /external/v1/appliances
or /external/v2/appliances
GET
Type : JSON
A JSON array of appliance objects that represent sensor appliances.
Name
Type
Nullable / Not nullable
List of values
id
Long integer
Not nullable
The sensor ID
name
String
Not nullable
The sensor's name
interfaceAddress
String
Not nullable
The sensor's console URL
state
JSON array
Not nullable
A JSON array that describes the sensor's connection status. For more information, see XsenseState fields .
version
String
Not nullable
The software version currently installed on the sensor.
alertCount
Long integer
Not nullable
The total number of alerts currently active on the sensor.
deviceCount
Long integer
Not nullable
The number of devices currently detected by the sensor.
unhandledAlertsCount
long
Not nullable
The current number of unhandled alerts on the sensor.
isActivated
Boolean
Not nullable
One of the following: Activated
or Unactivated
dataIntelligenceVersion
String
Not nullable
The version of threat intelligence data currently installed on the sensor
upgradeStatus
JSON array
Not nullable
A JSON array that describes the sensor's update status. For more information, see UpgradeStatusBean fields .
upgradeFinishTime
Long
Nullable
The time the last software update completed, in the following format: YYYY-MM-DD
hasLog
Boolean
Not nullable
Defines whether an upgrade log exists for the sensor.
zoneId
Long integer
Nullable
The ID of sensor's zone.
isInLearningMode
Boolean
Not nullable
Defines whether the sensor is currently in learning mode.
XsenseState fields
Name
Type
Nullable / Not nullable
List of values
id
Long integer
Not nullable
An internal, auto-incremented ID on the on-premises management console database.
xsenseId
Long integer
Not nullable
The sensor ID.
connectionState
A JSON array of datetime values
Not nullable
One of the following: SYNCED
, OUT_OF_SYNC
, TIME_DIFF_OFFSET
, DISCONNECTED
cmSyncedUntil
DateTime
Not nullable
The timestamp for the most recent data sent from the sensor.
sensorSyncedUntil
DateTime
Not nullable
The timestamp for the last update from the on-premises management console to the sensor.
sensorLastMessage
DateTime
Not nullable
The timestamp for the last update from the sensor.
UpgradeStatusBean fields
Name
Type
Nullable / Not nullable
List of values
startTime
DateTime
Not nullable
The time the last update process was started.
percentage
Integer between 0-100
Not nullable
The completion percentage of the last update process.
stage
String
Not nullable
One of the following statues: - UPLOADING
: Uploading Package - PREPARE_TO_INSTALL
: Preparing To Install - STOPPING_PROCESSES
Stopping Processes - BACKING_UP_DATA
: Backing Up Data - TAKING_SNAPSHOT
: Taking Snapshot - UPDATING_CONFIGURATION
: Updating Configuration - UPDATING_DEPENDENCIES
: Updating Dependencies - UPDATING_LIBRARIES
: Updating Libraries - PATCHING_DATABASES
: Patching Databases - STARTING_PROCESSES
: Starting Processes - VALIDATING_SYSTEM_SANITY
: Validating System Sanity - VALIDATION_SUCCEEDED_REBOOTING
: Validation Succeeded - SUCCESS
: Success - FAILURE
: Failure - UPGRADE_STARTED
: Upgrade Started - STARTING_INSTALLATION
: Starting Installation - INSTALLING_OPERATING_SYSTEM
: Installing OS
Response example
[
{
"dataIntelligenceVersion":"Dec 22, 2021",
"name":"Microsoft Defender for IoT",
"isActivated":true,
"hasLog":false,
"zoneId":null,
"upgradeStatus":null,
"deviceCount":22,
"state":{
"sensorLastMessage":1660217831000,
"xsenseId":1,
"sensorSyncedUntil":1660217741000,
"connectionState":{
"isConsideredConnected":true,
"id":1,
"description":"Connection is successful"
},
"cmSyncedUntil":1660217825000,
"id":1
},
"version":"22.1.4.8-r-6372aad",
"alertCount":9,
"upgradeFinishTime":null,
"uid":"a6218f1a-8ebf-4bb3-8613-c859b17eef01",
"interfaceAddress":"https://173.70.549.76",
"id":1,
"unhandledAlertsCount":9
}
]
Type : GET
API :
curl -k -H "Authorization: <AUTH_TOKEN>" 'https://<>IP_ADDRESS>/external/v1/appliances'
Example :
curl -k -H "Authorization: 1234b734a9244d54ab8d40aedddcabcd" 'https://127.0.0.1/external/v1/appliances'
Next steps
For more information, see the Defender for IoT API reference overview .