Экспорт инвентаризации оценки оборудования и встроенного ПО на устройство
Область применения:
- Microsoft Defender для конечной точки (план 1)
- Microsoft Defender для конечной точки (план 2)
- Управление уязвимостями в Microsoft Defender
- Microsoft Defender XDR
Хотите испытать Управление уязвимостями Microsoft Defender? Узнайте больше о том, как зарегистрироваться в общедоступной пробной версии Управление уязвимостями Microsoft Defender.
Существуют различные вызовы API для получения разных типов данных. Как правило, каждый вызов API содержит необходимые данные для устройств в вашей организации.
Ответ JSON API извлекает все данные в организации в виде ответов JSON. Этот метод лучше всего подходит для небольших организаций с менее чем 100 тыс. устройств. Ответ разбиется на страницы, поэтому для получения следующих результатов можно использовать поле @odata.nextLink из ответа.
через файлы Это решение API позволяет быстрее и надежнее извлекать большие объемы данных. Поэтому рекомендуется использовать его для крупных организаций с более чем 100 тыс. устройств. Этот API извлекает все данные в вашей организации в виде файлов скачивания. Ответ содержит URL-адреса для скачивания всех данных из службы хранилища Azure. Данные из службы хранилища Azure можно скачать следующим образом:
- Вызовите API, чтобы получить список URL-адресов для скачивания со всеми данными организации.
- Скачайте все файлы с помощью URL-адресов для скачивания и обработайте данные по мере того, как вам нравится.
Данные, собираемые с помощью ответа JSON или с помощью файлов, являются текущим snapshot текущего состояния. Он не содержит исторических данных. Для сбора исторических данных клиенты должны сохранять данные в собственных хранилищах данных.
Примечание.
Если не указано иное, все перечисленные методы оценки оборудования и встроенного ПО экспорта полностью экспортируются и по устройству (также называются по устройству).
1. Экспорт оценки оборудования и встроенного ПО (ответ JSON)
1.1 Описание метода API
Возвращает все оценки оборудования и встроенного ПО для всех устройств на основе каждого устройства. Он возвращает таблицу с отдельной записью для каждого уникального сочетания deviceId и componentType.
1.1.1. Ограничения
- Максимальный размер страницы — 200 000.
- Ограничения скорости для этого API: 30 вызовов в минуту и 1000 вызовов в час.
1.2 Разрешения
Для вызова этого API требуется одно из следующих разрешений. Дополнительные сведения, включая выбор разрешений, см. в статье Использование API Microsoft Defender для конечной точки.
| Тип разрешения | Разрешение | Отображаемое имя разрешения |
|---|---|---|
| Приложение | Software.Read.All | "Чтение сведений о программном обеспечении для управления угрозами и уязвимостями" |
| Делегированные (рабочая или учебная учетная запись) | Software.Read | "Чтение сведений о программном обеспечении для управления угрозами и уязвимостями" |
URL-адрес 1.3
GET api/machines/HardwareFirmwareInventoryByMachine
1.4 Параметры
- pageSize (по умолчанию = 50 000): количество результатов в ответе.
- $top: число возвращаемых результатов (не возвращает @odata.nextLink и поэтому не извлекет все данные).
1.5. Свойства (ответ JSON)
Примечание.
Каждая запись составляет примерно 1 КБ данных. Это следует учитывать при выборе правильного параметра pageSize.
В ответе могут быть возвращены некоторые дополнительные столбцы. Эти столбцы являются временными и могут быть удалены. Используйте только задокументированные столбцы.
Свойства, определенные в следующей таблице, перечислены в алфавитном порядке по идентификатору свойства. При запуске этого API результирующие выходные данные не обязательно будут возвращаться в том же порядке, что и в этой таблице.
| Свойство (идентификатор) | Тип данных | Описание |
|---|---|---|
| deviceId | String | Уникальный идентификатор устройства в службе. |
| rbacGroupId | Целое | Идентификатор группы управления доступом на основе ролей (RBAC). Если устройство не назначено ни одной группе RBAC, значение будет "Не назначено". Если в организации нет групп RBAC, значение будет "Нет". |
| rbacGroupName | String | Группа управления доступом на основе ролей (RBAC). Если устройство не назначено ни одной группе RBAC, значение будет "Не назначено". Если в организации нет групп RBAC, значение будет "Нет". |
| deviceName | String | Полное доменное имя (FQDN) устройства. |
| componentType | String | Тип оборудования или компонента встроенного ПО. |
| manufacturer | String | Производитель определенного оборудования или компонента встроенного ПО. |
| componentName | String | Имя определенного оборудования или компонента встроенного ПО. |
| componentVersion | String | Версия определенного оборудования или компонента встроенного ПО. |
| additionalFields | String | Дополнительные сведения о компонентах в формате массива JSON. |
1.6. Пример
1.6.1. Пример запроса
GET https://api.security.microsoft.com/api/machines/HardwareFirmwareInventoryByMachine
1.6.2. Пример ответа
{
"@odata.context": "https://api-df.securitycenter.microsoft.com/api/$metadata#Collection(microsoft.windowsDefenderATP.api.AssetHardwareFirmware)",
"value":[
{
"deviceId": "49126b9e4a5473b5229c73799e9e55c48668101b",
"rbacGroupId": 39,
"rbacGroupName": "testO6343398Gq31",
"deviceName": "testmachine5",
"componentType": "Hardware",
"manufacturer": "razer",
"componentName": "blade_15_advanced_model_(mid_2021)_-_rz09-0409",
"componentVersion": "7.04",
"additionalFields": "{\"SystemSKU\":\"RZ09-0409CE53\",\"BaseBoardManufacturer\":\"Razer\",\"BaseBoardProduct\":\"CH570\",\"BaseBoardVersion\":\"4\",\"DeviceFamily\":\"Workstation\"}"
}
]
},
2. Экспорт оценки оборудования и встроенного ПО (с помощью файлов)
2.1. Описание метода API
Возвращает все оценки оборудования и встроенного ПО для всех устройств на основе каждого устройства. Он возвращает таблицу с отдельной записью для каждого уникального сочетания DeviceId, ComponentType и ComponentName.
2.1.1. Ограничения
- Ограничения скорости для этого API : 5 вызовов в минуту и 20 вызовов в час.
2.2 Разрешения
Для вызова этого API требуется одно из следующих разрешений. Дополнительные сведения, включая выбор разрешений, см. в статье Использование API Microsoft Defender для конечной точки.
| Тип разрешения | Разрешение | Отображаемое имя разрешения |
|---|---|---|
| Приложение | Software.Read.All | "Чтение сведений о программном обеспечении для управления угрозами и уязвимостями" |
| Делегированные (рабочая или учебная учетная запись) | Software.Read | "Чтение сведений о программном обеспечении для управления угрозами и уязвимостями" |
URL-адрес 2.3
GET /api/machines/HardwareFirmwareInventoryExport
2.4. Параметры
- sasValidHours: количество часов, в течение которых будут действовать URL-адреса скачивания (максимум 24 часа).
2.5. Свойства (ответ JSON)
Примечание.
Файлы сжаты gzip & в многострочных форматах JSON.
URL-адреса для скачивания действительны только в течение 3 часов; В противном случае можно использовать параметр .
Чтобы увеличить скорость загрузки, убедитесь, что данные загружаются из того же региона Azure, где находятся данные.
Каждая запись составляет примерно 1 КБ данных. Это следует учитывать при выборе подходящего параметра pageSize.
В ответе могут быть возвращены некоторые дополнительные столбцы. Эти столбцы являются временными и могут быть удалены. Используйте только задокументированные столбцы.
| Свойство (идентификатор) | Тип данных | Описание |
|---|---|---|
| Экспорт файлов | String[array] | Список URL-адресов для скачивания файлов, содержащих текущие snapshot организации. |
| GeneratedTime | DateTime | Время создания экспорта. |
2.6. Пример
2.6.1. Пример запроса
GET https://api.security.microsoft.com/api/machines/HardwareFirmwareInventoryExport
2.6.2. Пример ответа
{
"@odata.context":"https://api-df.securitycenter.microsoft.com/api/$metadata#microsoft.windowsDefenderATP.api.ExportFilesResponse",
"exportFiles": [
"https://tvmexportstrprdcane.blob.core.windows.net/tvm-firmware-export/2022-07-11/1101/FirmwareHardwareExport/json/OrgId=3837d1f5-0d51-40cb-a99d-69ebedc9dcc8/_RbacGroupId=39/part-00999-71eea973-1bb1-4d0a-829d-80cb07aff5d8.c000.json.gz?sv=2020-08-04&st=2022-07-11T13%3A10%3A06Z&se=2022-07-11T16%3A10%3A06Z&sr=b&sp=r&sig=muN8Sq6rVN6bFMtR0u3S5Wzh3D9qNPgN5vpU7lWvULg%3D",
"https://tvmexportstrprdcane.blob.core.windows.net/tvm-firmware-export/2022-07-11/1101/FirmwareHardwareExport/json/OrgId=3837d1f5-0d51-40cb-a99d-69ebedc9dcc8/_RbacGroupId=9/part-00968-71eea973-1bb1-4d0a-829d-80cb07aff5d8.c000.json.gz?sv=2020-08-04&st=2022-07-11T13%3A10%3A06Z&se=2022-07-11T16%3A10%3A06Z&sr=b&sp=r&sig=%2BA0%2B4qOOBCS5E4UenJPbMdLM%2FkbXHnz%2F1pvfSOCq%2F2s%3D",
"https://tvmexportstrprdcane.blob.core.windows.net/tvm-firmware-export/2022-07-11/1101/FirmwareHardwareExport/json/OrgId=3837d1f5-0d51-40cb-a99d-69ebedc9dcc8/_RbacGroupId=9/part-00969-71eea973-1bb1-4d0a-829d-80cb07aff5d8.c000.json.gz?sv=2020-08-04&st=2022-07-11T13%3A10%3A06Z&se=2022-07-11T16%3A10%3A06Z&sr=b&sp=r&sig=sZUgYMwSr5zk6BZvS%2BoYIWlHJWk2oJ7YjiC8R26S1X4%3D"
],
"generatedTime": "2022-07-11T11:01:00Z"
}