Exportación de la evaluación del inventario de software por dispositivo

  • Artículo

Se aplica a:

¿Quiere experimentar Microsoft Defender para punto de conexión? Regístrese para obtener una prueba gratuita.

Esta API devuelve todos los datos del software instalado que tiene una enumeración de plataforma común (CPE) por dispositivo.

Las distintas llamadas API obtienen diferentes tipos de datos. Dado que la cantidad de datos puede ser grande, hay dos maneras de recuperarlos:

  • Exportación de la respuesta JSON de evaluación del inventario de software 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.

  • Exportación de la evaluación del inventario de software 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. Esta API le permite descargar todos los 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 la 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 exportación enumerados son de exportación completa y por dispositivo (también denominados por dispositivo).

1. Exportación de la evaluación del inventario de software (respuesta JSON)

Descripción del método de API 1.1

Esta respuesta de API contiene todos los datos del software instalado que tiene una enumeración de plataforma común (CPE) por dispositivo. Devuelve una tabla con una entrada para cada combinación única de DeviceId, SoftwareVendor, SoftwareName, SoftwareVersion.

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/SoftwareInventoryByMachine

1.4 Parámetros

  • pageSize (valor predeterminado = 50 000): número de resultados en respuesta.
  • $top: número de resultados que se devolverán (no devuelve @odata.nextLink y, por tanto, no extrae todos los datos)

1.5 Propiedades

Nota:

  • Cada registro tiene aproximadamente 0,5 KB de datos. Debe tener esto en cuenta al elegir el parámetro pageSize correcto.
  • 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.
  • 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 Ejemplo de un valor devuelto
DeviceId string Identificador único del dispositivo en el servicio. 9eaf3a8b5962e0e6b1af9ec756664a9b823df2d1
DeviceName string Nombre de dominio completo (FQDN) del dispositivo. johnlaptop.europe.contoso.com
DiskPaths Matriz[cadena] Prueba de disco de que el producto está instalado en el dispositivo. ["C:\Archivos de programa (x86)\Microsoft\Silverlight\Application\silverlight.exe"]
EndOfSupportDate string La fecha en la que la compatibilidad con este software tiene o finalizará. 2020-12-30
EndOfSupportStatus string Fin del estado de soporte técnico. Puede contener estos valores posibles: None, EOS Version, Upcoming EOS Version, EOS Software, Upcoming EOS Software. Próximo EOS
NumberOfWeaknesses Entero Número de puntos débiles en este software en este dispositivo 3
OSPlatform string Plataforma del sistema operativo que se ejecuta en el dispositivo. Se trata de sistemas operativos específicos con variaciones dentro de la misma familia, como Windows 10 y Windows 11. Consulte Administración de vulnerabilidades de Microsoft Defender sistemas operativos y plataformas compatibles para obtener más información. Windows10 y Windows 11
RbacGroupName string El grupo de control de acceso basado en rol (RBAC). Si este 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". Servidores
RegistryPaths Matriz[cadena] Evidencia del Registro de que el producto está instalado en el dispositivo. ["HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\Microsoft Silverlight"]
SoftwareFirstSeenTimestamp string La primera vez que se vio este software en el dispositivo. 2019-04-07 02:06:47
SoftwareName string Nombre del producto de software. Silverlight
SoftwareVendor string Nombre del proveedor de software. microsoft
SoftwareVersion string Número de versión del producto de software. 81.0.4044.138

1.6 Ejemplos

1.6.1 Ejemplo de solicitud

GET https://api.securitycenter.microsoft.com/api/machines/SoftwareInventoryByMachine?pageSize=5  &sinceTime=2021-05-19T18%3A35%3A49.924Z

Ejemplo de respuesta 1.6.2

{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Collection(contoso.windowsDefenderATP.api.AssetSoftware)",
    "value": [
        {
            "deviceId": "00044f68765bbaf712342dbe6db733b6a9c59ab4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18993b45912eeb224b2be2f5ea3142726e63f16a.DomainPII_21eeb80d086e79dbfa178eadfa25e8de9acfa346.corp.contoso.com",
            "osPlatform": "Windows10" "Windows11",
            "softwareVendor": "microsoft",
            "softwareName": "windows_10" "Windows_11",
            "softwareVersion": "10.0.17763.1637",
            "numberOfWeaknesses": 58,
            "diskPaths": [],
            "registryPaths": [],
            "softwareFirstSeenTimestamp": "2020-12-30 11:07:15",
            "endOfSupportStatus": "Upcoming EOS Version",
            "endOfSupportDate": "2021-05-11T00:00:00+00:00"
        },
        {
            "deviceId": "00044f68765bbaf712342dbe6db733b6a9c59ab4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18993b45912eeb224b2be2f5ea3142726e63f16a.DomainPII_21eeb80d086e79dbfa178eadfa25e8de9acfa346.corp.contoso.com",
            "osPlatform": "Windows10" "Windows11",
            "softwareVendor": "microsoft",
            "softwareName": ".net_framework",
            "softwareVersion": "4.0.0.0",
            "numberOfWeaknesses": 0,
            "diskPaths": [],
            "registryPaths": [
                "SOFTWARE\\Microsoft\\NET Framework Setup\\NDP\\v4.0\\Client\\Install"
            ],
            "softwareFirstSeenTimestamp": "2020-12-30 11:07:15",
            "endOfSupportStatus": "None",
            "endOfSupportDate": null
        },
        {
            "deviceId": "00044f68765bbaf712342dbe6db733b6a9c59ab4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18993b45912eeb224b2be2f5ea3142726e63f16a.DomainPII_21eed80d086e79bdfa178eadfa25e8de9acfa346.corp.contoso.com",
            "osPlatform": "Windows10" "Windows11",
            "softwareVendor": "microsoft",
            "softwareName": "system_center_2012_endpoint_protection",
            "softwareVersion": "4.7.214.0",
            "numberOfWeaknesses": 0,
            "diskPaths": [],
            "registryPaths": [
                "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\Microsoft Security Client"
            ],
            "softwareFirstSeenTimestamp": "2020-12-30 11:07:15",
            "endOfSupportStatus": "None",
            "endOfSupportDate": null
        },
        {
            "deviceId": "00044f68765ddaf71234bde6bd733d6a9c59ad4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18993b45912eeb224b2be2f5ea3142726e63f16a.DomainPII_21eeb80d086e79dbfa178aedfa25e8be9acfa346.corp.contoso.com",
            "osPlatform": "Windows10" "Windows11",
            "softwareVendor": "microsoft",
            "softwareName": "configuration_manager",
            "softwareVersion": "5.0.8634.1000",
            "numberOfWeaknesses": 0,
            "diskPaths": [],
            "registryPaths": [
                "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\{B7D3A842-E826-4542-B39B-1D883264B279}"
            ],
            "softwareFirstSeenTimestamp": "2020-12-30 11:07:15",
            "endOfSupportStatus": "None",
            "endOfSupportDate": null
        },
        {
            "deviceId": "00044f38765bbaf712342dbe6db733b6a9c59ab4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18993b45912eeb224b2de2f5ea3142726e63f16a.DomainPII_21eeb80d086e79bdfa178eadfa25e8be9acfa346.corp.contoso.com",
            "osPlatform": "Windows10" "Windows11",
            "softwareVendor": "microsoft",
            "softwareName": "system_center_2012_endpoint_protection",
            "softwareVersion": "4.10.209.0",
            "numberOfWeaknesses": 0,
            "diskPaths": [],
            "registryPaths": [
                "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\Microsoft Security Client"
            ],
            "softwareFirstSeenTimestamp": "2020-12-30 11:07:15",
            "endOfSupportStatus": "None",
            "endOfSupportDate": null
        }
    ],
    "@odata.nextLink": "https://api.securitycenter.microsoft.com/api/machines/SoftwareInventoryByMachine?pagesize=5&$skiptoken=eyJFeHBvcnREZWZpbml0aW9uIjp7IlRpbWVQYXRoIjoiMjAyMS0wMS0yNS8wMjAwLyJ9LCJFeHBvcnRGaWxlSW5kZXgiOjAsIkxpbmVTdG9wcGVkQXQiOjV9"
}

Nota:

La información devuelta por esta API, junto con la información devuelta por la API export non product code software inventory assessment para software que no tiene un CPE, proporciona visibilidad completa sobre el software instalado en toda la organización y los dispositivos en los que está instalado.

2. Exportación de la evaluación del inventario de software (a través de archivos)

2.1 Descripción del método de API

Esta respuesta de API contiene todos los datos de software instalado por dispositivo. Devuelve una tabla con una entrada para cada combinación única de DeviceId, SoftwareVendor, SoftwareName, SoftwareVersion.

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/SoftwareInventoryExport

Parameters

  • sasValidHours: el número de horas durante las que serán válidas las direcciones URL de descarga (máximo 24 horas)

2.5 Propiedades

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 obtener la máxima velocidad de descarga de los datos, puede asegurarse de que está descargando desde la misma región de Azure en la que residen los datos.

Propiedad (ID) Tipo de datos Descripción Ejemplo de un valor devuelto
Exportación de archivos array[string] Lista de direcciones URL de descarga para los archivos que contienen la instantánea actual de la organización "[Https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...1", "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...2"]
GeneratedTime string Hora en que se generó la exportación. 2021-05-20T08:00:00Z

2.6 Ejemplos

2.6.1 Ejemplo de solicitud

GET https://api.securitycenter.microsoft.com/api/machines/SoftwareInventoryExport

Ejemplo de respuesta 2.6.2

{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#microsoft.windowsDefenderATP.api.ExportFilesResponse",
    "exportFiles": [
        "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export/2021-01-11/1101/SoftwareInventory/json/OrgId=12345678-195f-4223-9c7a-99fb420fd000/part-00393-e423630d-4c69-4490-8769-a4f5468c4f25.c000.json.gz?sv=2019-12-12&st=2021-01-11T11%3A55%3A51Z&se=2021-01-11T14%3A55%3A51Z&sr=b&sp=r&sig=...",
        "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export/2021-01-11/1101/SoftwareInventory/json/OrgId=12345678-195f-4223-9c7a-99fb420fd000/part-00394-e423630d-4c69-4490-8769-a4f5468c4f25.c000.json.gz?sv=2019-12-12&st=2021-01-11T11%3A55%3A51Z&se=2021-01-11T14%3A55%3A51Z&sr=b&sp=r&sig=...",
        "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export/2021-01-11/1101/SoftwareInventory/json/OrgId=12345678-195f-4223-9c7a-99fb420fd000/part-00394-e423630d-4c69-4490-8769-a4f5468c4f25.c001.json.gz?sv=2019-12-12&st=2021-01-11T11%3A55%3A51Z&se=2021-01-11T14%3A55%3A51Z&sr=b&sp=r&sig=..."
    ],
    "generatedTime": "2021-01-11T11:01:00Z"
}

Consulte también

Otros relacionados

Sugerencia

¿Desea obtener más información? Engage con la comunidad de seguridad de Microsoft en nuestra comunidad tecnológica: Microsoft Defender para punto de conexión Tech Community.