Partager via

API Répertorier les machines

  • Article

S’applique à :

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

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

Récupère une collection de machines qui ont communiqué avec Microsoft Defender pour point de terminaison.

Prend en charge les requêtes OData V4.

La requête OData $filter est prise en charge sur : computerDnsName, id, versiondeviceValue, aadDeviceId, , machineTagslastSeen,exposureLevelonboardingStatus , lastIpAddress, healthStatus, osPlatformriskScore , et .rbacGroupId
$top avec la valeur maximale de 10 000
$skip Consultez des exemples dans Requêtes OData avec Defender pour point de terminaison

Limitations

  • Vous pouvez obtenir les appareils vus pour la dernière fois en fonction de la période de rétention configurée.
  • La taille maximale de la page est de 10 000.
  • Les limitations de débit pour cette API sont de 100 appels par minute et de 1 500 appels par heure.

Autorisations

Type d’autorisation Autorisation Nom complet de l’autorisation
Application Machine.Read.All « Lire tous les profils d’ordinateur »
Application Machine.ReadWrite.All « Lire et écrire toutes les informations de l’ordinateur »
Déléguée (compte professionnel ou scolaire) Machine.Read « Lire les informations de l’ordinateur »
Déléguée (compte professionnel ou scolaire) Machine.ReadWrite « Lire et écrire des informations sur la machine »

Lors de l’obtention d’un jeton à l’aide des informations d’identification de l’utilisateur, l’utilisateur doit disposer au moins de l’autorisation de rôle suivante : View Data (voir Créer et gérer des rôles).

Les réponses incluent uniquement les appareils auxquels l’utilisateur a accès, en fonction des paramètres du groupe d’appareils (voir Créer et gérer des groupes d’appareils).

La création de groupes d’appareils est prise en charge dans Defender pour point de terminaison Plan 1 et Plan 2.

Requête HTTP

GET https://api.security.microsoft.com/api/machines

En-têtes de demande

Nom Type Description
Autorisation Chaîne Porteur {token}. Obligatoire.

Corps de la demande

Empty

Réponse

Si l’opération réussit et que les machines existent, vous voyez 200 OK la liste des entités de machine dans le corps. S’il n’y a pas de machines récentes, vous voyez 404 Not Found.

Exemple

Exemple de requête

Voici un exemple de demande.

GET https://api.security.microsoft.com/api/machines

Exemple de réponse

Voici un exemple de réponse.

HTTP/1.1 200 OK
Content-type: application/json
{
    "@odata.context": "https://api.security.microsoft.com/api/$metadata#Machines",
    "value": [
        {
            "id": "1e5bc9d7e413ddd7902c2932e418702b84d0cc07",
            "computerDnsName": "mymachine1.contoso.com",
            "firstSeen": "2018-08-02T14:55:03.7791856Z",
            "lastSeen": "2018-08-02T14:55:03.7791856Z",
            "osPlatform": "Windows10" "Windows11",
            "version": "1709",
            "osProcessor": "x64",
            "lastIpAddress": "172.17.230.209",
            "lastExternalIpAddress": "167.220.196.71",
            "osBuild": 18209,
            "healthStatus": "Active",
            "rbacGroupId": 140,
            "rbacGroupName": "The-A-Team",
            "riskScore": "Low",
            "exposureLevel": "Medium",
            "isAadJoined": true,
            "aadDeviceId": "80fe8ff8-2624-418e-9591-41f0491218f9",
            "machineTags": [ "test tag 1", "test tag 2" ]
        }
        ...
    ]
}

Conseil

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