Поделиться через


Экспорт инвентаризации оценки оборудования и встроенного ПО на устройство

Область применения:

Хотите испытать Управление уязвимостями 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=d7c7c745-195f-4223-9c7a-99fb420fd000/_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=d7c7c745-195f-4223-9c7a-99fb420fd000/_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=d7c7c745-195f-4223-9c7a-99fb420fd000/_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"

   }