Exporter l’inventaire de l’évaluation du matériel et du microprogramme par appareil

Article
04/26/2024

S’applique à :

Vous souhaitez découvrir Gestion des vulnérabilités Microsoft Defender ? En savoir plus sur la façon dont vous pouvez vous inscrire à la version d’évaluation publique Gestion des vulnérabilités Microsoft Defender.

Il existe différents appels d’API pour obtenir différents types de données. En général, chaque appel d’API contient les données requises pour les appareils de votre organization.

Réponse JSON L’API extrait toutes les données de votre organization sous forme de réponses JSON. Cette méthode est idéale pour les petites organisations avec moins de 100 000 appareils. La réponse étant paginée, vous pouvez utiliser le champ @odata.nextLink de la réponse pour extraire les résultats suivants.
via des fichiers Cette solution d’API permet d’extraire de plus grandes quantités de données plus rapidement et de manière plus fiable. Il est donc recommandé pour les grandes organisations, avec plus de 100 000 appareils. Cette API extrait toutes les données de votre organization en tant que fichiers de téléchargement. La réponse contient des URL pour télécharger toutes les données à partir du stockage Azure. Vous pouvez télécharger des données à partir du Stockage Azure comme suit :
- Appelez l’API pour obtenir une liste d’URL de téléchargement avec toutes vos données organization.
- Téléchargez tous les fichiers à l’aide des URL de téléchargement et traitez les données comme vous le souhaitez.

Les données collectées à l’aide de « réponse JSON ou via des fichiers » sont les instantané actuelles de l’état actuel. Il ne contient pas de données historiques. Pour collecter des données historiques, les clients doivent enregistrer les données dans leurs propres stockages de données.

Remarque

Sauf indication contraire, toutes les méthodes d’évaluation du matériel et du microprogramme d’exportation répertoriées sont l’exportation complète et par appareil (également appelée par appareil)

1. Exporter l’évaluation du matériel et du microprogramme (réponse JSON)

1.1 Description de la méthode d’API

Retourne toutes les évaluations de matériel et de microprogramme pour tous les appareils, par appareil. Elle retourne une table avec une entrée distincte pour chaque combinaison unique de deviceId et componentType.

1.1.1 Limitations

La taille maximale de la page est de 200 000.
Les limitations de débit pour cette API sont de 30 appels par minute et de 1 000 appels par heure.

1.2 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 Microsoft Defender pour point de terminaison pour plus d’informations.

Type d’autorisation	Autorisation	Nom complet de l’autorisation
Application	Software.Read.All	« Lire les informations logicielles de gestion des menaces et des vulnérabilités »
Déléguée (compte professionnel ou scolaire)	Software.Read	« Lire les informations logicielles de gestion des menaces et des vulnérabilités »

1.3 URL

GET api/machines/HardwareFirmwareInventoryByMachine

1.4 Paramètres

pageSize (valeur par défaut = 50 000) : nombre de résultats dans la réponse.
$top : nombre de résultats à retourner (ne retourne @odata.nextLink pas et n’extrait donc pas toutes les données).

1.5 Propriétés (réponse JSON)

Remarque

Chaque enregistrement représente environ 1 Ko de données. Vous devez en tenir compte lors du choix du paramètre pageSize approprié.

Certaines colonnes supplémentaires peuvent être retournées dans la réponse. Ces colonnes sont temporaires et peuvent être supprimées. Utilisez uniquement les colonnes documentées.

Les propriétés définies dans le tableau suivant sont répertoriées par ordre alphabétique par ID de propriété. Lors de l’exécution de cette API, la sortie résultante n’est pas nécessairement retournée dans le même ordre que celui indiqué dans cette table.

Propriété (ID)	Type de données	Description
deviceId	Chaîne	Identificateur unique de l’appareil dans le service.
rbacGroupId	Int	ID de groupe de contrôle d’accès en fonction du rôle (RBAC). Si l’appareil n’est affecté à aucun groupe RBAC, la valeur est « Non affecté ». Si le organization ne contient aucun groupe RBAC, la valeur est « None ».
rbacGroupName	Chaîne	Groupe de contrôle d’accès en fonction du rôle (RBAC). Si l’appareil n’est affecté à aucun groupe RBAC, la valeur est « Non affecté ». Si le organization ne contient aucun groupe RBAC, la valeur est « None ».
deviceName	Chaîne	Nom de domaine complet (FQDN) de l’appareil.
componentType	Chaîne	Type de composant matériel ou de microprogramme.
Fabricant	Chaîne	Fabricant d’un composant matériel ou microprogramme spécifique.
componentName	Chaîne	Nom d’un composant matériel ou microprogramme spécifique.
componentVersion	Chaîne	Version d’un composant matériel ou microprogramme spécifique.
additionalFields	Chaîne	Informations supplémentaires sur les composants au format tableau JSON.

1.6 Exemple

1.6.1 Exemple de requête

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

1.6.2 Exemple de réponse

      {
        "@odata.context": "https://api-df.securitycenter.microsoft.com/api/$metadata#Collection(microsoft.windowsDefenderATP.api.AssetHardwareFirmware)",
        "value":[
        {
            "deviceId": "49126b9e4a5473b5229c73799e9e55c48668101b",
            "rbacGroupId": 39,
            "rbacGroupName": "testO6343398Gq31",
            "deviceName": "testmachine5",
            "componentType": "Hardware",
            "manufacturer": "razer",
            "componentName": "blade_15_advanced_model_(mid_2021)_-_rz09-0409",
            "componentVersion": "7.04",
            "additionalFields": "{\"SystemSKU\":\"RZ09-0409CE53\",\"BaseBoardManufacturer\":\"Razer\",\"BaseBoardProduct\":\"CH570\",\"BaseBoardVersion\":\"4\",\"DeviceFamily\":\"Workstation\"}"
          }  
        ]  
      },

2. Exporter l’évaluation du matériel et du microprogramme (via des fichiers)

2.1 Description de la méthode d’API

2.1.1 Limitations

Les limitations de débit pour cette API sont de 5 appels par minute et de 20 appels par heure.

2.2 Autorisations

Type d’autorisation	Autorisation	Nom complet de l’autorisation
Application	Software.Read.All	« Lire les informations logicielles de gestion des menaces et des vulnérabilités »
Déléguée (compte professionnel ou scolaire)	Software.Read	« Lire les informations logicielles de gestion des menaces et des vulnérabilités »

2.3 URL

GET /api/machines/HardwareFirmwareInventoryExport

2.4 Paramètres

sasValidHours : nombre d’heures pendant lesquelles les URL de téléchargement seront valides (maximum 24 heures).

2.5 Propriétés (réponse JSON)

Remarque

Les fichiers sont compressés gzip & au format Json multiligne.

Les URL de téléchargement ne sont valides que pendant 3 heures ; sinon, vous pouvez utiliser le paramètre .

Pour optimiser les vitesses de téléchargement, veillez à télécharger les données à partir de la même région Azure où résident vos données.

Chaque enregistrement représente environ 1 Ko de données. Vous devez en tenir compte lors du choix du paramètre pageSize qui vous convient.

Certaines colonnes supplémentaires peuvent être retournées dans la réponse. Ces colonnes sont temporaires et peuvent être supprimées. Utilisez uniquement les colonnes documentées.

Propriété (ID)	Type de données	Description
Exporter des fichiers	String[array]	Liste des URL de téléchargement des fichiers contenant le instantané actuel du organization.
GeneratedTime	DateTime	Heure à laquelle l’exportation a été générée.

2.6 Exemple

2.6.1 Exemple de demande

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

2.6.2 Exemple de réponse

    {
        "@odata.context":"https://api-df.securitycenter.microsoft.com/api/$metadata#microsoft.windowsDefenderATP.api.ExportFilesResponse",
    "exportFiles": [
        "https://tvmexportstrprdcane.blob.core.windows.net/tvm-firmware-export/2022-07-11/1101/FirmwareHardwareExport/json/OrgId=3837d1f5-0d51-40cb-a99d-69ebedc9dcc8/_RbacGroupId=39/part-00999-71eea973-1bb1-4d0a-829d-80cb07aff5d8.c000.json.gz?sv=2020-08-04&st=2022-07-11T13%3A10%3A06Z&se=2022-07-11T16%3A10%3A06Z&sr=b&sp=r&sig=muN8Sq6rVN6bFMtR0u3S5Wzh3D9qNPgN5vpU7lWvULg%3D",
        "https://tvmexportstrprdcane.blob.core.windows.net/tvm-firmware-export/2022-07-11/1101/FirmwareHardwareExport/json/OrgId=3837d1f5-0d51-40cb-a99d-69ebedc9dcc8/_RbacGroupId=9/part-00968-71eea973-1bb1-4d0a-829d-80cb07aff5d8.c000.json.gz?sv=2020-08-04&st=2022-07-11T13%3A10%3A06Z&se=2022-07-11T16%3A10%3A06Z&sr=b&sp=r&sig=%2BA0%2B4qOOBCS5E4UenJPbMdLM%2FkbXHnz%2F1pvfSOCq%2F2s%3D",
        "https://tvmexportstrprdcane.blob.core.windows.net/tvm-firmware-export/2022-07-11/1101/FirmwareHardwareExport/json/OrgId=3837d1f5-0d51-40cb-a99d-69ebedc9dcc8/_RbacGroupId=9/part-00969-71eea973-1bb1-4d0a-829d-80cb07aff5d8.c000.json.gz?sv=2020-08-04&st=2022-07-11T13%3A10%3A06Z&se=2022-07-11T16%3A10%3A06Z&sr=b&sp=r&sig=sZUgYMwSr5zk6BZvS%2BoYIWlHJWk2oJ7YjiC8R26S1X4%3D"
    ],
    "generatedTime": "2022-07-11T11:01:00Z"

   }

Partager via

Exporter l’inventaire de l’évaluation du matériel et du microprogramme par appareil

1. Exporter l’évaluation du matériel et du microprogramme (réponse JSON)

1.1 Description de la méthode d’API

1.1.1 Limitations

1.2 Autorisations

1.3 URL

1.4 Paramètres

1.5 Propriétés (réponse JSON)

1.6 Exemple

1.6.1 Exemple de requête

1.6.2 Exemple de réponse

2. Exporter l’évaluation du matériel et du microprogramme (via des fichiers)

2.1 Description de la méthode d’API

2.1.1 Limitations

2.2 Autorisations

2.3 URL

2.4 Paramètres

2.5 Propriétés (réponse JSON)

2.6 Exemple

2.6.1 Exemple de demande

2.6.2 Exemple de réponse

Commentaires

Ressources supplémentaires