Exportar a avaliação do inventário de software por dispositivo
Aplica-se a:
- API do Microsoft Defender para Endpoint 1
- Microsoft Defender para Endpoint Plano 2
- Gestão de Vulnerabilidade do Microsoft Defender
- Microsoft Defender XDR
Quer experimentar o Microsoft Defender para Ponto Final? Inscrever-se para uma avaliação gratuita.
Esta API devolve todos os dados do software instalado que tem uma Enumeração de Plataforma Comum (CPE) numa base por dispositivo.
Diferentes chamadas à API obtêm diferentes tipos de dados. Uma vez que a quantidade de dados pode ser grande, existem duas formas de os obter:
Exportar resposta JSON de avaliação de inventário de software A API extrai todos os dados na sua organização como respostas Json. Este método é melhor para pequenas organizações com menos de 100 K dispositivos. A resposta é paginada, pelo que pode utilizar o campo @odata.nextLink da resposta para obter os resultados seguintes.
Exportar a avaliação do inventário de software através de ficheiros Esta solução de API permite extrair grandes quantidades de dados de forma mais rápida e fiável. Por isso, é recomendado para grandes organizações, com mais de 100 K dispositivos. Esta API extrai todos os dados na sua organização como ficheiros de transferência. A resposta contém URLs para transferir todos os dados do Armazenamento do Azure. Esta API permite-lhe transferir todos os seus dados do Armazenamento do Azure da seguinte forma:
- Chame a API para obter uma lista de URLs de transferência com todos os dados da sua organização.
- Transfira todos os ficheiros com os URLs de transferência e processe os dados conforme quiser.
Os dados recolhidos (utilizando a resposta Json ou através de ficheiros) são o instantâneo atual do estado atual. Não contém dados históricos. Para recolher dados históricos, os clientes têm de guardar os dados nos seus próprios armazenamentos de dados.
Nota
Salvo indicação em contrário, todos os métodos de avaliação de exportação listados são de exportação completa e por dispositivo (também referidos como por dispositivo).
1. Exportar a avaliação do inventário de software (resposta JSON)
1.1 Descrição do método da API
Esta resposta da API contém todos os dados do software instalado que tem uma Enumeração de Plataforma Comum (CPE), por dispositivo. Devolve uma tabela com uma entrada para cada combinação exclusiva de DeviceId, SoftwareVendor, SoftwareName, SoftwareVersion.
1.1.1 Limitações
- O tamanho máximo da página é 200 000.
- As limitações de taxa para esta API são 30 chamadas por minuto e 1000 chamadas por hora.
1.2 Permissões
É necessária uma das seguintes permissões para chamar esta API. Para saber mais, incluindo como escolher permissões, veja Utilizar Microsoft Defender para Endpoint APIs para obter detalhes.
| Tipo de permissão | Permissão | Nome a apresentar da permissão |
|---|---|---|
| Aplicação | Software.Read.All | "Ler informações de software de Gestão de Ameaças e Vulnerabilidades" |
| Delegado (conta escolar ou profissional) | Software.Read | "Ler informações de software de Gestão de Ameaças e Vulnerabilidades" |
1,3 URL
GET /api/machines/SoftwareInventoryByMachine
1.4 Parâmetros
- pageSize (predefinição = 50 000): número de resultados em resposta.
- $top: Número de resultados a devolver (não devolve @odata.nextLink e, por conseguinte, não extrai todos os dados)
1.5 Propriedades
Nota
- Cada registo tem aproximadamente 0,5 KB de dados. Deve ter isto em conta ao escolher o parâmetro pageSize correto para si.
- As propriedades definidas na tabela seguinte são listadas alfabeticamente, por ID de propriedade. Ao executar esta API, o resultado resultante não será necessariamente devolvido pela mesma ordem listada nesta tabela.
- Algumas colunas adicionais podem ser devolvidas na resposta. Estas colunas são temporárias e podem ser removidas. Utilize apenas as colunas documentadas.
| Propriedade (ID) | Tipo de dados | Descrição | Exemplo de um valor devolvido |
|---|---|---|---|
| DeviceId | cadeia | Identificador exclusivo do dispositivo no serviço. | 9eaf3a8b5962e0e6b1af9ec756664a9b823df2d1 |
| DeviceName | cadeia | Nome de domínio completamente qualificado (FQDN) do dispositivo. | johnlaptop.europe.contoso.com |
| DiskPaths | Matriz[cadeia] | Prova de disco de que o produto está instalado no dispositivo. | ["C:\Programas (x86)\Microsoft\Silverlight\Application\silverlight.exe"] |
| EndOfSupportDate | cadeia | A data em que o suporte para este software tem ou terminará. | 2020-12-30 |
| EndOfSupportStatus | cadeia | Fim do estado de suporte. Pode conter estes valores possíveis: None, EOS Version, Upcoming EOS Version, EOS Software, Upcoming EOS Software. | EOS futuro |
| NumberOfWeaknesses | int | Número de pontos fracos neste software neste dispositivo | 3 |
| OSPlatform | cadeia | Plataforma do sistema operativo em execução no dispositivo. Estes são sistemas operativos específicos com variações dentro da mesma família, como Windows 10 e Windows 11. Veja Gestão de vulnerabilidades do Microsoft Defender sistemas operativos e plataformas suportados para obter detalhes. | Windows10 e Windows 11 |
| RbacGroupName | cadeia | O grupo de controlo de acesso baseado em funções (RBAC). Se este dispositivo não estiver atribuído a nenhum grupo RBAC, o valor será "Não atribuído". Se a organização não contiver nenhum grupo RBAC, o valor será "Nenhum". | Servidores |
| RegistryPaths | Matriz[cadeia] | Prova de registo de que o produto está instalado no dispositivo. | ["HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\Microsoft Silverlight"] |
| SoftwareFirstSeenTimestamp | cadeia | A primeira vez que este software foi visto no dispositivo. | 2019-04-07 02:06:47 |
| SoftwareName | cadeia | Nome do produto de software. | Silverlight |
| SoftwareVendor | cadeia | Nome do fornecedor de software. | microsoft |
| SoftwareVersion | cadeia | Número da versão do produto de software. | 81.0.4044.138 |
1.6 Exemplos
1.6.1 Exemplo de pedido
GET https://api.securitycenter.microsoft.com/api/machines/SoftwareInventoryByMachine?pageSize=5 &sinceTime=2021-05-19T18%3A35%3A49.924Z
1.6.2 Exemplo de resposta
{
"@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
As informações devolvidas por esta API, juntamente com as informações devolvidas pela API de avaliação de inventário de software de código de produto exportado, para software que não tem um CPE, dão-lhe visibilidade total sobre o software instalado na sua organização e os dispositivos em que está instalado.
2. Exportar a avaliação do inventário de software (através de ficheiros)
Descrição do método da API 2.1
Esta resposta da API contém todos os dados do software instalado por dispositivo. Devolve uma tabela com uma entrada para cada combinação exclusiva de DeviceId, SoftwareVendor, SoftwareName, SoftwareVersion.
2.1.1 Limitações
As limitações de taxa para esta API são 5 chamadas por minuto e 20 chamadas por hora.
2.2 Permissões
É necessária uma das seguintes permissões para chamar esta API. Para saber mais, incluindo como escolher permissões, veja Utilizar Microsoft Defender para Endpoint APIs para obter detalhes.
| Tipo de permissão | Permissão | Nome a apresentar da permissão |
|---|---|---|
| Aplicação | Software.Read.All | "Ler informações de software de Gestão de Ameaças e Vulnerabilidades" |
| Delegado (conta escolar ou profissional) | Software.Read | "Ler informações de software de Gestão de Ameaças e Vulnerabilidades" |
2.3 URL
GET /api/machines/SoftwareInventoryExport
Parâmetros
- sasValidHours: o número de horas durante as quais os URLs de transferência serão válidos (Máximo de 24 horas)
2.5 Propriedades
Nota
- Os ficheiros são comprimidos gzip & no formato JSON multiline.
- Os URLs de transferência só são válidos durante 3 horas. Caso contrário, pode utilizar o parâmetro .
- Para obter a velocidade máxima de transferência dos seus dados, pode certificar-se de que está a transferir a partir da mesma região do Azure em que os seus dados residem.
| Propriedade (ID) | Tipo de dados | Descrição | Exemplo de um valor devolvido |
|---|---|---|---|
| Exportar ficheiros | matriz[cadeia] | Uma lista de URLs de transferência para ficheiros que contêm o instantâneo atual da organização | "[Https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...1", "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...2"] |
| GeneratedTime | cadeia | A hora em que a exportação foi gerada. | 2021-05-20T08:00:00Z |
2.6 Exemplos
2.6.1 Exemplo de pedido
GET https://api.securitycenter.microsoft.com/api/machines/SoftwareInventoryExport
2.6.2 Exemplo de resposta
{
"@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 também
- Exportar métodos e propriedades de avaliação por dispositivo
- Exportar avaliação de configuração segura por dispositivo
- Exportar avaliação de vulnerabilidades de software por dispositivo
- Exportar a avaliação do inventário de software de código não produto
Outros relacionados
Sugestão
Quer saber mais? Engage com a comunidade de Segurança da Microsoft na nossa Comunidade Tecnológica: Microsoft Defender para Endpoint Tech Community.
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários