Virtual Machines - Install Patches

Installs patches on the VM.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}/installPatches?api-version=2022-08-01

URI Parameters

Name In Required Type Description
resourceGroupName
path True
  • string

The name of the resource group.

subscriptionId
path True
  • string

Subscription credentials which uniquely identify Microsoft Azure subscription. The subscription ID forms part of the URI for every service call.

vmName
path True
  • string

The name of the virtual machine.

api-version
query True
  • string

Client Api Version.

Request Body

Name Required Type Description
rebootSetting True

Defines when it is acceptable to reboot a VM during a software update operation.

linuxParameters

Input for InstallPatches on a Linux VM, as directly received by the API

maximumDuration
  • string

Specifies the maximum amount of time that the operation will run. It must be an ISO 8601-compliant duration string such as PT4H (4 hours)

windowsParameters

Input for InstallPatches on a Windows VM, as directly received by the API

Responses

Name Type Description
200 OK

OK

202 Accepted

Accepted

Other Status Codes

Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

Install patch state of a virtual machine.

Sample Request

POST https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/myResourceGroupName/providers/Microsoft.Compute/virtualMachines/myVMName/installPatches?api-version=2022-08-01

{
  "maximumDuration": "PT4H",
  "rebootSetting": "IfRequired",
  "windowsParameters": {
    "classificationsToInclude": [
      "Critical",
      "Security"
    ],
    "maxPatchPublishDate": "2020-11-19T02:36:43.0539904+00:00"
  }
}

Sample Response

{
  "status": "Succeeded",
  "installationActivityId": "68f8b292-dfc2-4646-9781-33cc88631968",
  "rebootStatus": "Completed",
  "maintenanceWindowExceeded": false,
  "excludedPatchCount": 0,
  "notSelectedPatchCount": 0,
  "pendingPatchCount": 2,
  "installedPatchCount": 3,
  "failedPatchCount": 0,
  "startDateTime": "2020-04-24T21:02:04.2556154Z",
  "patches": [
    {
      "patchId": "35428702-5784-4ba4-a6e0-5222258b5411",
      "name": "Definition Update for Windows Defender Antivirus - KB2267602 (Definition 1.279.1373.0)",
      "version": "",
      "kbId": "2267602",
      "classifications": [
        "Definition Updates"
      ],
      "installationState": "Installed"
    },
    {
      "patchId": "39f9cdd1-795c-4d0e-8c0a-73ab3f31746d",
      "name": "Windows Malicious Software Removal Tool x64 - October 2018 (KB890830)",
      "version": "",
      "kbId": "890830",
      "classifications": [
        "Update Rollups"
      ],
      "installationState": "Pending"
    }
  ],
  "error": null
}

Definitions

ApiError

Api error.

ApiErrorBase

Api error base.

CloudError

An error response from the Compute service.

InnerError

Inner error details.

LinuxParameters

Input for InstallPatches on a Linux VM, as directly received by the API

PatchInstallationDetail

Information about a specific patch that was encountered during an installation action.

PatchInstallationState

The state of the patch after the installation operation completed.

PatchOperationStatus

The overall success or failure status of the operation. It remains "InProgress" until the operation completes. At that point it will become "Unknown", "Failed", "Succeeded", or "CompletedWithWarnings."

VirtualMachineInstallPatchesParameters

Input for InstallPatches as directly received by the API

VirtualMachineInstallPatchesResult

The result summary of an installation operation.

VMGuestPatchRebootSetting

Defines when it is acceptable to reboot a VM during a software update operation.

VMGuestPatchRebootStatus

The reboot state of the VM following completion of the operation.

WindowsParameters

Input for InstallPatches on a Windows VM, as directly received by the API

ApiError

Api error.

Name Type Description
code
  • string

The error code.

details

The Api error details

innererror

The Api inner error

message
  • string

The error message.

target
  • string

The target of the particular error.

ApiErrorBase

Api error base.

Name Type Description
code
  • string

The error code.

message
  • string

The error message.

target
  • string

The target of the particular error.

CloudError

An error response from the Compute service.

Name Type Description
error

Api error.

InnerError

Inner error details.

Name Type Description
errordetail
  • string

The internal error message or exception dump.

exceptiontype
  • string

The exception type.

LinuxParameters

Input for InstallPatches on a Linux VM, as directly received by the API

Name Type Description
classificationsToInclude
  • string[]

The update classifications to select when installing patches for Linux.

maintenanceRunId
  • string

This is used as a maintenance run identifier for Auto VM Guest Patching in Linux.

packageNameMasksToExclude
  • string[]

packages to exclude in the patch operation. Format: packageName_packageVersion

packageNameMasksToInclude
  • string[]

packages to include in the patch operation. Format: packageName_packageVersion

PatchInstallationDetail

Information about a specific patch that was encountered during an installation action.

Name Type Description
classifications
  • string[]

The classification(s) of the patch as provided by the patch publisher.

installationState

The state of the patch after the installation operation completed.

kbId
  • string

The KBID of the patch. Only applies to Windows patches.

name
  • string

The friendly name of the patch.

patchId
  • string

A unique identifier for the patch.

version
  • string

The version string of the package. It may conform to Semantic Versioning. Only applies to Linux.

PatchInstallationState

The state of the patch after the installation operation completed.

Name Type Description
Excluded
  • string
Failed
  • string
Installed
  • string
NotSelected
  • string
Pending
  • string
Unknown
  • string

PatchOperationStatus

The overall success or failure status of the operation. It remains "InProgress" until the operation completes. At that point it will become "Unknown", "Failed", "Succeeded", or "CompletedWithWarnings."

Name Type Description
CompletedWithWarnings
  • string
Failed
  • string
InProgress
  • string
Succeeded
  • string
Unknown
  • string

VirtualMachineInstallPatchesParameters

Input for InstallPatches as directly received by the API

Name Type Description
linuxParameters

Input for InstallPatches on a Linux VM, as directly received by the API

maximumDuration
  • string

Specifies the maximum amount of time that the operation will run. It must be an ISO 8601-compliant duration string such as PT4H (4 hours)

rebootSetting

Defines when it is acceptable to reboot a VM during a software update operation.

windowsParameters

Input for InstallPatches on a Windows VM, as directly received by the API

VirtualMachineInstallPatchesResult

The result summary of an installation operation.

Name Type Description
error

The errors that were encountered during execution of the operation. The details array contains the list of them.

excludedPatchCount
  • integer

The number of patches that were not installed due to the user blocking their installation.

failedPatchCount
  • integer

The number of patches that could not be installed due to some issue. See errors for details.

installationActivityId
  • string

The activity ID of the operation that produced this result. It is used to correlate across CRP and extension logs.

installedPatchCount
  • integer

The number of patches successfully installed.

maintenanceWindowExceeded
  • boolean

Whether the operation ran out of time before it completed all its intended actions.

notSelectedPatchCount
  • integer

The number of patches that were detected as available for install, but did not meet the operation's criteria.

patches

The patches that were installed during the operation.

pendingPatchCount
  • integer

The number of patches that were identified as meeting the installation criteria, but were not able to be installed. Typically this happens when maintenanceWindowExceeded == true.

rebootStatus

The reboot state of the VM following completion of the operation.

startDateTime
  • string

The UTC timestamp when the operation began.

status

The overall success or failure status of the operation. It remains "InProgress" until the operation completes. At that point it will become "Failed", "Succeeded", "Unknown" or "CompletedWithWarnings."

VMGuestPatchRebootSetting

Defines when it is acceptable to reboot a VM during a software update operation.

Name Type Description
Always
  • string
IfRequired
  • string
Never
  • string

VMGuestPatchRebootStatus

The reboot state of the VM following completion of the operation.

Name Type Description
Completed
  • string
Failed
  • string
NotNeeded
  • string
Required
  • string
Started
  • string
Unknown
  • string

WindowsParameters

Input for InstallPatches on a Windows VM, as directly received by the API

Name Type Description
classificationsToInclude
  • string[]

The update classifications to select when installing patches for Windows.

excludeKbsRequiringReboot
  • boolean

Filters out Kbs that don't have an InstallationRebootBehavior of 'NeverReboots' when this is set to true.

kbNumbersToExclude
  • string[]

Kbs to exclude in the patch operation

kbNumbersToInclude
  • string[]

Kbs to include in the patch operation

maxPatchPublishDate
  • string

This is used to install patches that were published on or before this given max published date.