匯出每個裝置的硬體和韌體評估清查

發行項
04/26/2024

適用於：

想要體驗 Microsoft Defender 弱點管理嗎？深入瞭解如何註冊 Microsoft Defender 弱點管理公開預覽試用版。

有不同的 API 呼叫可取得不同類型的數據。一般而言，每個 API 呼叫都會包含組織中裝置的必要數據。

JSON 回應 API 會將組織中的所有數據提取為 JSON 回應。此方法最適合 裝置少於 100 K 的小型組織。回應會進行分頁，因此您可以使用回應中的 @odata.nextLink 欄位來擷取下一個結果。
透過檔案 此 API 解決方案可讓您更快速且更可靠地提取大量數據。因此，建議大型組織使用超過100 K的裝置。此 API 會將組織中的所有資料提取為下載檔。回應包含可從 Azure 記憶體下載所有數據的 URL。您可以從 Azure 記憶體下載資料，如下所示：
- 呼叫 API 以取得包含您所有組織資料的下載 URL 清單。
- 使用下載 URL 下載所有檔案，並視需要處理數據。

使用「JSON 回應 或 透過檔案」收集的數據是目前狀態的目前快照集。它不包含歷史數據。若要收集歷史數據，客戶必須將數據儲存在自己的數據記憶體中。

注意事項

除非另有指示，否則列出的所有導出硬體和韌體評估方法都是 完整匯 出，而裝置 (也稱為 每個裝置)

1.導出硬體和韌體評估 (JSON 回應)

1.1 API 方法描述

根據每個裝置，傳回所有裝置的所有硬體和韌體評估。它會針對 deviceId 和 componentType 的每個唯一組合，傳回具有個別項目的數據表。

1.1.1 限制

頁面大小上限為 200,000。
此 API 的速率限制為每分鐘 30 次呼叫，每小時 1000 次呼叫。

1.2 許可權

呼叫此 API 需要下列其中一個許可權。若要深入瞭解，包括如何選擇許可權，請參閱使用適用於端點的 Microsoft Defender API 以取得詳細數據。

許可權類型	權限	許可權顯示名稱
應用程式	Software.Read.All	「讀取威脅和弱點管理軟體資訊」
委派 (公司或學校帳戶)	Software.Read	「讀取威脅和弱點管理軟體資訊」

1.3 URL

GET api/machines/HardwareFirmwareInventoryByMachine

1.4 參數

pageSize (預設值 = 50,000) ：回應中的結果數目。
$top：要傳回的結果數目 (不會傳回 @odata.nextLink ，因此不會提取所有數據) 。

1.5 JSON 回應 (屬性)

注意事項

每筆記錄大約是 1 KB 的數據。當您選擇正確的 pageSize 參數時，應該將此納入考慮。

回應中可能會傳回一些額外的數據行。這些數據行是暫時性的，而且可能會被移除。僅使用記載的數據行。

下表中定義的屬性會依屬性標識元依字母順序列出。執行此 API 時，產生的輸出不一定會以此數據表所列的相同順序傳回。

屬性 (識別碼)	資料類型	描述
deviceId	字串	服務中裝置的唯一標識符。
rbacGroupId	臨界值	角色型訪問控制 (RBAC) 群組標識碼。如果裝置未指派給任何 RBAC 群組，則值會是 “Unassigned”。如果組織不包含任何 RBAC 群組，則值會是「None」。
rbacGroupName	字串	角色型訪問控制 (RBAC) 群組。如果裝置未指派給任何 RBAC 群組，則值會是 “Unassigned”。如果組織不包含任何 RBAC 群組，則值會是「None」。
deviceName	字串	裝置的 FQDN) (完整功能變數名稱。
componentType	字串	硬體或韌體元件的類型。
製造商	字串	特定硬體或韌體元件的製造商。
componentName	字串	特定硬體或韌體元件的名稱。
componentVersion	字串	特定硬體或韌體元件的版本。
additionalFields	字串	JSON 數位格式元件的其他相關信息。

1.6 範例

1.6.1 要求範例

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

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.透過檔案導出硬體和韌體評估 ()

2.1 API 方法描述

根據每個裝置，傳回所有裝置的所有硬體和韌體評估。它會針對 DeviceId、ComponentType 和 ComponentName 的每個唯一組合，傳回具有個別項目的數據表。

2.1.1 限制

此 API 的速率限制為每分鐘 5 次呼叫，每小時 20 次呼叫。

2.2 許可權

呼叫此 API 需要下列其中一個許可權。若要深入瞭解，包括如何選擇許可權，請參閱使用適用於端點的 Microsoft Defender API 以取得詳細數據。

許可權類型	權限	許可權顯示名稱
應用程式	Software.Read.All	「讀取威脅和弱點管理軟體資訊」
委派 (公司或學校帳戶)	Software.Read	「讀取威脅和弱點管理軟體資訊」

2.3 URL

GET /api/machines/HardwareFirmwareInventoryExport

2.4 參數

sasValidHours：下載 URL 的有效時數 () 最多 24 小時。

2.5 JSON 回應 (屬性)

注意事項

檔案是以多行 JSON 格式壓縮 &。

下載 URL 的有效期只有 3 小時;否則，您可以使用參數。

若要將下載速度最大化，請確定您是從數據所在的相同 Azure 區域下載數據。

每筆記錄大約是 1 KB 的數據。當您選擇適合您的 pageSize 參數時，應該將此納入考慮。

回應中可能會傳回一些額外的數據行。這些數據行是暫時性的，而且可能會被移除。僅使用記載的數據行。

屬性 (識別碼)	資料類型	描述
匯出檔案	String[array]	保存組織目前快照集之檔案的下載 URL 清單。
GeneratedTime	DateTime	產生匯出的時間。

2.6 範例

2.6.1 要求範例

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

2.6.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"

   }

共用方式為

匯出每個裝置的硬體和韌體評估清查

1.導出硬體和韌體評估 (JSON 回應)

1.1 API 方法描述

1.1.1 限制

1.2 許可權

1.3 URL

1.4 參數

1.5 JSON 回應 (屬性)

1.6 範例

1.6.1 要求範例

1.6.2 回應範例

2.透過檔案導出硬體和韌體評估 ()

2.1 API 方法描述

2.1.1 限制

2.2 許可權

2.3 URL

2.4 參數

2.5 JSON 回應 (屬性)

2.6 範例

2.6.1 要求範例

2.6.2 回應範例

意見反應

其他資源