Condividi tramite

Esportare l'inventario di valutazione hardware e firmware per dispositivo

  • Articolo

Si applica a:

Vuoi provare Gestione delle vulnerabilità di Microsoft Defender? Altre informazioni su come iscriversi alla versione di valutazione dell'anteprima pubblica Gestione delle vulnerabilità di Microsoft Defender.

Sono disponibili diverse chiamate API per ottenere tipi diversi di dati. In generale, ogni chiamata API contiene i dati necessari per i dispositivi dell'organizzazione.

  • Risposta JSON L'API esegue il pull di tutti i dati nell'organizzazione come risposte JSON. Questo metodo è ideale per le organizzazioni di piccole dimensioni con meno di 100 K dispositivi. La risposta viene impaginata, quindi è possibile usare il campo @odata.nextLink dalla risposta per recuperare i risultati successivi.

  • tramite file Questa soluzione API consente di eseguire il pull di grandi quantità di dati in modo più rapido e affidabile. È quindi consigliabile per le organizzazioni di grandi dimensioni, con più di 100.000 dispositivi. Questa API esegue il pull di tutti i dati nell'organizzazione come file di download. La risposta contiene URL per scaricare tutti i dati da Archiviazione di Azure. È possibile scaricare i dati da Archiviazione di Azure come indicato di seguito:

    • Chiamare l'API per ottenere un elenco di URL di download con tutti i dati dell'organizzazione.
    • Scaricare tutti i file usando gli URL di download ed elaborare i dati come si desidera.

I dati raccolti usando "risposta JSON o tramite file" sono lo snapshot corrente dello stato corrente. Non contiene dati cronologici. Per raccogliere dati cronologici, i clienti devono salvare i dati nei propri archivi dati.

Nota

Se non indicato diversamente, tutti i metodi di valutazione dell'hardware e del firmware di esportazione elencati sono l'esportazione completa e il dispositivo (detto anche per dispositivo)

1. Esportare la valutazione hardware e firmware (risposta JSON)

Descrizione del metodo API 1.1

Restituisce tutte le valutazioni hardware e firmware per tutti i dispositivi, in base al dispositivo. Restituisce una tabella con una voce separata per ogni combinazione univoca di deviceId e componentType.

1.1.1 Limitazioni

  • La dimensione massima della pagina è 200.000.
  • Le limitazioni di frequenza per questa API sono 30 chiamate al minuto e 1000 chiamate all'ora.

1.2 Autorizzazioni

Per chiamare questa API è necessaria una delle autorizzazioni seguenti. Per altre informazioni, inclusa la scelta delle autorizzazioni, vedere Usare le API Microsoft Defender per endpoint per informazioni dettagliate.

Tipo di autorizzazione Autorizzazione Nome visualizzato autorizzazioni
Applicazione Software.Read.All 'Leggere le informazioni sul software di gestione delle minacce e delle vulnerabilità'
Delegato (account aziendale o dell'istituto di istruzione) Software.Read 'Leggere le informazioni sul software di gestione delle minacce e delle vulnerabilità'

1.3 URL

GET api/machines/HardwareFirmwareInventoryByMachine

1.4 Parametri

  • pageSize (valore predefinito = 50.000): numero di risultati in risposta.
  • $top: numero di risultati da restituire (non restituisce @odata.nextLink e quindi non esegue il pull di tutti i dati).

1.5 Proprietà (risposta JSON)

Nota

Ogni record è di circa 1 KB di dati. È consigliabile tenere conto di questo aspetto quando si sceglie il parametro pageSize corretto.

Nella risposta potrebbero essere restituite alcune colonne aggiuntive. Queste colonne sono temporanee e potrebbero essere rimosse. Usare solo le colonne documentate.

Le proprietà definite nella tabella seguente sono elencate in ordine alfabetico in base all'ID proprietà. Quando si esegue questa API, l'output risultante non verrà necessariamente restituito nello stesso ordine elencato in questa tabella.

Proprietà (ID) Tipo di dati Descrizione
IDdispositivo Stringa Identificatore univoco per il dispositivo nel servizio.
rbacGroupId Soglia ID del gruppo controllo degli accessi in base al ruolo. Se il dispositivo non è assegnato a un gruppo di controllo degli accessi in base al ruolo, il valore sarà "Non assegnato". Se l'organizzazione non contiene gruppi di controllo degli accessi in base al ruolo, il valore sarà "Nessuno".
rbacGroupName Stringa Gruppo di controllo degli accessi in base al ruolo. Se il dispositivo non è assegnato a un gruppo di controllo degli accessi in base al ruolo, il valore sarà "Non assegnato". Se l'organizzazione non contiene gruppi di controllo degli accessi in base al ruolo, il valore sarà "Nessuno".
deviceName Stringa Nome di dominio completo (FQDN) del dispositivo.
componentType Stringa Tipo di componente hardware o firmware.
fabbricante Stringa Produttore di un componente hardware o firmware specifico.
componentName Stringa Nome di un componente hardware o firmware specifico.
componentVersion Stringa Versione di un componente hardware o firmware specifico.
additionalFields Stringa Informazioni aggiuntive sui componenti in formato matrice JSON.

Esempio 1.6

1.6.1 Esempio di richiesta

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

Esempio di risposta 1.6.2

      {
        "@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. Esportare la valutazione hardware e firmware (tramite file)

Descrizione del metodo API 2.1

Restituisce tutte le valutazioni hardware e firmware per tutti i dispositivi, in base al dispositivo. Restituisce una tabella con una voce separata per ogni combinazione univoca di DeviceId, ComponentType e ComponentName.

2.1.1 Limitazioni

  • Le limitazioni di frequenza per questa API sono 5 chiamate al minuto e 20 chiamate all'ora.

2.2 Autorizzazioni

Per chiamare questa API è necessaria una delle autorizzazioni seguenti. Per altre informazioni, inclusa la scelta delle autorizzazioni, vedere Usare le API Microsoft Defender per endpoint per informazioni dettagliate.

Tipo di autorizzazione Autorizzazione Nome visualizzato autorizzazioni
Applicazione Software.Read.All 'Leggere le informazioni sul software di gestione delle minacce e delle vulnerabilità'
Delegato (account aziendale o dell'istituto di istruzione) Software.Read 'Leggere le informazioni sul software di gestione delle minacce e delle vulnerabilità'

URL 2.3

GET /api/machines/HardwareFirmwareInventoryExport

2.4 Proprietà (risposta JSON)

Nota

  • I file sono compressi in gzip & in formato Json multilinea.
  • Gli URL di download sono validi solo per 1 ora.
  • Per ottimizzare la velocità di download, assicurarsi di scaricare i dati dalla stessa area di Azure in cui si trovano i dati.
  • Ogni record è di circa 1 KB di dati. È consigliabile portarlo in considerazione quando si sceglie il parametro pageSize che funziona automaticamente.
  • Nella risposta potrebbero essere restituite alcune colonne aggiuntive. Queste colonne sono temporanee e potrebbero essere rimosse. Usare solo le colonne documentate.
Proprietà (ID) Tipo di dati Descrizione
Esportare file String[array] Elenco di URL di download per i file che contengono lo snapshot corrente dell'organizzazione.
GeneratedTime DateTime Ora in cui è stata generata l'esportazione.

Esempi 2.5

2.5.1 Esempio di richiesta

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

Esempio di risposta 2.5.2

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

   }