Exportación del inventario de evaluación de hardware y firmware por dispositivo
Se aplica a:
- Microsoft Defender para punto de conexión Plan 1
- Microsoft Defender para punto de conexión Plan 2
- Administración de vulnerabilidades de Microsoft Defender
- Microsoft Defender XDR
¿Quieres experimentar Administración de vulnerabilidades de Microsoft Defender? Obtenga más información sobre cómo puede registrarse en la versión de prueba de Administración de vulnerabilidades de Microsoft Defender versión preliminar pública.
Hay diferentes llamadas API para obtener diferentes tipos de datos. En general, cada llamada API contiene los datos necesarios para los dispositivos de la organización.
Respuesta JSON La API extrae todos los datos de la organización como respuestas JSON. Este método es mejor para organizaciones pequeñas con menos de 100 K dispositivos. La respuesta está paginada, por lo que puede usar el campo @odata.nextLink de la respuesta para capturar los resultados siguientes.
a través de archivos Esta solución de API permite extraer grandes cantidades de datos de forma más rápida y confiable. Por lo tanto, se recomienda para organizaciones grandes, con más de 100 K dispositivos. Esta API extrae todos los datos de la organización como archivos de descarga. La respuesta contiene direcciones URL para descargar todos los datos de Azure Storage. Puede descargar datos de Azure Storage de la siguiente manera:
- Llame a la API para obtener una lista de direcciones URL de descarga con todos los datos de la organización.
- Descargue todos los archivos mediante las direcciones URL de descarga y procese los datos como desee.
Los datos recopilados mediante "respuesta JSON o a través de archivos" son la instantánea actual del estado actual. No contiene datos históricos. Para recopilar datos históricos, los clientes deben guardar los datos en sus propios almacenamientos de datos.
Nota:
A menos que se indique lo contrario, todos los métodos de evaluación de firmware y hardware de exportación enumerados son de exportación completa y por dispositivo (también denominados por dispositivo)
1. Exportación de la evaluación de hardware y firmware (respuesta JSON)
Descripción del método de API 1.1
Devuelve todas las evaluaciones de hardware y firmware para todos los dispositivos, por dispositivo. Devuelve una tabla con una entrada independiente para cada combinación única de deviceId y componentType.
1.1.1 Limitaciones
- El tamaño máximo de página es de 200 000.
- Las limitaciones de velocidad de esta API son 30 llamadas por minuto y 1000 llamadas por hora.
1.2 Permisos
Se requiere uno de los siguientes permisos para llamar a esta API. Para obtener más información, incluido cómo elegir permisos, consulte Uso de Microsoft Defender para punto de conexión API para obtener más información.
| Tipo de permiso | Permiso | Nombre para mostrar del permiso |
|---|---|---|
| Aplicación | Software.Read.All | "Leer la información del software de administración de amenazas y vulnerabilidades" |
| Delegado (cuenta profesional o educativa) | Software.Read | "Leer la información del software de administración de amenazas y vulnerabilidades" |
Dirección URL 1.3
GET api/machines/HardwareFirmwareInventoryByMachine
1.4 Parámetros
- pageSize (valor predeterminado = 50 000): número de resultados en respuesta.
- $top: número de resultados que se van a devolver (no devuelve @odata.nextLink y, por lo tanto, no extrae todos los datos).
Propiedades 1.5 (respuesta JSON)
Nota:
Cada registro tiene aproximadamente 1 KB de datos. Debe tener esto en cuenta al elegir el parámetro pageSize correcto.
Es posible que se devuelvan algunas columnas adicionales en la respuesta. Estas columnas son temporales y pueden quitarse. Use solo las columnas documentadas.
Las propiedades definidas en la tabla siguiente se enumeran alfabéticamente por identificador de propiedad. Al ejecutar esta API, la salida resultante no se devolverá necesariamente en el mismo orden que se muestra en esta tabla.
| Propiedad (ID) | Tipo de datos | Descripción |
|---|---|---|
| deviceId | Cadena | Identificador único del dispositivo en el servicio. |
| rbacGroupId | Int | Identificador del grupo de control de acceso basado en rol (RBAC). Si el dispositivo no está asignado a ningún grupo de RBAC, el valor será "Sin asignar". Si la organización no contiene ningún grupo de RBAC, el valor será "Ninguno". |
| rbacGroupName | Cadena | El grupo de control de acceso basado en rol (RBAC). Si el dispositivo no está asignado a ningún grupo de RBAC, el valor será "Sin asignar". Si la organización no contiene ningún grupo de RBAC, el valor será "Ninguno". |
| deviceName | Cadena | Nombre de dominio completo (FQDN) del dispositivo. |
| componentType | Cadena | Tipo de componente de hardware o firmware. |
| manufacturer | Cadena | Fabricante de un componente de hardware o firmware específico. |
| componentName | Cadena | Nombre de un componente de hardware o firmware específico. |
| componentVersion | Cadena | Versión de un componente de hardware o firmware específico. |
| additionalFields | Cadena | Información adicional sobre los componentes en formato de matriz JSON. |
Ejemplo 1.6
1.6.1 Ejemplo de solicitud
GET https://api.security.microsoft.com/api/machines/HardwareFirmwareInventoryByMachine
Ejemplo de respuesta 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. Exportación de la evaluación de hardware y firmware (a través de archivos)
2.1 Descripción del método de API
Devuelve todas las evaluaciones de hardware y firmware para todos los dispositivos, por dispositivo. Devuelve una tabla con una entrada independiente para cada combinación única de DeviceId, ComponentType y ComponentName.
2.1.1 Limitaciones
- Las limitaciones de frecuencia de esta API son 5 llamadas por minuto y 20 llamadas por hora.
2.2 Permisos
Se requiere uno de los siguientes permisos para llamar a esta API. Para obtener más información, incluido cómo elegir permisos, consulte Uso de Microsoft Defender para punto de conexión API para obtener más información.
| Tipo de permiso | Permiso | Nombre para mostrar del permiso |
|---|---|---|
| Aplicación | Software.Read.All | "Leer la información del software de administración de amenazas y vulnerabilidades" |
| Delegado (cuenta profesional o educativa) | Software.Read | "Leer la información del software de administración de amenazas y vulnerabilidades" |
Dirección URL 2.3
GET /api/machines/HardwareFirmwareInventoryExport
2.4 Parámetros
- sasValidHours: el número de horas durante las que serán válidas las direcciones URL de descarga (máximo 24 horas).
Propiedades 2.5 (respuesta JSON)
Nota:
Los archivos se comprimen gzip & en formato Json multilínea.
Las direcciones URL de descarga solo son válidas durante 3 horas; De lo contrario, puede usar el parámetro .
Para maximizar las velocidades de descarga, asegúrese de que está descargando los datos de la misma región de Azure donde residen los datos.
Cada registro tiene aproximadamente 1 KB de datos. Debe tener esto en cuenta al elegir el parámetro pageSize que funciona automáticamente.
Es posible que se devuelvan algunas columnas adicionales en la respuesta. Estas columnas son temporales y pueden quitarse. Use solo las columnas documentadas.
| Propiedad (ID) | Tipo de datos | Descripción |
|---|---|---|
| Exportación de archivos | String[array] | Una lista de direcciones URL de descarga para los archivos que contienen la instantánea actual de la organización. |
| GeneratedTime | DateTime | El momento en que se generó la exportación. |
Ejemplo 2.6
2.6.1 Ejemplo de solicitud
GET https://api.security.microsoft.com/api/machines/HardwareFirmwareInventoryExport
Ejemplo de respuesta 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"
}
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de