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 |
|---|---|---|---|---|
|
resource
|
path | True |
|
The name of the resource group. |
|
subscription
|
path | True |
|
Subscription credentials which uniquely identify Microsoft Azure subscription. The subscription ID forms part of the URI for every service call. |
|
vm
|
path | True |
|
The name of the virtual machine. |
|
api-version
|
query | True |
|
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 |
|
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
|
Api |
Api error. |
|
Api |
Api error base. |
|
Cloud |
An error response from the Compute service. |
|
Inner |
Inner error details. |
|
Linux |
Input for InstallPatches on a Linux VM, as directly received by the API |
|
Patch |
Information about a specific patch that was encountered during an installation action. |
|
Patch |
The state of the patch after the installation operation completed. |
|
Patch |
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." |
|
Virtual |
Input for InstallPatches as directly received by the API |
|
Virtual |
The result summary of an installation operation. |
|
VMGuest |
Defines when it is acceptable to reboot a VM during a software update operation. |
|
VMGuest |
The reboot state of the VM following completion of the operation. |
|
Windows |
Input for InstallPatches on a Windows VM, as directly received by the API |
ApiError
Api error.
| Name | Type | Description |
|---|---|---|
| code |
|
The error code. |
| details |
The Api error details |
|
| innererror |
The Api inner error |
|
| message |
|
The error message. |
| target |
|
The target of the particular error. |
ApiErrorBase
Api error base.
| Name | Type | Description |
|---|---|---|
| code |
|
The error code. |
| message |
|
The error message. |
| target |
|
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 |
|
The internal error message or exception dump. |
| exceptiontype |
|
The exception type. |
LinuxParameters
Input for InstallPatches on a Linux VM, as directly received by the API
| Name | Type | Description |
|---|---|---|
| classificationsToInclude |
|
The update classifications to select when installing patches for Linux. |
| maintenanceRunId |
|
This is used as a maintenance run identifier for Auto VM Guest Patching in Linux. |
| packageNameMasksToExclude |
|
packages to exclude in the patch operation. Format: packageName_packageVersion |
| packageNameMasksToInclude |
|
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 |
|
The classification(s) of the patch as provided by the patch publisher. |
| installationState |
The state of the patch after the installation operation completed. |
|
| kbId |
|
The KBID of the patch. Only applies to Windows patches. |
| name |
|
The friendly name of the patch. |
| patchId |
|
A unique identifier for the patch. |
| version |
|
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 |
|
|
| Failed |
|
|
| Installed |
|
|
| NotSelected |
|
|
| Pending |
|
|
| Unknown |
|
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 |
|
|
| Failed |
|
|
| InProgress |
|
|
| Succeeded |
|
|
| Unknown |
|
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 |
|
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 |
|
The number of patches that were not installed due to the user blocking their installation. |
| failedPatchCount |
|
The number of patches that could not be installed due to some issue. See errors for details. |
| installationActivityId |
|
The activity ID of the operation that produced this result. It is used to correlate across CRP and extension logs. |
| installedPatchCount |
|
The number of patches successfully installed. |
| maintenanceWindowExceeded |
|
Whether the operation ran out of time before it completed all its intended actions. |
| notSelectedPatchCount |
|
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 |
|
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 |
|
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 |
|
|
| IfRequired |
|
|
| Never |
|
VMGuestPatchRebootStatus
The reboot state of the VM following completion of the operation.
| Name | Type | Description |
|---|---|---|
| Completed |
|
|
| Failed |
|
|
| NotNeeded |
|
|
| Required |
|
|
| Started |
|
|
| Unknown |
|
WindowsParameters
Input for InstallPatches on a Windows VM, as directly received by the API
| Name | Type | Description |
|---|---|---|
| classificationsToInclude |
|
The update classifications to select when installing patches for Windows. |
| excludeKbsRequiringReboot |
|
Filters out Kbs that don't have an InstallationRebootBehavior of 'NeverReboots' when this is set to true. |
| kbNumbersToExclude |
|
Kbs to exclude in the patch operation |
| kbNumbersToInclude |
|
Kbs to include in the patch operation |
| maxPatchPublishDate |
|
This is used to install patches that were published on or before this given max published date. |