Windows 기능 업데이트에 대한 프로그래밍 방식 컨트롤

적용 대상: ✅ Windows 11, ✅ Windows 10

Windows Autopatch 프로그래밍 방식 컨트롤은 Microsoft Graph API 통해 소프트웨어 업데이트를 승인하고 예약하는 데 사용됩니다. Graph SDK를 통해 API를 직접 호출하거나 Microsoft Intune 같은 관리 도구와 통합할 수 있습니다.

이 문서에서는 Graph Explorer 사용하여 클라이언트에 기능 업데이트를 배포하는 전체 프로세스를 안내합니다. 이 문서에서는 다음을 수행합니다.

이 문서에서는 다음을 수행합니다.

그래프 Explorer 열기
쿼리를 실행하여 디바이스 식별
장치 등록
기능 업데이트에 대한 카탈로그 항목 나열
배포 만들기
배포 대상 그룹에 멤버 추가
배포 일시 중지
배포 삭제
디바이스 등록 취소

필수 구성 요소

모든 Windows 자동 패치 필수 구성 요소를 충족해야 합니다.

사용 권한

이 문서에 나열된 쿼리에는 다음 권한이 필요합니다.

Windows 자동 패치 작업에 대한 WindowsUpdates.ReadWrite.All입니다.
디바이스 정보를 표시할 수 있는 Device.Read.All 권한 이상

Windows 업데이트 배포 관리자와 같은 일부 역할에는 이미 이러한 권한이 있습니다.

필수 엔드포인트

다음 엔드포인트에 액세스할 수 있어야 합니다.

엔드포인트 Windows 업데이트

*.prod.do.dsp.mp.microsoft.com
*.windowsupdate.com
*.dl.delivery.mp.microsoft.com
*.update.microsoft.com
*.delivery.mp.microsoft.com
tsfe.trafficshaping.dsp.mp.microsoft.com

Graph API 엔드포인트:

devicelistenerprod.microsoft.com
login.windows.net
payloadprod*.blob.core.windows.net

그래프 Explorer 열기

이 문서에서는 Graph Explorer 사용하여 Microsoft Graph API를 요청하여 데이터를 검색, 추가, 삭제 및 업데이트합니다. 그래프 Explorer Microsoft Graph API에 대해 알아볼 수 있는 개발자 도구입니다. Graph Explorer 사용에 대한 자세한 내용은 Graph Explorer 시작을 참조하세요.

Warning

이 문서에 나열된 요청에는 Microsoft 365 계정으로 로그인해야 합니다. 필요한 경우 Microsoft 365 Business Premium 무료 1개월 평가판을 사용할 수 있습니다.
테스트 테넌트 를 사용하여 배포 프로세스를 학습하고 확인하는 것이 좋습니다. 그래프 Explorer 학습 도구로 사용할 수 있습니다. 계속하기 전에 Graph Explorer 동의 및 동의 유형을 부여하는 것을 이해해야 합니다.

브라우저에서 Graph Explorer 이동하여 Microsoft Entra 사용자 계정을 사용하여 로그인합니다.
이 문서의 쿼리를 WindowsUpdates.ReadWrite.All 사용하려면 사용 권한을 사용하도록 설정해야 할 수 있습니다. 사용 권한을 사용하려면 다음을 수행합니다.
1. Graph Explorer 권한 수정 탭을 선택합니다.
2. 사용 권한 대화 상자에서 WindowsUpdates.ReadWrite.All 권한을 선택한 다음 동의를 선택합니다. 동의를 부여하려면 다시 로그인해야 할 수 있습니다.
요청을 수행하려면 다음을 수행합니다.
1. HTTP 메서드의 드롭다운 목록에서 GET, POST, PUT, PATCH 또는 DELETE를 선택합니다.
2. URL 필드에 요청을 입력합니다. 버전은 URL에 따라 자동으로 채워집니다.
3. 요청 본문을 수정해야 하는 경우 요청 본문 탭을 편집합니다.
4. 쿼리 실행 단추를 선택합니다. 결과는 응답 창에 표시됩니다.
팁

Microsoft Graph 설명서를 검토할 때 일반적으로 예제 요청이 을 나열content-type: application/json하는 것을 볼 수 있습니다. content-type 일반적으로 Graph Explorer 지정하는 것은 필요하지 않지만 헤더 탭을 선택하고 요청 헤더 필드에 를 키 및 application/json 값으로 추가하여 content-type 요청에 추가할 수 있습니다.

쿼리를 실행하여 디바이스 식별

디바이스 리소스 유형을 사용하여 Windows Autopatch에 등록할 클라이언트를 찾습니다. 특정 요구 사항에 맞게 쿼리 매개 변수를 변경합니다. 자세한 내용은 쿼리 매개 변수 사용을 참조하세요.

모든 디바이스의 AzureAD 디바이스 ID 및 이름을 표시합니다.

GET https://graph.microsoft.com/v1.0/devices?$select=deviceid,displayName

이름이 로 시작하는 Test디바이스의AzureAD 디바이스 ID 및 이름을 표시합니다.

GET https://graph.microsoft.com/v1.0/devices?$filter=startswith(displayName,'Test')&$select=deviceid,displayName

고급 쿼리에 대한 요청 헤더 추가

다음 요청의 경우 ConsistencyLevel 헤더를 로 eventual설정합니다. 고급 쿼리 매개 변수에 대한 자세한 내용은 Microsoft Entra 디렉터리 개체의 고급 쿼리 기능을 참조하세요.

그래프 Explorer 헤더 요청 탭을 선택합니다.
및 의 키 형식에 ConsistencyLevel값에 를 입력합니다eventual.
추가 단추를 선택합니다. 완료되면 휴지통 아이콘을 선택하여 요청 헤더를 제거합니다.

AzureAD 디바이스 ID로 있는 01234567-89ab-cdef-0123-456789abcdef 디바이스의 이름 및 운영 체제 버전을 표시합니다.

GET https://graph.microsoft.com/v1.0/devices?$search="deviceid:01234567-89ab-cdef-0123-456789abcdef"&$select=displayName,operatingSystemVersion

가상 머신이 아닌 디바이스를 찾으려면 가상 머신이 모델로 나열되지 않았지만 제조업체가 나열된 디바이스를 필터링합니다. 각 디바이스에 대한 AzureAD 디바이스 ID, 이름 및 운영 체제 버전을 표시합니다.
```
GET https://graph.microsoft.com/v1.0/devices?$filter=model ne 'virtual machine' and NOT(manufacturer eq null)&$count=true&$select=deviceid,displayName,operatingSystemVersion
```

팁

디바이스 리소스 유형을 사용하는 요청은 일반적으로 및 를 id 모두 갖습니다deviceid.

는 deviceidMicrosoft Entra 디바이스 ID이며 이 문서에서 사용됩니다.
- 이 문서의 deviceid 뒷부분에서는 배포 대상 그룹에 디바이스 추가와 같은 특정 요청을 수행할 때 으로 id 사용됩니다.
id 디바이스 리소스 유형의 은 일반적으로 이 문서에서 사용되지 않는 Microsoft Entra 개체 ID입니다.

장치 등록

디바이스를 기능 업데이트 관리에 등록하면 Windows 자동 패치가 Windows 업데이트 제공되는 기능 업데이트의 권한이 됩니다. Windows 자동 패치를 통해 디바이스가 기능 업데이트 관리에 등록된 상태로 유지되는 한, Windows Autopatch를 사용하여 명시적으로 배포하지 않는 한 디바이스는 Windows 업데이트 다른 기능 업데이트를 받지 않습니다. 업데이트가 아직 수신되지 않은 경우 디바이스에 지정된 기능 업데이트가 제공됩니다. 예를 들어 기능 업데이트 관리에 등록되어 있고 현재 이전 버전의 Windows 11 있는 디바이스에 Windows 11 기능 업데이트 버전 22H2를 배포하면 디바이스가 버전 22H2로 업데이트됩니다. 디바이스가 이미 버전 22H2 이상을 실행 중인 경우 현재 버전에 유지됩니다.

팁

비즈니스용 Windows 업데이트 보고서에는 디바이스의 현재 운영 체제 버전을 표시하는 통합 문서가 있습니다. 통합 문서에서 기능 업데이트 탭으로 이동하고 서비스 내 기능 업데이트 타일에서세부 정보 보기 링크를 선택하여 세부 정보 플라이아웃을 엽니다. 배포 대상 그룹을 만들 때 도움이 되도록 디바이스의 OS 버전 및 Microsoft Entra ID 쉽게 .csv 파일로 내보내거나 Azure Monitor 로그에서 열 수 있습니다.

수신하려는 업데이트 유형에 따라 디바이스를 등록합니다. 현재 디바이스를 등록하여 기능 업데이트() 또는 드라이버(featuredriver)를 받을 수 있습니다. 디바이스를 등록하여 여러 업데이트 분류에서 업데이트를 받을 수 있습니다.

디바이스를 등록하려면 enrollAssets를 사용하여 updatableAssets에 POST합니다. 다음 예제에서는 드라이버 업데이트를 받을 세 개의 디바이스를 등록합니다.
1. 그래프 Explorer HTTP 동사의 드롭다운 목록에서 POST를 선택합니다.
2. URL 필드에 다음 요청을 입력합니다.
  https://graph.microsoft.com/beta/admin/windows/updates/updatableAssets/enrollAssets
3. 요청 본문 탭에서 다음 정보를 제공하는 다음 JSON을 입력합니다.
  - 디바이스 ID를 로 Microsoft Entraid
  - feature updateCategory에 대한 또는 driver
```
{
  "updateCategory": "driver",
  "assets": [
    {
      "@odata.type": "#microsoft.graph.windowsUpdates.azureADDevice",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    {
      "@odata.type": "#microsoft.graph.windowsUpdates.azureADDevice",
      "id": "01234567-89ab-cdef-0123-456789abcde0"
    },
    {
      "@odata.type": "#microsoft.graph.windowsUpdates.azureADDevice",
      "id": "01234567-89ab-cdef-0123-456789abcde1"
    }
  ]
}
```
4. 쿼리 실행 단추를 선택합니다. 결과는 응답 창에 표시됩니다. 이 경우 HTTP는 의 202 Accepted코드를 상태.

기능 업데이트에 대한 카탈로그 항목 나열

각 기능 업데이트는 고유한 카탈로그 항목과 연결됩니다. 반환된 는 id카탈로그 ID 이며 배포를 만드는 데 사용됩니다. 기능 업데이트는 지원 사용 중지 날짜에 도달할 때까지 배포할 수 있습니다. 자세한 내용은 Windows 10 및 Windows 11 Enterprise 및 Education 버전에 대한 지원 수명 주기 날짜를 참조 하세요. 다음 쿼리는 배포 가능한 모든 기능 업데이트 카탈로그 항목을 나열합니다.

GET https://graph.microsoft.com/beta/admin/windows/updates/catalog/entries?$filter=isof('microsoft.graph.windowsUpdates.featureUpdateCatalogEntry')

다음 잘린 응답은 Windows 11 버전 22H2 기능 업데이트의 카탈로그 IDd9049ddb-0ca8-4bc1-bd3c-41a456ef300f 를 표시합니다.

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/catalog/entries",
    "value": [
        {
            "@odata.type": "#microsoft.graph.windowsUpdates.featureUpdateCatalogEntry",
            "id": "d9049ddb-0ca8-4bc1-bd3c-41a456ef300f",
            "displayName": "Windows 11, version 22H2",
            "deployableUntilDateTime": "2025-10-14T00:00:00Z",
            "releaseDateTime": "2022-09-20T00:00:00Z",
            "version": "Windows 11, version 22H2",
            "buildNumber": "22621"
        }
    ]
}

배포 만들기

기능 업데이트에 대한 배포를 만들 때 배포가 작동하는 방식을 정의하는 데 사용할 수 있는 여러 옵션이 있습니다. 배포 및 모니터링 설정은 선택 사항입니다. 다음 배포 설정은 Windows 11 버전 22H2 기능 업데이트(의 카탈로그 ID)를 배포하기 위한 예제 요청 본문에 d9049ddb-0ca8-4bc1-bd3c-41a456ef300f정의되어 있습니다.

배포 시작 날짜 : 2023년 2월 14일 오전 5시 UTC
3일마다 100대의 디바이스 속도로 점진적 출시
5개의 디바이스가 기능 업데이트를 롤백하는 경우 배포를 일시 중지하는 모니터링 규칙
배포의 디바이스에 적용 가능한 모든 보호 장치를 적용하는 기본 보호 보류 동작
- 보호 보류가 명시적으로 정의되지 않은 경우 기본 보호 보류 동작이 자동으로 적용됩니다.

POST https://graph.microsoft.com/beta/admin/windows/updates/deployments
content-type: application/json

{
    "content": {
        "@odata.type": "#microsoft.graph.windowsUpdates.catalogContent",
        "catalogEntry": {
            "@odata.type": "#microsoft.graph.windowsUpdates.featureUpdateCatalogEntry",
            "id": "d9049ddb-0ca8-4bc1-bd3c-41a456ef300f"
        }
    },
    "settings": {
        "@odata.type": "microsoft.graph.windowsUpdates.deploymentSettings",
        "schedule": {
            "startDateTime": "2023-02-14T05:00:00Z",
            "gradualRollout": {
                "@odata.type": "#microsoft.graph.windowsUpdates.rateDrivenRolloutSettings",
                "durationBetweenOffers": "P3D",
                "devicesPerOffer": "100"
            }
        },
        "monitoring": {
            "monitoringRules": [
                {
                    "signal": "rollback",
                    "threshold": 5,
                    "action": "pauseDeployment"
                }
            ]
        }
    }
}

응답 본문에는 다음이 포함됩니다.

예제의 새 배포 IDde910e12-3456-7890-abcd-ef1234567890
예제의 새 대상 그룹 IDd39ad1ce-0123-4567-89ab-cdef01234567

배포 요청 본문에 정의된 모든 설정

{
     "@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/deployments/$entity",
     "id": "de910e12-3456-7890-abcd-ef1234567890",
     "createdDateTime": "2023-02-07T19:21:15.425905Z",
     "lastModifiedDateTime": "2023-02-07T19:21:15Z",
     "state": {
         "effectiveValue": "scheduled",
         "requestedValue": "none",
         "reasons": []
     },
     "content": {
         "@odata.type": "#microsoft.graph.windowsUpdates.catalogContent",
         "catalogEntry@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/deployments('de910e12-3456-7890-abcd-ef1234567890')/content/microsoft.graph.windowsUpdates.catalogContent/catalogEntry/$entity",
         "catalogEntry": {
             "@odata.type": "#microsoft.graph.windowsUpdates.featureUpdateCatalogEntry",
             "id": "d9049ddb-0ca8-4bc1-bd3c-41a456ef300f",
             "displayName": "Windows 11, version 22H2",
             "deployableUntilDateTime": "2025-10-14T00:00:00Z",
             "releaseDateTime": "0001-01-01T00:00:00Z",
             "version": "Windows 11, version 22H2"
         }
     },
     "settings": {
         "contentApplicability": null,
         "userExperience": null,
         "expedite": null,
         "schedule": {
             "startDateTime": "2023-02-14T05:00:00Z",
             "gradualRollout": {
                 "@odata.type": "#microsoft.graph.windowsUpdates.rateDrivenRolloutSettings",
                 "durationBetweenOffers": "P3D",
                 "devicesPerOffer": 100
             }
         },
         "monitoring": {
             "monitoringRules": [
                 {
                     "signal": "rollback",
                     "threshold": 5,
                     "action": "pauseDeployment"
                 }
             ]
         }
     },
     "audience@odata.context": "https://graph.microsoft.com/beta/$metadata#admin/windows/updates/deployments('de910e12-3456-7890-abcd-ef1234567890')/audience/$entity",
     "audience": {
         "id": "d39ad1ce-0123-4567-89ab-cdef01234567",
         "applicableContent": []
     }
}

배포 편집

배포를 업데이트하려면 배포 ID로 배포 리소스를 패치하고 요청 본문에 업데이트된 설정을 제공합니다. 다음 예제에서는 배포를 만들 때 정의된 기존 점진적 롤아웃 설정을 유지하지만 배포 시작 날짜를 2023년 2월 28일 오전 5시 UTC로 변경합니다.

PATCH https://graph.microsoft.com/beta/admin/windows/updates/deployments/de910e12-3456-7890-abcd-ef1234567890
content-type: application/json

{
    "settings": {
        "@odata.type": "microsoft.graph.windowsUpdates.deploymentSettings",
        "schedule": {
            "startDateTime": "2023-02-28T05:00:00Z",
            "gradualRollout": {
                "@odata.type": "#microsoft.graph.windowsUpdates.rateDrivenRolloutSettings",
                "durationBetweenOffers": "P3D",
                "devicesPerOffer": "100"
            }
        }
    }
}

배포 IDde910e12-3456-7890-abcd-ef1234567890가 인 배포에 대한 배포 설정을 확인합니다.

GET https://graph.microsoft.com/beta/admin/windows/updates/deployments/de910e12-3456-7890-abcd-ef1234567890

배포 대상 그룹에 멤버 추가

대상 그룹 ID는 d39ad1ce-0123-4567-89ab-cdef01234567배포를 만들 때 만들어졌습니다. 대상 그룹 ID는 배포 대상 그룹에 멤버를 추가하는 데 사용됩니다. 배포 대상 그룹을 업데이트한 후 Windows 업데이트 배포 설정에 따라 디바이스에 업데이트를 제공하기 시작합니다. 배포가 존재하고 디바이스가 대상 그룹에 있는 한 업데이트가 제공됩니다.

다음 예제에서는 각 디바이스에 대한 Microsoft Entra ID 사용하여 배포 대상 그룹에 세 개의 디바이스를 추가합니다.

POST https://graph.microsoft.com/beta/admin/windows/updates/deploymentAudiences/d39ad1ce-0123-4567-89ab-cdef01234567/updateAudience
content-type: application/json

{
  "addMembers": [
    {
      "@odata.type": "#microsoft.graph.windowsUpdates.azureADDevice",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    {
      "@odata.type": "#microsoft.graph.windowsUpdates.azureADDevice",
      "id": "01234567-89ab-cdef-0123-456789abcde0"
    },
    {
      "@odata.type": "#microsoft.graph.windowsUpdates.azureADDevice",
     "id": "01234567-89ab-cdef-0123-456789abcde1"
    }
  ]
}

디바이스가 대상 그룹에 추가되었는지 확인하려면 의 대상 그룹 IDd39ad1ce-0123-4567-89ab-cdef01234567를 사용하여 다음 쿼리를 실행합니다.

GET https://graph.microsoft.com/beta/admin/windows/updates/deploymentAudiences/d39ad1ce-0123-4567-89ab-cdef01234567/members

배포 일시 중지

배포를 일시 중지하려면 deploymentState에 대한 의 paused 배포 requestedValue 를 패치합니다. 배포를 다시 시작하려면 값을 none 사용하고 상태가 로 업데이트 offeringscheduled 되거나 배포가 아직 시작 날짜에 도달하지 않은 경우 입니다.

다음 예제에서는 배포 IDde910e12-3456-7890-abcd-ef1234567890가 인 배포를 일시 중지합니다.


PATCH https://graph.microsoft.com/beta/admin/windows/updates/deployments/de910e12-3456-7890-abcd-ef1234567890
content-type: application/json

{
  "@odata.type": "#microsoft.graph.windowsUpdates.deployment",
  "state": {
    "@odata.type": "microsoft.graph.windowsUpdates.deploymentState",
    "requestedValue": "paused"
  }
}

배포 삭제

배포를 완전히 제거하려면 배포를 삭제합니다. 배포를 삭제하면 아직 콘텐츠를 받지 못한 경우 디바이스에 콘텐츠가 제공되지 않습니다. 콘텐츠 제공을 다시 시작하려면 새 승인을 만들어야 합니다.

다음 예제에서는 배포 ID가 인 배포 를 삭제합니다 de910e12-3456-7890-abcd-ef1234567890.

DELETE https://graph.microsoft.com/beta/admin/windows/updates/deployments/de910e12-3456-7890-abcd-ef1234567890

디바이스 등록 취소

디바이스에 더 이상 관리가 필요하지 않은 경우 Windows Autopatch에서 등록을 취소합니다. 디바이스를 등록하는 것과 마찬가지로 또는 feature 를 에 대한 값으로 지정 driver 합니다updateCategory. 디바이스는 지정된 업데이트 범주에 대한 Windows Autopatch에서 더 이상 업데이트를 받지 않습니다. 디바이스의 구성에 따라 Windows 업데이트 업데이트를 받기 시작할 수 있습니다. instance 경우 디바이스가 여전히 기능 업데이트에 등록되어 있지만 드라이버에서 등록되지 않은 경우:

서비스의 기존 드라이버 배포는 디바이스에 제공되지 않습니다.
디바이스는 Windows 자동 패치에서 기능 업데이트를 계속 받습니다.
디바이스의 구성에 따라 드라이버가 Windows 업데이트 설치되기 시작할 수 있습니다.

디바이스 등록을 취소하려면 unenrollAssets를 사용하여 updatableAssets에 POST합니다. 요청 본문에서 다음을 지정합니다.

디바이스에 대한 id디바이스 ID Microsoft Entra
feature updateCategory에 대한 또는 driver

다음 예제에서는 및 두 디바이스에 대한 등록을 01234567-89ab-cdef-0123-456789abcdef01234567-89ab-cdef-0123-456789abcde0제거 driver 합니다.

POST https://graph.microsoft.com/beta/admin/windows/updates/updatableAssets/unenrollAssets
content-type: application/json

{
  "updateCategory": "driver",
  "assets": [
    {
      "@odata.type": "#microsoft.graph.windowsUpdates.azureADDevice",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    },
    {
      "@odata.type": "#microsoft.graph.windowsUpdates.azureADDevice",
      "id": "01234567-89ab-cdef-0123-456789abcde0"
    }
  ]
}

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-03-31