디바이스당 소프트웨어 인벤토리 평가 내보내기
적용 대상:
- 엔드포인트용 Microsoft Defender 플랜 1
- 엔드포인트용 Microsoft Defender 플랜 2
- Microsoft Defender 취약성 관리
- Microsoft Defender XDR
엔드포인트용 Microsoft Defender를 경험하고 싶으신가요? 무료 평가판을 신청하세요.
이 API는 CPE(Common Platform Enumeration)가 있는 설치된 소프트웨어에 대한 모든 데이터를 디바이스별로 반환합니다.
다른 API 호출은 다양한 형식의 데이터를 가져옵니다. 데이터의 양이 클 수 있으므로 두 가지 방법으로 검색할 수 있습니다.
소프트웨어 인벤토리 평가 JSON 응답 내보내기 API는 organization 모든 데이터를 Json 응답으로 가져옵니다. 이 방법은 디바이스가 100K 미만인 소규모 조직에 가장 적합합니다. 응답의 페이지가 매겨지므로 응답의 @odata.nextLink 필드를 사용하여 다음 결과를 가져올 수 있습니다.
파일을 통해 소프트웨어 인벤토리 평가 내보내기 이 API 솔루션을 사용하면 더 많은 양의 데이터를 더 빠르고 안정적으로 끌어낼 수 있습니다. 따라서 100K 이상의 디바이스를 사용하는 대규모 조직에 권장됩니다. 이 API는 organization 모든 데이터를 다운로드 파일로 가져옵니다. 응답에는 Azure Storage에서 모든 데이터를 다운로드하는 URL이 포함되어 있습니다. 이 API를 사용하면 다음과 같이 Azure Storage에서 모든 데이터를 다운로드할 수 있습니다.
- API를 호출하여 모든 organization 데이터가 포함된 다운로드 URL 목록을 가져옵니다.
- 다운로드 URL을 사용하여 모든 파일을 다운로드하고 원하는 대로 데이터를 처리합니다.
Json 응답 또는 파일을 통해 수집되는 데이터는 현재 상태의 현재 스냅샷. 기록 데이터가 포함되지 않습니다. 기록 데이터를 수집하려면 고객은 데이터를 자체 데이터 스토리지에 저장해야 합니다.
참고
달리 명시되지 않는 한 나열된 모든 내보내기 평가 방법은 전체 내보내 기 및 디바이스 별( 디바이스별이라고도 함)입니다.
1. 소프트웨어 인벤토리 평가 내보내기(JSON 응답)
1.1 API 메서드 설명
이 API 응답에는 디바이스당 CPE(Common Platform Enumeration)가 있는 설치된 소프트웨어의 모든 데이터가 포함됩니다. DeviceId, SoftwareVendor, SoftwareName, SoftwareVersion의 모든 고유한 조합에 대한 항목이 있는 테이블을 반환합니다.
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/SoftwareInventoryByMachine
1.4 매개 변수
- pageSize(기본값 = 50,000): 응답 결과 수입니다.
- $top: 반환할 결과 수(반환 @odata.nextLink 되지 않으므로 모든 데이터를 끌어오지 않음)
1.5 속성
참고
- 각 레코드는 약 0.5KB의 데이터입니다. 올바른 pageSize 매개 변수를 선택할 때 이를 고려해야 합니다.
- 다음 표에 정의된 속성은 속성 ID별로 사전순으로 나열됩니다. 이 API를 실행할 때 결과 출력이 반드시 이 표에 나열된 순서대로 반환되지는 않습니다.
- 응답에 일부 추가 열이 반환될 수 있습니다. 이러한 열은 임시이며 제거될 수 있습니다. 문서화된 열만 사용하세요.
| 속성(ID) | 데이터 형식 | 설명 | 반환된 값의 예 |
|---|---|---|---|
| DeviceId | 문자열 | 서비스의 디바이스에 대한 고유 식별자입니다. | 9eaf3a8b5962e0e6b1af9ec756664a9b823df2d1 |
| 장치 이름 | 문자열 | 디바이스의 FQDN(정규화된 도메인 이름)입니다. | johnlaptop.europe.contoso.com |
| DiskPaths | Array[string] | 제품이 디바이스에 설치되었다는 디스크 증거입니다. | ["C:\Program Files (x86)\Microsoft\Silverlight\Application\silverlight.exe"] |
| EndOfSupportDate | 문자열 | 이 소프트웨어에 대한 지원이 종료되거나 종료되는 날짜입니다. | 2020-12-30 |
| EndOfSupportStatus | 문자열 | 지원 종료 상태. None, EOS 버전, 예정된 EOS 버전, EOS 소프트웨어, 예정된 EOS 소프트웨어 등의 가능한 값을 포함할 수 있습니다. | 예정된 EOS |
| NumberOfWeaknesses | int | 이 디바이스에서 이 소프트웨어의 약점 수 | 3 |
| OSPlatform | 문자열 | 디바이스에서 실행되는 운영 체제의 플랫폼입니다. 이러한 운영 체제는 Windows 10 및 Windows 11 같은 제품군 내에서 변형이 있는 특정 운영 체제입니다. 자세한 내용은 지원되는 운영 체제 및 플랫폼 Microsoft Defender 취약성 관리 참조하세요. | Windows10 및 Windows 11 |
| RbacGroupName | 문자열 | RBAC(역할 기반 액세스 제어) 그룹입니다. 이 디바이스가 RBAC 그룹에 할당되지 않은 경우 값은 "할당되지 않음"입니다. organization RBAC 그룹이 없는 경우 값은 "없음"입니다. | 서버 |
| RegistryPaths | Array[string] | 제품이 디바이스에 설치되었다는 레지스트리 증명 정보입니다. | ["HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\Microsoft Silverlight"] |
| SoftwareFirstSeenTimestamp | 문자열 | 이 소프트웨어가 디바이스에서 처음 보였습니다. | 2019-04-07 02:06:47 |
| SoftwareName | 문자열 | 소프트웨어 제품의 이름입니다. | Silverlight |
| SoftwareVendor | 문자열 | 소프트웨어 공급업체의 이름입니다. | Microsoft |
| SoftwareVersion | 문자열 | 소프트웨어 제품의 버전 번호입니다. | 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"
}
참고
CPE가 없는 소프트웨어의 경우 제품 코드가 아닌 소프트웨어 인벤토리 평가 API 내보내기에서 반환된 정보와 함께 이 API에서 반환한 정보를 통해 organization 설치된 소프트웨어 및 설치된 디바이스에 대한 전체적인 가시성을 제공합니다.
2. 소프트웨어 인벤토리 평가 내보내기(파일을 통해)
2.1 API 메서드 설명
이 API 응답에는 디바이스당 설치된 소프트웨어의 모든 데이터가 포함됩니다. DeviceId, SoftwareVendor, SoftwareName, SoftwareVersion의 모든 고유한 조합에 대한 항목이 있는 테이블을 반환합니다.
2.1.1 제한 사항
이 API에 대한 속도 제한은 분당 5개 호출 및 시간당 20개의 호출입니다.
2.2 사용 권한
이 API를 호출하려면 다음 권한 중 하나가 필요합니다. 사용 권한을 선택하는 방법을 포함하여 자세한 내용은 엔드포인트용 Microsoft Defender API 사용을 참조하세요.
| 사용 권한 유형 | 사용 권한 | 사용 권한 표시 이름 |
|---|---|---|
| 응용 프로그램 | Software.Read.All | '위협 및 취약성 관리 소프트웨어 정보 읽기' |
| 위임됨(회사 또는 학교 계정) | Software.Read | '위협 및 취약성 관리 소프트웨어 정보 읽기' |
2.3 URL
GET /api/machines/SoftwareInventoryExport
매개 변수
- sasValidHours: 다운로드 URL이 유효한 시간(최대 24시간)
2.5 속성
참고
- 파일은 gzip 압축 & 여러 줄 JSON 형식입니다.
- 다운로드 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"
}
참고 항목
기타 관련
팁
더 자세히 알아보고 싶으신가요? 기술 커뮤니티: 엔드포인트용 Microsoft Defender Tech Community의 Microsoft 보안 커뮤니티와 Engage.