每個裝置匯出軟體清查評估Export software inventory assessment per device

適用於:Applies to:

想要體驗適用於端點的 Microsoft Defender 嗎?Want to experience Microsoft Defender for Endpoint? 注册免費試用版。Sign up for a free trial.

重要

部分資訊與發行前版本產品有關,在正式發行之前可能會實質上進行修改。Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft 對此處提供的資訊,不提供任何明確或隱含的瑕疵擔保。Microsoft makes no warranties, express or implied, with respect to the information provided here.

有不同的 API 呼叫可取得不同的資料類型。There are different API calls to get different types of data. 因為資料量可能很大,所以可供檢索的方式有兩種:Because the amount of data can be large, there are two ways it can be retrieved:

  • 匯出軟體清查評估 OData API 將組織中的所有資料都提取為 Json 回應,遵循 OData 的通訊協定。Export software inventory assessment OData The API pulls all data in your organization as Json responses, following the OData protocol. 這種方法最適合 小型組織,且少於 100 K 裝置This method is best for small organizations with less than 100-K devices. 回應已分頁,所以您可以使用 @ nextLink 欄位從回應讀取下一個結果。The response is paginated, so you can use the @odata.nextLink field from the response to fetch the next results.

  • 透過檔案匯出軟體清查評估 此 API 解決方案可讓大量的資料更快速且可靠地進行。Export software inventory assessment via files This API solution enables pulling larger amounts of data faster and more reliably. 因此,建議大型組織使用超過 100 K 的裝置。Therefore, it is recommended for large organizations, with more than 100-K devices. 此 API 會將組織中的所有資料都提取為下載檔案。This API pulls all data in your organization as download files. 回應包含從 Azure 儲存體下載所有資料的 URLs。The response contains URLs to download all the data from Azure Storage. 此 API 可讓您從 Azure 儲存體下載所有資料,如下所示:This API enables you to download all your data from Azure Storage as follows:

    • 呼叫 API 以取得所有組織資料的下載 URLs 清單。Call the API to get a list of download URLs with all your organization data.

    • 使用下載 URLs 下載所有檔案,並視需要處理資料。Download all the files using the download URLs and process the data as you like.

使用 OData 或透過 檔案收集 (所收集的資料,) 目前狀態的目前快照,且不包含歷史資料。Data that is collected (using either OData or via files) is the current snapshot of the current state, and does not contain historic data. 為了收集歷史資料,客戶必須將資料儲存在自己的資料儲存中。In order to collect historic data, customers must save the data in their own data storages.

注意

除非另有說明,否則所列的所有出口評估方法都是 完整匯出 ,而且 依裝置 (也稱為 每個裝置) 。Unless indicated otherwise, all export assessment methods listed are full export and by device (also referred to as per device).

1. 匯出軟體清查評估 (OData) 1. Export software inventory assessment (OData)

1.1 API 方法描述1.1 API method description

此 API 回應包含每個裝置已安裝軟體的所有資料。This API response contains all the data of installed software per device. 會傳回資料表,其中包含 DeviceId、SoftwareVendor、SoftwareName、SoftwareVersion 的每個唯一組合的專案。Returns a table with an entry for every unique combination of DeviceId, SoftwareVendor, SoftwareName, SoftwareVersion.

限制Limitations

  • 頁面大小上限為200000。Maximum page size is 200,000.

  • 此 API 的速率限制為每分鐘30個通話,每小時1000個通話。Rate limitations for this API are 30 calls per minute and 1000 calls per hour.

1.2 許可權1.2 Permissions

需要有下列其中一個許可權才能呼叫此 API。One of the following permissions is required to call this API. 若要深入瞭解,包括如何選擇許可權,請參閱 使用 Microsoft Defender For Endpoint APIs 以取得詳細資訊。To learn more, including how to choose permissions, see Use Microsoft Defender for Endpoint APIs for details.

許可權類型Permission type 權限Permission 許可權顯示名稱Permission display name
應用程式Application 已讀取軟體。所有Software.Read.All '讀取威脅及弱點管理弱點資訊''Read Threat and Vulnerability Management vulnerability information'
委派 (工作或學校帳戶) Delegated (work or school account) 軟體. 讀取Software.Read '讀取威脅及弱點管理弱點資訊''Read Threat and Vulnerability Management vulnerability information'

1.3 URL1.3 URL

GET /api/machines/SoftwareInventoryByMachine

1.4 參數1.4 Parameters

  • pageSize (預設值 = 50000) –回應的結果數目。pageSize (default = 50,000) – number of results in response.

  • $top –傳回的結果數 (不會傳回 @odata nextLink,因此不會拉入所有資料) $top – number of results to return (doesn’t return @odata.nextLink and therefore doesn’t pull all the data)

1.5 屬性1.5 Properties

注意

-每筆記錄大約 0.5 KB 的資料。-Each record is approximately 0.5KB of data. 為您選擇正確的 pageSize 參數時,您應該考慮使用此帳戶。You should take this into account when choosing the correct pageSize parameter for you.

-在下表中定義的屬性依屬性識別碼列出字母順序。-The properties defined in the following table are listed alphabetically, by property ID. 執行此 API 時,所產生的輸出不一定會依照此表中所列的順序傳回。When running this API, the resulting output will not necessarily be returned in the same order listed in this table.

-回應中可能傳回其他一些欄。-Some additional columns might be returned in the response. 這些欄是暫存檔的,而且可能會被移除,請只使用記錄的資料行。These columns are temporary and might be removed, please use only the documented columns.

屬性 (識別碼) Property (ID) 資料類型Data type 描述Description 傳回值的範例Example of a returned value
DeviceIdDeviceId stringstring 服務中裝置的唯一識別碼。Unique identifier for the device in the service. 9eaf3a8b5962e0e6b1af9ec756664a9b823df2d19eaf3a8b5962e0e6b1af9ec756664a9b823df2d1
DeviceNameDeviceName stringstring 裝置 (FQDN) 的完整功能變數名稱。Fully qualified domain name (FQDN) of the device. johnlaptop.europe.contoso.comjohnlaptop.europe.contoso.com
DiskPathsDiskPaths 陣列 [字串]Array[string] 在裝置上安裝產品的磁片證據。Disk evidence that the product is installed on the device. [C: \ (x86) \ Microsoft \ Silverlight \ 應用程式 \silverlight.exe "] 的程式檔案[ "C:\Program Files (x86)\Microsoft\Silverlight\Application\silverlight.exe" ]
EndOfSupportDateEndOfSupportDate stringstring 此軟體支援或會結束的日期。The date in which support for this software has or will end. 2020-12-302020-12-30
EndOfSupportStatusEndOfSupportStatus stringstring 支援狀態的結束。End of support status. 可以包含這些可能的值:無、EOS 版本、即將發生的 EOS 版本、EOS 軟體(即將進行的 EOS 軟體)。Can contain these possible values: None, EOS Version, Upcoming EOS Version, EOS Software, Upcoming EOS Software. 即將進行的 EOSUpcoming EOS
識別碼Id stringstring 記錄的唯一識別碼。Unique identifier for the record. 123ABG55_573AG&mnp!123ABG55_573AG&mnp!
NumberOfWeaknessesNumberOfWeaknesses intint 此裝置上的此軟體弱點數目Number of weaknesses on this software on this device 3
OSPlatformOSPlatform stringstring 裝置上所執行作業系統的平臺。Platform of the operating system running on the device. 這表示特定作業系統,包括相同系列內的變體,例如 Windows 10 和 Windows 7。This indicates specific operating systems, including variations within the same family, such as Windows 10 and Windows 7. 如需詳細資訊,請參閱 tvm 支援的作業系統和平臺。See tvm supported operating systems and platforms for details. Windows10Windows10
RbacGroupNameRbacGroupName stringstring 以角色為基礎的存取控制 (RBAC) 群組。The role-based access control (RBAC) group. 如果此裝置並未指派給任何 RBAC 群組,此值將會是「未指派」。If this device is not assigned to any RBAC group, the value will be “Unassigned.” 如果組織不包含任何 RBAC 群組,則此值會是 "None"。If the organization doesn’t contain any RBAC groups, the value will be “None.” 伺服器Servers
RegistryPathsRegistryPaths 陣列 [字串]Array[string] 產品已安裝在裝置中的登錄證據。Registry evidence that the product is installed in the device. ["HKEY_LOCAL_MACHINE \軟體 \ WOW6432Node \ microsoft \ Windows \ CurrentVersion \ 卸載 \ microsoft Silverlight "][ "HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\Microsoft Silverlight" ]
SoftwareFirstSeenTimestampSoftwareFirstSeenTimestamp stringstring 此軟體第一次出現于此裝置上。The first time this software was seen on the device. 2019-04-07 02:06:472019-04-07 02:06:47
SoftwareNameSoftwareName stringstring 軟體產品的名稱。Name of the software product. SilverlightSilverlight
SoftwareVendorSoftwareVendor stringstring 軟體廠商的名稱。Name of the software vendor. 微軟microsoft
SoftwareVersionSoftwareVersion stringstring 軟體產品的版本號碼。Version number of the software product. 81.0.4044.13881.0.4044.138

1.6 範例1.6 Examples

1.6.1 要求範例1.6.1 Request example

GET https://api.securitycenter.microsoft.com/api/machines/SoftwareInventoryByMachine?pageSize=5  &sinceTime=2021-05-19T18%3A35%3A49.924Z 

1.6.2 回應範例1.6.2 Response example

{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#Collection(contoso.windowsDefenderATP.api.AssetSoftware)",
    "value": [
        {
            "deviceId": "00044f68765bbaf712342dbe6db733b6a9c59ab4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18993b45912eeb224b2be2f5ea3142726e63f16a.DomainPII_21eeb80d086e79dbfa178eadfa25e8de9acfa346.corp.contoso.com",
            "osPlatform": "Windows10",
            "softwareVendor": "microsoft",
            "softwareName": "windows_10",
            "softwareVersion": "10.0.17763.1637",
            "numberOfWeaknesses": 58,
            "diskPaths": [],
            "registryPaths": [],
            "softwareFirstSeenTimestamp": "2020-12-30 11:07:15",
            "endOfSupportStatus": "Upcoming EOS Version",
            "endOfSupportDate": "2021-05-11T00:00:00+00:00"
        },
        {
            "deviceId": "00044f68765bbaf712342dbe6db733b6a9c59ab4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18993b45912eeb224b2be2f5ea3142726e63f16a.DomainPII_21eeb80d086e79dbfa178eadfa25e8de9acfa346.corp.contoso.com",
            "osPlatform": "Windows10",
            "softwareVendor": "microsoft",
            "softwareName": ".net_framework",
            "softwareVersion": "4.0.0.0",
            "numberOfWeaknesses": 0,
            "diskPaths": [],
            "registryPaths": [
                "SOFTWARE\\Microsoft\\NET Framework Setup\\NDP\\v4.0\\Client\\Install"
            ],
            "softwareFirstSeenTimestamp": "2020-12-30 11:07:15",
            "endOfSupportStatus": "None",
            "endOfSupportDate": null
        },
        {
            "deviceId": "00044f68765bbaf712342dbe6db733b6a9c59ab4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18993b45912eeb224b2be2f5ea3142726e63f16a.DomainPII_21eed80d086e79bdfa178eadfa25e8de9acfa346.corp.contoso.com",
            "osPlatform": "Windows10",
            "softwareVendor": "microsoft",
            "softwareName": "system_center_2012_endpoint_protection",
            "softwareVersion": "4.7.214.0",
            "numberOfWeaknesses": 0,
            "diskPaths": [],
            "registryPaths": [
                "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\Microsoft Security Client"
            ],
            "softwareFirstSeenTimestamp": "2020-12-30 11:07:15",
            "endOfSupportStatus": "None",
            "endOfSupportDate": null
        },
        {
            "deviceId": "00044f68765ddaf71234bde6bd733d6a9c59ad4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18993b45912eeb224b2be2f5ea3142726e63f16a.DomainPII_21eeb80d086e79dbfa178aedfa25e8be9acfa346.corp.contoso.com",
            "osPlatform": "Windows10",
            "softwareVendor": "microsoft",
            "softwareName": "configuration_manager",
            "softwareVersion": "5.0.8634.1000",
            "numberOfWeaknesses": 0,
            "diskPaths": [],
            "registryPaths": [
                "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\{B7D3A842-E826-4542-B39B-1D883264B279}"
            ],
            "softwareFirstSeenTimestamp": "2020-12-30 11:07:15",
            "endOfSupportStatus": "None",
            "endOfSupportDate": null
        },
        {
            "deviceId": "00044f38765bbaf712342dbe6db733b6a9c59ab4",
            "rbacGroupName": "hhh",
            "deviceName": "ComputerPII_18993b45912eeb224b2de2f5ea3142726e63f16a.DomainPII_21eeb80d086e79bdfa178eadfa25e8be9acfa346.corp.contoso.com",
            "osPlatform": "Windows10",
            "softwareVendor": "microsoft",
            "softwareName": "system_center_2012_endpoint_protection",
            "softwareVersion": "4.10.209.0",
            "numberOfWeaknesses": 0,
            "diskPaths": [],
            "registryPaths": [
                "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall\\Microsoft Security Client"
            ],
            "softwareFirstSeenTimestamp": "2020-12-30 11:07:15",
            "endOfSupportStatus": "None",
            "endOfSupportDate": null
        }
    ],
    "@odata.nextLink": "https://api.securitycenter.microsoft.com/api/machines/SoftwareInventoryByMachine?pagesize=5&$skiptoken=eyJFeHBvcnREZWZpbml0aW9uIjp7IlRpbWVQYXRoIjoiMjAyMS0wMS0yNS8wMjAwLyJ9LCJFeHBvcnRGaWxlSW5kZXgiOjAsIkxpbmVTdG9wcGVkQXQiOjV9"
}

2. 透過檔案匯出軟體清查評估 () 2. Export software inventory assessment (via files)

2.1 API 方法描述2.1 API method description

此 API 回應包含每個裝置已安裝軟體的所有資料。This API response contains all the data of installed software per device. 會傳回資料表,其中包含 DeviceId、SoftwareVendor、SoftwareName、SoftwareVersion 的每個唯一組合的專案。Returns a table with an entry for every unique combination of DeviceId, SoftwareVendor, SoftwareName, SoftwareVersion.

2.1.1 限制2.1.1 Limitations

此 API 的速率限制是每分鐘5個通話,每小時20個通話。Rate limitations for this API are 5 calls per minute and 20 calls per hour.

2.2 許可權2.2 Permissions

需要有下列其中一個許可權才能呼叫此 API。One of the following permissions is required to call this API. 若要深入瞭解,包括如何選擇許可權,請參閱 使用 Microsoft Defender For Endpoint APIs 以取得詳細資訊。To learn more, including how to choose permissions, see Use Microsoft Defender for Endpoint APIs for details.

許可權類型Permission type 權限Permission 許可權顯示名稱Permission display name
應用程式Application 已讀取軟體。所有Software.Read.All '讀取威脅及弱點管理弱點資訊''Read Threat and Vulnerability Management vulnerability information'
委派 (工作或學校帳戶) Delegated (work or school account) 軟體. 讀取Software.Read '讀取威脅及弱點管理弱點資訊''Read Threat and Vulnerability Management vulnerability information'

2.3 URL2.3 URL

GET /api/machines/SoftwareInventoryExport

參數Parameters

  • sasValidHours –下載 URLs (最長24小時內的有效時數) sasValidHours – The number of hours that the download URLs will be valid for (Maximum 24 hours)

2.5 屬性2.5 Properties

注意

  • 這些檔案是以多行 Json 格式的 gzip 壓縮 &。The files are gzip compressed & in multiline Json format.

  • 下載 URLs 只會在3小時內有效。The download URLs are only valid for 3 hours. 否則您可以使用參數。Otherwise you can use the parameter.

_ 若要下載最大的資料下載速度,您可以確定從資料所在的相同 Azure 地區下載。_ For maximum download speed of your data, you can make sure you are downloading from the same Azure region that your data resides.

屬性 (識別碼) Property (ID) 資料類型Data type 描述Description 傳回值的範例Example of a returned value
匯出檔案Export files 陣列 [ 字串]array[string] 用於存放組織目前快照之檔案的下載 URLs 清單A list of download URLs for files holding the current snapshot of the organization [ Https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...1”, “https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...2” ][ Https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...1”, “https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...2” ]
GeneratedTimeGeneratedTime stringstring 產生匯出的時間。The time that the export was generated. 2021-05-20T08:00: 00Z]2021-05-20T08:00:00Z ]

2.6 範例2.6 Examples

2.6.1 要求範例2.6.1 Request example

GET https://api.securitycenter.microsoft.com/api/machines/SoftwareInventoryExport

2.6.2 回應範例2.6.2 Response example

{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#microsoft.windowsDefenderATP.api.ExportFilesResponse",
    "exportFiles": [
        "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export/2021-01-11/1101/SoftwareInventory/json/OrgId=12345678-195f-4223-9c7a-99fb420fd000/part-00393-e423630d-4c69-4490-8769-a4f5468c4f25.c000.json.gz?sv=2019-12-12&st=2021-01-11T11%3A55%3A51Z&se=2021-01-11T14%3A55%3A51Z&sr=b&sp=r&sig=...",
        "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export/2021-01-11/1101/SoftwareInventory/json/OrgId=12345678-195f-4223-9c7a-99fb420fd000/part-00394-e423630d-4c69-4490-8769-a4f5468c4f25.c000.json.gz?sv=2019-12-12&st=2021-01-11T11%3A55%3A51Z&se=2021-01-11T14%3A55%3A51Z&sr=b&sp=r&sig=...",
        "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export/2021-01-11/1101/SoftwareInventory/json/OrgId=12345678-195f-4223-9c7a-99fb420fd000/part-00394-e423630d-4c69-4490-8769-a4f5468c4f25.c001.json.gz?sv=2019-12-12&st=2021-01-11T11%3A55%3A51Z&se=2021-01-11T14%3A55%3A51Z&sr=b&sp=r&sig=..."
    ],
    "generatedTime": "2021-01-11T11:01:00Z"
}

另請參閱See also

其他相關Other related