デバイスごとのソフトウェアインベントリ評価のエクスポート

[アーティクル]
04/27/2024

適用対象:

Microsoft Defender ATP を試してみたいですか? 無料試用版にサインアップしてください。

この API は、 Common Platform Enum(CPE) を持つインストール済みソフトウェアのすべてのデータをデバイスごとに返します。

API 呼び出しによって、さまざまな種類のデータが取得されます。データの量は大きくなる可能性があるため、取得する方法は 2 つあります。

ソフトウェアインベントリ評価 JSON 応答をエクスポートするAPI は、organization内のすべてのデータを Json 応答としてプルします。この方法は、 100 K 未満のデバイスを持つ小規模な組織に最適です。応答はページ分割されるため、応答の@odata.nextLink フィールドを使用して、次の結果をフェッチできます。
ファイルを使用してソフトウェアインベントリ評価をエクスポートするこの API ソリューションを使用すると、大量のデータをより迅速かつ確実にプルできます。そのため、100 K を超えるデバイスを持つ大規模な組織におすすめです。この API は、組織内のすべてのデータをダウンロードファイルとしてプルします。応答には、Azure Storage からすべてのデータをダウンロードするための URL が含まれています。この API を使用すると、次のように Azure Storage からすべてのデータをダウンロードできます:
- すべての組織データを含むダウンロード URL の一覧を取得するには、API を呼び出します。
- ダウンロード URL を使用してすべてのファイルをダウンロードし、データを好きなように処理します。

収集されたデータ (Json 応答またはファイル経由) は、現在の状態の現在のスナップショットです。履歴データは含まれません。履歴データを収集するには、お客様が独自のデータストレージにデータを保存する必要があります。

注:

特に明記されていない限り、一覧表示されているすべてのエクスポート評価方法は 、完全なエクスポート と デバイス別 ( デバイス別とも呼ばれます) です。

1. ソフトウェアインベントリ評価のエクスポート (JSON 応答)

1.1 API メソッドの説明

この API 応答には、デバイスごとに Common Platform Enum(CPE)を持つインストール済みソフトウェアのすべてのデータが含まれています。 DeviceId、SoftwareVendor、SoftwareName、SoftwareVersion のすべての一意の組み合わせのエントリを持つテーブルを返します。

1.1.1 制限事項

最大ページサイズは 200,000 です。
この API のレート制限は、1 分あたり 30 呼び出しと 1 時間あたり 1000 呼び出しです。

1.2 アクセス許可

この API を呼び出すには、次のいずれかのアクセス許可が必要です。アクセス許可の選択方法など、詳細については、「Microsoft Defender for Endpoint API を使用する」を参照してください。

アクセス許可の種類	アクセス許可	アクセス許可の表示名
アプリケーション	Software.Read.All	'脅威と脆弱性管理ソフトウェア情報の読み取り'
委任 (職場または学校のアカウント)	Software.Read	'脅威と脆弱性管理ソフトウェア情報の読み取り'

1.3 URL

GET /api/machines/SoftwareInventoryByMachine

1.4 パラメーター

pageSize (既定値 = 50,000): 応答の結果の数。
$top: 返す結果の数 (返されない @odata.nextLink ので、すべてのデータをプルしない)

1.5 プロパティ

注:

各レコードのデータは約 0.5 KB です。正しい pageSize パラメーターを選択するときは、これを考慮する必要があります。
次のテーブルで定義されているプロパティは、プロパティ ID でアルファベット順にリスト表示されます。この API を実行する場合、結果の出力は必ずしもこのテーブルにリストされているのと同じ順序で返されるとは限りません。
応答で追加の列が返される場合があります。これらの列は一時的なものであり、削除される可能性があります。ドキュメント化された列のみを使用してください。

プロパティ (ID)	データ型	説明	戻り値の例
DeviceId	文字列	サービス内のデバイスの一意の識別子。	9eaf3a8b5962e0e6b1af9ec756664a9b823df2d1
DeviceName	string	デバイスの完全修飾ドメイン名 (FQDN)。	johnlaptop.europe.contoso.com
DiskPaths	Array[string]	デバイスに製品がインストールされていることを示すディスク証拠。	["C:\Program Files (x86)\Microsoft\Silverlight\Application\silverlight.exe"]
EndOfSupportDate	文字列	このソフトウェアのサポートが終了する日付。	2020-12-30
EndOfSupportStatus	string	サポート終了の状態。次の値を含めることができます:None、EOS バージョン、今後の EOS バージョン、EOS ソフトウェア、今後の EOS ソフトウェア。	今後の EOS
NumberOfWeaknesses	int	このデバイス上のこのソフトウェアの弱点の数	3
OSPlatform	文字列	デバイスで実行されているオペレーティングシステムのプラットフォーム。これらは、Windows 10やWindows 11など、同じファミリ内のバリエーションを持つ特定のオペレーティングシステムです。詳細については、「サポートされているオペレーティングシステムとプラットフォームMicrosoft Defender 脆弱性の管理」を参照してください。	Windows10 とWindows 11
RbacGroupName	文字列	ロールベースのアクセス制御 (RBAC) グループ。このデバイスが RBAC グループに割り当てられていない場合、値は "未割り当て" になります。organizationに RBAC グループが含まれていない場合、値は "None" になります。	サーバー
RegistryPaths	Array[string]	製品がデバイスにインストールされていることを示すレジストリの証拠。	["HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\Microsoft Silverlight"]
SoftwareFirstSeenTimestamp	string	このソフトウェアがデバイスで初めて見られた時。	2019-04-07 02:06:47
SoftwareName	string	ソフトウェア製品の名前。	Silverlight
SoftwareVendor	string	ソフトウェアベンダーの名前。	microsoft
SoftwareVersion	string	ソフトウェア製品のバージョン番号。	81.0.4044.138

1.6 例

1.6.1 要求の例

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

1.6.2 応答の例

{
    "@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" "Windows11",
            "softwareVendor": "microsoft",
            "softwareName": "windows_10" "Windows_11",
            "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" "Windows11",
            "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" "Windows11",
            "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" "Windows11",
            "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" "Windows11",
            "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"
}

注:

この API によって返される情報と、CPE を持たないソフトウェアについて、製品コード以外のソフトウェアインベントリ評価 API から返される情報により、organization全体にインストールされているソフトウェアとインストールされているデバイスが完全に可視化されます。

2. ソフトウェアインベントリ評価のエクスポート (ファイル経由)

2.1 API メソッドの説明

この API 応答には、デバイスごとにインストールされているソフトウェアのすべてのデータが含まれています。 DeviceId、SoftwareVendor、SoftwareName、SoftwareVersion のすべての一意の組み合わせのエントリを持つテーブルを返します。

2.1.1 制限事項

この API のレート制限は、1 分あたり 5 回の呼び出しと 1 時間あたり 20 回の呼び出しです。

2.2 権限

アクセス許可の種類	アクセス許可	アクセス許可の表示名
アプリケーション	Software.Read.All	'脅威と脆弱性管理ソフトウェア情報の読み取り'
委任 (職場または学校のアカウント)	Software.Read	'脅威と脆弱性管理ソフトウェア情報の読み取り'

2.3 URL

GET /api/machines/SoftwareInventoryExport

パラメーター

sasValidHours: ダウンロード URL が有効になる時間数 (最大 24 時間)

2.5 プロパティ

注:

ファイルは複数行の JSON 形式で gzip 圧縮 & されます。
ダウンロード URL は 3 時間のみ有効です。それ以外の場合は、パラメーターを使用できます。
データの最大ダウンロード速度を確保するために、データが存在するのと同じ Azure リージョンからダウンロードしていることを確認できます。

プロパティ (ID)	データ型	説明	戻り値の例
ファイルをエクスポートする	array[string]	organizationの現在のスナップショットを保持しているファイルのダウンロード URL の一覧	"[Https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...1", "https://tvmexportstrstgeus.blob.core.windows.net/tvm-export...2"]
GeneratedTime	文字列	エクスポートが生成された時刻。	2021-05-20T08:00:00Z

2.6 例

2.6.1 要求の例

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

2.6.2 応答の例

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

次の方法で共有

デバイスごとのソフトウェアインベントリ評価のエクスポート

1. ソフトウェアインベントリ評価のエクスポート (JSON 応答)

1.1 API メソッドの説明

1.1.1 制限事項

1.2 アクセス許可

1.3 URL

1.4 パラメーター

1.5 プロパティ

1.6 例

1.6.1 要求の例

1.6.2 応答の例

2. ソフトウェアインベントリ評価のエクスポート (ファイル経由)

2.1 API メソッドの説明

2.1.1 制限事項

2.2 権限

2.3 URL

パラメーター

2.5 プロパティ

2.6 例

2.6.1 要求の例

2.6.2 応答の例

関連項目

フィードバック

その他のリソース

次の方法で共有

デバイスごとのソフトウェア インベントリ評価のエクスポート

1. ソフトウェア インベントリ評価のエクスポート (JSON 応答)

1.1 API メソッドの説明

1.1.1 制限事項

1.2 アクセス許可

1.3 URL

1.4 パラメーター

1.5 プロパティ

1.6 例

1.6.1 要求の例

1.6.2 応答の例

2. ソフトウェア インベントリ評価のエクスポート (ファイル経由)

2.1 API メソッドの説明

2.1.1 制限事項

2.2 権限

2.3 URL

パラメーター

2.5 プロパティ

2.6 例

2.6.1 要求の例

2.6.2 応答の例

関連項目

フィードバック

その他のリソース

デバイスごとのソフトウェアインベントリ評価のエクスポート

1. ソフトウェアインベントリ評価のエクスポート (JSON 応答)

2. ソフトウェアインベントリ評価のエクスポート (ファイル経由)