Adicionar, atualizar ou excluir uma definição de verificação
Aplica-se a:
- Microsoft Defender para Ponto de Extremidade
- Gerenciamento de Vulnerabilidades do Microsoft Defender
- Microsoft Defender XDR
Deseja experimentar o Microsoft Defender para Ponto de Extremidade? Inscreva-se para uma avaliação gratuita.
Quer experimentar Gerenciamento de Vulnerabilidades do Microsoft Defender? Saiba mais sobre como você pode se inscrever no Gerenciamento de Vulnerabilidades do Microsoft Defender avaliação de visualização pública.
Importante
Algumas informações neste artigo estão relacionadas ao produto pré-lançado que pode ser modificado substancialmente antes de ser lançado comercialmente. A Microsoft não oferece garantias, expressas ou implícitas, com relação às informações aqui fornecidas.
Observação
Se você for um cliente do governo dos EUA, use as URIs listadas em Microsoft Defender para Ponto de Extremidade para clientes do governo dos EUA.
Dica
Para obter um melhor desempenho, você pode usar o servidor mais próximo da localização geográfica:
- us.api.security.microsoft.com
- eu.api.security.microsoft.com
- uk.api.security.microsoft.com
- au.api.security.microsoft.com
- swa.api.security.microsoft.com
Descrição da API
API para adicionar, atualizar ou excluir uma verificação autenticada.
Limitações
As limitações de taxa para essa API são 100 chamadas por minuto e 1.500 chamadas por hora.
Você pode postar em computadores vistos pela última vez de acordo com o período de retenção configurado.
Permissões
Uma das seguintes permissões é necessária para chamar esta API. Para saber mais, incluindo como escolher permissões, consulte Usar APIs do Defender para Ponto de Extremidade.
Tipo de permissão | Permissão | Nome da exibição de permissão |
---|---|---|
Application | Machine.ReadWrite.All | Ler e gravar todas as informações de verificação. |
Delegado (conta corporativa ou de estudante) | Machine.Read.Write | Ler e gravar todas as informações de verificação. |
Observação
Ao obter um token usando credenciais de usuário:
- Para exibir dados, o usuário precisa ter pelo menos a seguinte permissão de função:
ViewData
ouTvmViewData
(Consulte Create e gerencie funções para obter mais informações) - Para editar dados, o usuário precisa ter pelo menos a seguinte permissão de função:
ManageSecurity
(Consulte Create e gerenciar funções para obter mais informações)
Solicitação HTTP
POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions
Cabeçalhos de solicitação
Nome | Tipo | Descrição |
---|---|---|
Autorização | Cadeia de caracteres | {token} de portador. Obrigatório. |
Content-Type | string | application/json. Obrigatório. |
Corpo da solicitação
No corpo da solicitação, forneça um objeto JSON com os seguintes parâmetros:
Parâmetro | Tipo | Descrição |
---|---|---|
scanType | Enum | O tipo de verificação. Os valores possíveis são: "Windows", "Rede". Obrigatório. |
scanName | Cadeia de caracteres | Nome da verificação. Obrigatório. |
isActive | Booliano | Status de se a verificação está em execução ativamente. Obrigatório. |
destino | Cadeia de caracteres | Uma lista separada por vírgulas de destinos a serem verificados, endereços IP ou nomes de host. Obrigatório. |
intervalInHours | Int | O intervalo em que a verificação é executada. Obrigatório. |
Targettype | Cadeia de caracteres | O tipo de destino no campo de destino. Os tipos possíveis são "Endereço IP" ou "Nome do Host". O valor padrão é Endereço IP. Obrigatório. |
scannerAgent | Objeto | ID do computador. Obrigatório. |
scanAuthenticationParams | Objeto | Um objeto que representa os parâmetros de autenticação, consulte Propriedades de objeto parâmetros de autenticação para campos esperados. Essa propriedade é obrigatória ao criar uma nova verificação e é opcional ao atualizar uma verificação. |
Resposta
Se for bem-sucedido, esse método retornará o código de resposta 200 – Ok e a nova ou atualizada definição de verificação no corpo da resposta.
Solicitação de exemplo para adicionar uma nova verificação
Aqui está um exemplo de uma solicitação que adiciona uma nova verificação.
POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions
{
"scanType": "Windows",
"scanName": "Test Windows scan",
"isActive": true,
"target": "127.0.0.1",
"intervalInHours": 1,
"targetType": "Ip",
"scannerAgent": {
"machineId": "eb663a27ae9d032f61bc268a79eedf14c4b90f77",
},
"scanAuthenticationParams": {
"@odata.type": "#microsoft.windowsDefenderATP.api.WindowsAuthParams",
"type": "Kerberos",
"username": "username",
"domain": "password",
"isGmsaUser": true
}
}
Resposta de exemplo
Veja um exemplo de resposta.
{
"@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#DeviceAuthenticatedScanDefinitions/$entity",
"id": "289224fb-1686-472c-9751-5555960854ca",
"scanType": "Windows",
"scanName": "Test Windows scan",
"isActive": true,
"target": "127.0.0.1",
"orgId": "0335a792-18d2-424b-aeed-559567054570",
"intervalInHours": 1,
"createdBy": "username@test.com",
"targetType": "Ip",
"scanAuthenticationParams": null,
"scannerAgent": {
"id": "0335a792-18d2-424b-aeed-559567054570_ eb663a27ae9d032f61bc268a79eedf14c4b90f77",
"machineId": "eb663a27ae9d032f61bc268a79eedf14c4b90f77",
"machineName": "DESKTOP-TEST",
"lastSeen": "2023-01-04T09:40:03.2787058Z",
"assignedApplicationId": "ae4a5cde-b4a1-4b76-8635-458b2cf15752",
"scannerSoftwareVersion": "7.6.0.0",
"lastCommandExecutionTimestamp": "2023-01-04T09:33:16Z",
"mdeClientVersion": "10.8295.22621.1010"
},
"latestScan": {
"status": null,
"failureReason": null,
"executionDateTime": null
}
}
Solicitação de exemplo para atualizar uma verificação
Aqui está um exemplo de uma solicitação que atualiza uma verificação.
PATCH https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions/289224fb-1686-472c-9751-5555960854ca
{
"scanName": "Test Update Windows scan",
"isActive": false,
"target": "127.0.0.2,127.0.0.3",
"intervalInHours": 1,
"targetType": "Ip",
"scanAuthenticationParams": {
"@odata.type": "#microsoft.windowsDefenderATP.api.WindowsAuthParams",
"type": "Kerberos",
"username": "username",
"domain": "password",
"isGmsaUser": true
}
}
Exemplo de resposta
Veja um exemplo de resposta.
{
"@odata.context": "https://localhost:1059/api/$metadata#DeviceAuthenticatedScanDefinitions/$entity",
"id": "289224fb-1686-472c-9751-5555960854ca",
"scanType": "Windows",
"scanName": "Test Update Windows scan",
"isActive": false,
"target": "127.0.0.2,127.0.0.3",
"orgId": "0335a792-18d2-424b-aeed-559567054570",
"intervalInHours": 1,
"createdBy": "userName@microsoft.com",
"targetType": "Ip",
"scanAuthenticationParams": null,
"scannerAgent": {
"id": "0335a792-18d2-424b-aeed-559567054570_eb663a27ae9d032f61bc268a79eedf14c4b90f77",
"machineId": "eb663a27ae9d032f61bc268a79eedf14c4b90f77",
"machineName": "DESKTOP-TEST",
"lastSeen": "2023-01-04T09:40:03.2787058Z",
"assignedApplicationId": "ae4a5cde-b4a1-4b76-8635-458b2cf15752",
"scannerSoftwareVersion": "7.6.0.0",
"lastCommandExecutionTimestamp": "2023-01-04T09:33:16Z",
"mdeClientVersion": "10.8295.22621.1010"
},
"latestScan": {
"status": null,
"failureReason": null,
"executionDateTime": null
}
}
Solicitação de exemplo para excluir verificações
Aqui está um exemplo de uma solicitação que exclui verificações.
POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions/BatchDelete
{
"ScanDefinitionIds": ["td32f17af-5cc2-4e4e-964a-4c4ef7d216e2", "ab32g20af-5dd2-4a5e-954a-4c4ef7d216e2"],
}
Dica
Você deseja aprender mais? Engage com a comunidade de Segurança da Microsoft em nossa Comunidade Tecnológica: Microsoft Defender para Ponto de Extremidade Tech Community.
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de