디바이스당 하드웨어 및 펌웨어 평가 인벤토리 내보내기

아티클
04/26/2024

적용 대상:

Microsoft Defender 취약성 관리 경험하고 싶으신가요? Microsoft Defender 취약성 관리 공개 미리 보기 평가판에 등록하는 방법에 대해 자세히 알아보세요.

다양한 형식의 데이터를 가져오기 위한 다른 API 호출이 있습니다. 일반적으로 각 API 호출에는 organization 디바이스에 대한 필수 데이터가 포함됩니다.

JSON 응답 API는 organization 모든 데이터를 JSON 응답으로 가져옵니다. 이 방법은 디바이스가 100K 미만인 소규모 조직에 가장 적합합니다. 응답의 페이지가 매겨지므로 응답의 @odata.nextLink 필드를 사용하여 다음 결과를 가져올 수 있습니다.
파일을 통해 이 API 솔루션을 사용하면 더 많은 양의 데이터를 더 빠르고 안정적으로 끌어낼 수 있습니다. 따라서 100K 이상의 디바이스를 사용하는 대규모 조직에 권장됩니다. 이 API는 organization 모든 데이터를 다운로드 파일로 가져옵니다. 응답에는 Azure Storage에서 모든 데이터를 다운로드하는 URL이 포함되어 있습니다. 다음과 같이 Azure Storage에서 데이터를 다운로드할 수 있습니다.
- API를 호출하여 모든 organization 데이터가 포함된 다운로드 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 응답)

참고

각 레코드는 약 1KB의 데이터입니다. 올바른 pageSize 매개 변수를 선택할 때 이를 고려해야 합니다.

응답에 일부 추가 열이 반환될 수 있습니다. 이러한 열은 임시이며 제거될 수 있습니다. 문서화된 열만 사용합니다.

다음 표에 정의된 속성은 속성 ID에 따라 사전순으로 나열됩니다. 이 API를 실행할 때 결과 출력이 반드시 이 표에 나열된 순서대로 반환되지는 않습니다.

속성(ID)	데이터 형식	설명
deviceId	String	서비스의 디바이스에 대한 고유 식별자입니다.
rbacGroupId	임계값	RBAC(역할 기반 액세스 제어) 그룹 ID입니다. 디바이스가 RBAC 그룹에 할당되지 않은 경우 값은 "할당되지 않음"입니다. organization RBAC 그룹이 없는 경우 값은 "없음"입니다.
rbacGroupName	String	RBAC(역할 기반 액세스 제어) 그룹입니다. 디바이스가 RBAC 그룹에 할당되지 않은 경우 값은 "할당되지 않음"입니다. organization RBAC 그룹이 없는 경우 값은 "없음"입니다.
Devicename	String	디바이스의 FQDN(정규화된 도메인 이름)입니다.
componentType	String	하드웨어 또는 펌웨어 구성 요소의 유형입니다.
제조업체	String	특정 하드웨어 또는 펌웨어 구성 요소의 제조업체입니다.
componentName	String	특정 하드웨어 또는 펌웨어 구성 요소의 이름입니다.
componentVersion	String	특정 하드웨어 또는 펌웨어 구성 요소의 버전입니다.
additionalFields	String	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 사용 권한

사용 권한 유형	사용 권한	사용 권한 표시 이름
응용 프로그램	Software.Read.All	'위협 및 취약성 관리 소프트웨어 정보 읽기'
위임됨(회사 또는 학교 계정)	Software.Read	'위협 및 취약성 관리 소프트웨어 정보 읽기'

2.3 URL

GET /api/machines/HardwareFirmwareInventoryExport

2.4 매개 변수

sasValidHours: 다운로드 URL이 유효한 시간(최대 24시간)입니다.

2.5 속성(JSON 응답)

참고

파일은 gzip 압축 & 여러 줄 Json 형식입니다.

다운로드 URL은 3시간 동안만 유효합니다. 그렇지 않으면 매개 변수를 사용할 수 있습니다.

다운로드 속도를 최대화하려면 데이터가 있는 동일한 Azure 지역에서 데이터를 다운로드하고 있는지 확인합니다.

각 레코드는 약 1KB의 데이터입니다. 적합한 pageSize 매개 변수를 선택할 때 이를 고려해야 합니다.