Partager via

Ajouter, mettre à jour ou supprimer une définition d’analyse

  • Article

S’applique à :

Vous voulez découvrir Microsoft Defender pour point de terminaison ? Inscrivez-vous pour bénéficier d’un essai gratuit.

Vous souhaitez découvrir Microsoft Defender Vulnerability Management ? En savoir plus sur la façon dont vous pouvez vous inscrire à la version d’évaluation publique de Microsoft Defender Vulnerability Management.

Importante

Certaines informations contenues dans cet article concernent le produit en préversion, qui peut être considérablement modifié avant sa publication commerciale. Microsoft n’offre aucune garantie, explicite ou implicite, concernant les informations fournies ici.

Remarque

Si vous êtes un client du gouvernement des États-Unis, utilisez les URI répertoriés dans Microsoft Defender pour point de terminaison pour les clients du gouvernement des États-Unis.

Conseil

Pour de meilleures performances, vous pouvez utiliser le serveur plus près de votre emplacement géographique :

  • 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
  • ina.api.security.microsoft.com

Description de l’API

API pour ajouter, mettre à jour ou supprimer une analyse authentifiée.

Limitations

Les limitations de débit pour cette API sont de 100 appels par minute et de 1 500 appels par heure.

Vous pouvez publier sur les ordinateurs vus pour la dernière fois en fonction de la période de rétention configurée.

Autorisations

L’une des autorisations suivantes est nécessaire pour appeler cette API. Pour en savoir plus, notamment sur le choix des autorisations, consultez Utiliser les API Defender pour point de terminaison.

Type d’autorisation Autorisation Nom complet de l’autorisation
Application Machine.ReadWrite.All Lire et écrire toutes les informations d’analyse.
Déléguée (compte professionnel ou scolaire) Machine.Read.Write Lire et écrire toutes les informations d’analyse.

Remarque

Lors de l’obtention d’un jeton à l’aide des informations d’identification de l’utilisateur :

  • Pour afficher les données, l’utilisateur doit disposer au moins de l’autorisation de rôle suivante : ViewData ou TvmViewData (voir Créer et gérer des rôles pour plus d’informations)
  • Pour modifier des données, l’utilisateur doit disposer au moins de l’autorisation de rôle suivante : ManageSecurity (voir Créer et gérer des rôles pour plus d’informations)

Requête HTTP

POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions

En-têtes de demande

Nom Type Description
Autorisation Chaîne Porteur {token}. Obligatoire.
Content-Type string application/json. Obligatoire.

Corps de la demande

Dans le corps de la demande, fournissez un objet JSON avec les paramètres suivants :

Paramètre Type Description
scanType Énum Type d’analyse. Les valeurs possibles sont : « Windows », « Réseau ». Obligatoire.
scanName Chaîne Nom de l’analyse. Obligatoire.
isActive Valeur booléenne État indiquant si l’analyse est en cours d’exécution active. Obligatoire.
target Chaîne Liste séparée par des virgules des cibles à analyser, soit des adresses IP, soit des noms d’hôte. Obligatoire.
intervalInHours Int Intervalle auquel l’analyse s’exécute. Obligatoire.
targetType Chaîne Type de cible dans le champ cible. Les types possibles sont « Adresse IP » ou « Nom d’hôte ». La valeur par défaut est Adresse IP. Obligatoire.
scannerAgent Objet ID de l’ordinateur. Obligatoire.
scanAuthenticationParams Objet Objet représentant les paramètres d’authentification, consultez Propriétés de l’objet Paramètres d’authentification pour les champs attendus. Cette propriété est obligatoire lors de la création d’une analyse et est facultative lors de la mise à jour d’une analyse.

Réponse

Si elle réussit, cette méthode renvoie le code de réponse 200 - Ok et la définition d’analyse nouvelle ou mise à jour dans le corps de la réponse.

Exemple de demande d’ajout d’une nouvelle analyse

Voici un exemple de requête qui ajoute une nouvelle analyse.

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
    }
}

Exemple de réponse

Voici un exemple de réponse.

 {
"@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
    }

}

Exemple de demande de mise à jour d’une analyse

Voici un exemple de demande qui met à jour une analyse.

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
    }
 }

Exemple de réponse

Voici un exemple de réponse.

{
    "@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
    }
}

Exemple de demande de suppression d’analyses

Voici un exemple de requête qui supprime des analyses.

POST https://api.securitycenter.microsoft.com/api/DeviceAuthenticatedScanDefinitions/BatchDelete

{
  "ScanDefinitionIds": ["td32f17af-5cc2-4e4e-964a-4c4ef7d216e2", "ab32g20af-5dd2-4a5e-954a-4c4ef7d216e2"],
}

Conseil

Voulez-vous en savoir plus ? Collaborez avec la communauté Microsoft Security dans notre communauté technique : Microsoft Defender pour point de terminaison Tech Community.