你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Virtual Machines - Install Patches

服务:: Compute

API 版本:: 2025-04-01

在虚拟机上安装修补程序。

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

URI 参数

名称	在	必需	类型	说明
resourceGroupName	path	True	string minLength: 1 maxLength: 90	资源组的名称。此名称不区分大小写。
subscriptionId	path	True	string minLength: 1	目标订阅的 ID。
vmName	path	True	string	虚拟机的名称。
api-version	query	True	string minLength: 1	要用于此操作的 API 版本。

请求正文

名称	必需	类型	说明
rebootSetting	True	VMGuestPatchRebootSetting	定义在软件更新作期间重新启动 VM 是可以接受的。
linuxParameters		LinuxParameters	Linux VM 上 InstallPatches 的输入，由 API 直接接收
maximumDuration		string (duration)	指定作将运行的最大时间量。它必须是符合 ISO 8601 的持续时间字符串，如 PT4H（4 小时）
windowsParameters		WindowsParameters	Windows VM 上 InstallPatches 的输入，由 API 直接接收

响应

名称

类型

说明

200 OK

VirtualMachineInstallPatchesResult

Azure作已成功完成。

202 Accepted

已接受资源作。

标头

Location: string
Retry-After: integer

Other Status Codes

意外错误响应。

安全性

azure_auth

Azure Active Directory OAuth2 Flow。

类型: oauth2
流向: implicit
授权 URL: https://login.microsoftonline.com/common/oauth2/authorize

作用域

名称	说明
user_impersonation	模拟用户帐户

示例

Install patch state of a virtual machine.

示例请求

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

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


import com.azure.resourcemanager.compute.models.VMGuestPatchClassificationWindows;
import com.azure.resourcemanager.compute.models.VMGuestPatchRebootSetting;
import com.azure.resourcemanager.compute.models.VirtualMachineInstallPatchesParameters;
import com.azure.resourcemanager.compute.models.WindowsParameters;
import java.time.OffsetDateTime;
import java.util.Arrays;

/**
 * Samples for VirtualMachines InstallPatches.
 */
public final class Main {
    /*
     * x-ms-original-file:
     * specification/compute/resource-manager/Microsoft.Compute/ComputeRP/stable/2025-04-01/examples/
     * virtualMachineExamples/VirtualMachine_InstallPatches.json
     */
    /**
     * Sample code: Install patch state of a virtual machine.
     * 
     * @param azure The entry point for accessing resource management APIs in Azure.
     */
    public static void installPatchStateOfAVirtualMachine(com.azure.resourcemanager.AzureResourceManager azure) {
        azure.virtualMachines().manager().serviceClient().getVirtualMachines().installPatches("myResourceGroupName",
            "myVMName",
            new VirtualMachineInstallPatchesParameters().withMaximumDuration("PT4H")
                .withRebootSetting(VMGuestPatchRebootSetting.IF_REQUIRED)
                .withWindowsParameters(new WindowsParameters()
                    .withClassificationsToInclude(Arrays.asList(VMGuestPatchClassificationWindows.CRITICAL,
                        VMGuestPatchClassificationWindows.SECURITY))
                    .withMaxPatchPublishDate(OffsetDateTime.parse("2020-11-19T02:36:43.0539904+00:00"))
                    .withPatchNameMasksToInclude(Arrays.asList("*SQL*"))
                    .withPatchNameMasksToExclude(Arrays.asList("*Windows*"))),
            com.azure.core.util.Context.NONE);
    }
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

from azure.identity import DefaultAzureCredential

from azure.mgmt.compute import ComputeManagementClient

"""
# PREREQUISITES
    pip install azure-identity
    pip install azure-mgmt-compute
# USAGE
    python virtual_machine_install_patches.py

    Before run the sample, please set the values of the client ID, tenant ID and client secret
    of the AAD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID,
    AZURE_CLIENT_SECRET. For more info about how to get the value, please see:
    https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal
"""


def main():
    client = ComputeManagementClient(
        credential=DefaultAzureCredential(),
        subscription_id="{subscription-id}",
    )

    response = client.virtual_machines.begin_install_patches(
        resource_group_name="myResourceGroupName",
        vm_name="myVMName",
        install_patches_input={
            "maximumDuration": "PT4H",
            "rebootSetting": "IfRequired",
            "windowsParameters": {
                "classificationsToInclude": ["Critical", "Security"],
                "maxPatchPublishDate": "2020-11-19T02:36:43.0539904+00:00",
                "patchNameMasksToExclude": ["*Windows*"],
                "patchNameMasksToInclude": ["*SQL*"],
            },
        },
    ).result()
    print(response)


# x-ms-original-file: specification/compute/resource-manager/Microsoft.Compute/ComputeRP/stable/2025-04-01/examples/virtualMachineExamples/VirtualMachine_InstallPatches.json
if __name__ == "__main__":
    main()

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

package armcompute_test

import (
	"context"
	"log"

	"time"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/compute/armcompute/v7"
)

// Generated from example definition: https://github.com/Azure/azure-rest-api-specs/blob/fb90eb1bec64c6e8ad3e288a64c84cc18742a394/specification/compute/resource-manager/Microsoft.Compute/ComputeRP/stable/2025-04-01/examples/virtualMachineExamples/VirtualMachine_InstallPatches.json
func ExampleVirtualMachinesClient_BeginInstallPatches() {
	cred, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("failed to obtain a credential: %v", err)
	}
	ctx := context.Background()
	clientFactory, err := armcompute.NewClientFactory("<subscription-id>", cred, nil)
	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}
	poller, err := clientFactory.NewVirtualMachinesClient().BeginInstallPatches(ctx, "myResourceGroupName", "myVMName", armcompute.VirtualMachineInstallPatchesParameters{
		MaximumDuration: to.Ptr("PT4H"),
		RebootSetting:   to.Ptr(armcompute.VMGuestPatchRebootSettingIfRequired),
		WindowsParameters: &armcompute.WindowsParameters{
			ClassificationsToInclude: []*armcompute.VMGuestPatchClassificationWindows{
				to.Ptr(armcompute.VMGuestPatchClassificationWindowsCritical),
				to.Ptr(armcompute.VMGuestPatchClassificationWindowsSecurity)},
			MaxPatchPublishDate: to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2020-11-19T02:36:43.053Z"); return t }()),
			PatchNameMasksToExclude: []*string{
				to.Ptr("*Windows*")},
			PatchNameMasksToInclude: []*string{
				to.Ptr("*SQL*")},
		},
	}, nil)
	if err != nil {
		log.Fatalf("failed to finish the request: %v", err)
	}
	res, err := poller.PollUntilDone(ctx, nil)
	if err != nil {
		log.Fatalf("failed to pull the result: %v", err)
	}
	// You could use response here. We use blank identifier for just demo purposes.
	_ = res
	// If the HTTP response code is 200 as defined in example definition, your response structure would look as follows. Please pay attention that all the values in the output are fake values for just demo purposes.
	// res.VirtualMachineInstallPatchesResult = armcompute.VirtualMachineInstallPatchesResult{
	// 	ExcludedPatchCount: to.Ptr[int32](0),
	// 	FailedPatchCount: to.Ptr[int32](0),
	// 	InstallationActivityID: to.Ptr("68f8b292-dfc2-4646-9781-33cc88631968"),
	// 	InstalledPatchCount: to.Ptr[int32](3),
	// 	MaintenanceWindowExceeded: to.Ptr(false),
	// 	NotSelectedPatchCount: to.Ptr[int32](0),
	// 	Patches: []*armcompute.PatchInstallationDetail{
	// 		{
	// 			Name: to.Ptr("Definition Update for Windows Defender Antivirus - KB2267602 (Definition 1.279.1373.0)"),
	// 			Classifications: []*string{
	// 				to.Ptr("Definition Updates")},
	// 				InstallationState: to.Ptr(armcompute.PatchInstallationStateInstalled),
	// 				KbID: to.Ptr("2267602"),
	// 				PatchID: to.Ptr("35428702-5784-4ba4-a6e0-5222258b5411"),
	// 				Version: to.Ptr(""),
	// 			},
	// 			{
	// 				Name: to.Ptr("Windows Malicious Software Removal Tool x64 - October 2018 (KB890830)"),
	// 				Classifications: []*string{
	// 					to.Ptr("Update Rollups")},
	// 					InstallationState: to.Ptr(armcompute.PatchInstallationStatePending),
	// 					KbID: to.Ptr("890830"),
	// 					PatchID: to.Ptr("39f9cdd1-795c-4d0e-8c0a-73ab3f31746d"),
	// 					Version: to.Ptr(""),
	// 			}},
	// 			PendingPatchCount: to.Ptr[int32](2),
	// 			RebootStatus: to.Ptr(armcompute.VMGuestPatchRebootStatusCompleted),
	// 			StartDateTime: to.Ptr(func() time.Time { t, _ := time.Parse(time.RFC3339Nano, "2020-04-24T21:02:04.255Z"); return t}()),
	// 			Status: to.Ptr(armcompute.PatchOperationStatusSucceeded),
	// 		}
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

const { ComputeManagementClient } = require("@azure/arm-compute");
const { DefaultAzureCredential } = require("@azure/identity");
require("dotenv/config");

/**
 * This sample demonstrates how to Installs patches on the VM.
 *
 * @summary Installs patches on the VM.
 * x-ms-original-file: specification/compute/resource-manager/Microsoft.Compute/ComputeRP/stable/2025-04-01/examples/virtualMachineExamples/VirtualMachine_InstallPatches.json
 */
async function installPatchStateOfAVirtualMachine() {
  const subscriptionId = process.env["COMPUTE_SUBSCRIPTION_ID"] || "{subscription-id}";
  const resourceGroupName = process.env["COMPUTE_RESOURCE_GROUP"] || "myResourceGroupName";
  const vmName = "myVMName";
  const installPatchesInput = {
    maximumDuration: "PT4H",
    rebootSetting: "IfRequired",
    windowsParameters: {
      classificationsToInclude: ["Critical", "Security"],
      maxPatchPublishDate: new Date("2020-11-19T02:36:43.0539904+00:00"),
      patchNameMasksToExclude: ["*Windows*"],
      patchNameMasksToInclude: ["*SQL*"],
    },
  };
  const credential = new DefaultAzureCredential();
  const client = new ComputeManagementClient(credential, subscriptionId);
  const result = await client.virtualMachines.beginInstallPatchesAndWait(
    resourceGroupName,
    vmName,
    installPatchesInput,
  );
  console.log(result);
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

using Azure;
using Azure.ResourceManager;
using System;
using System.Threading.Tasks;
using System.Xml;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager.Compute.Models;
using Azure.ResourceManager.Compute;

// Generated from example definition: specification/compute/resource-manager/Microsoft.Compute/ComputeRP/stable/2025-04-01/examples/virtualMachineExamples/VirtualMachine_InstallPatches.json
// this example is just showing the usage of "VirtualMachines_InstallPatches" operation, for the dependent resources, they will have to be created separately.

// get your azure access token, for more details of how Azure SDK get your access token, please refer to https://free.blessedness.top/en-us/dotnet/azure/sdk/authentication?tabs=command-line
TokenCredential cred = new DefaultAzureCredential();
// authenticate your client
ArmClient client = new ArmClient(cred);

// this example assumes you already have this VirtualMachineResource created on azure
// for more information of creating VirtualMachineResource, please refer to the document of VirtualMachineResource
string subscriptionId = "{subscription-id}";
string resourceGroupName = "myResourceGroupName";
string vmName = "myVMName";
ResourceIdentifier virtualMachineResourceId = VirtualMachineResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, vmName);
VirtualMachineResource virtualMachine = client.GetVirtualMachineResource(virtualMachineResourceId);

// invoke the operation
VirtualMachineInstallPatchesContent content = new VirtualMachineInstallPatchesContent(VmGuestPatchRebootSetting.IfRequired)
{
    MaximumDuration = XmlConvert.ToTimeSpan("PT4H"),
    WindowsParameters = new WindowsParameters
    {
        ClassificationsToInclude = { VmGuestPatchClassificationForWindows.Critical, VmGuestPatchClassificationForWindows.Security },
        MaxPatchPublishOn = DateTimeOffset.Parse("2020-11-19T02:36:43.0539904+00:00"),
        PatchNameMasksToInclude = { "*SQL*" },
        PatchNameMasksToExclude = { "*Windows*" },
    },
};
ArmOperation<VirtualMachineInstallPatchesResult> lro = await virtualMachine.InstallPatchesAsync(WaitUntil.Completed, content);
VirtualMachineInstallPatchesResult result = lro.Value;

Console.WriteLine($"Succeeded: {result}");

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

示例响应

状态代码:: 200

{
  "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
}

状态代码:: 202

Location: https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Compute/locations/westus/operations/{operationId}&monitor=true&api-version=2025-04-01

定义

名称	说明
ApiError	API 错误。
ApiErrorBase	Api 错误库。
CloudError	来自计算服务的错误响应。
InnerError	内部错误详细信息。
LinuxParameters	Linux VM 上 InstallPatches 的输入，由 API 直接接收
PatchInstallationDetail	有关安装作期间遇到的特定修补程序的信息。
PatchInstallationState	安装作完成后的修补程序状态。
PatchOperationStatus	作的总体成功或失败状态。在作完成之前，它将保持“InProgress”状态。此时，它将变为“未知”、“失败”、“成功”或“CompletedWithWarnings”。
VirtualMachineInstallPatchesParameters	API 直接接收的 InstallPatches 的输入
VirtualMachineInstallPatchesResult	安装作的结果摘要。
VMGuestPatchClassificationLinux
VMGuestPatchClassificationWindows
VMGuestPatchRebootSetting	定义在软件更新作期间重新启动 VM 是可以接受的。
VMGuestPatchRebootStatus	完成作后虚拟机的重新启动状态。
WindowsParameters	Windows VM 上 InstallPatches 的输入，由 API 直接接收

ApiError

Object

API 错误。

名称	类型	说明
code	string	错误代码。
details	ApiErrorBase[]	Api 错误详细信息
innererror	InnerError	Api 内部错误
message	string	错误消息。
target	string	特定错误的目标。

ApiErrorBase

Object

Api 错误库。

名称	类型	说明
code	string	错误代码。
message	string	错误消息。
target	string	特定错误的目标。

CloudError

Object

来自计算服务的错误响应。

名称	类型	说明
error	ApiError	API 错误。

InnerError

Object

内部错误详细信息。

名称	类型	说明
errordetail	string	内部错误消息或异常转储。
exceptiontype	string	异常类型。

LinuxParameters

Object

Linux VM 上 InstallPatches 的输入，由 API 直接接收

名称	类型	说明
classificationsToInclude	VMGuestPatchClassificationLinux[]	安装 Linux 修补程序时要选择的更新分类。
maintenanceRunId	string	这用作 Linux 中自动虚拟机客户机修补的维护运行标识符。
packageNameMasksToExclude	string[]	要排除在修补程序作中的包。格式：packageName_packageVersion
packageNameMasksToInclude	string[]	要包含在修补作中的包。格式：packageName_packageVersion

PatchInstallationDetail

Object

有关安装作期间遇到的特定修补程序的信息。

名称	类型	说明
classifications	string[]	修补程序发布者提供的修补程序的分类。
installationState	PatchInstallationState	安装作完成后的修补程序状态。
kbId	string	修补程序的 KBID。仅适用于 Windows 补丁。
name	string	修补程序的友好名称。
patchId	string	修补程序的唯一标识符。
version	string	包的版本字符串。它可能符合语义版本控制。仅适用于 Linux。

PatchInstallationState

枚举

安装作完成后的修补程序状态。

值	说明
Unknown
Installed
Failed
Excluded
NotSelected
Pending

PatchOperationStatus

枚举

作的总体成功或失败状态。在作完成之前，它将保持“InProgress”状态。此时，它将变为“未知”、“失败”、“成功”或“CompletedWithWarnings”。

值	说明
Unknown
InProgress
Failed
Succeeded
CompletedWithWarnings

VirtualMachineInstallPatchesParameters

Object

API 直接接收的 InstallPatches 的输入

名称	类型	说明
linuxParameters	LinuxParameters	Linux VM 上 InstallPatches 的输入，由 API 直接接收
maximumDuration	string (duration)	指定作将运行的最大时间量。它必须是符合 ISO 8601 的持续时间字符串，如 PT4H（4 小时）
rebootSetting	VMGuestPatchRebootSetting	定义在软件更新作期间重新启动 VM 是可以接受的。
windowsParameters	WindowsParameters	Windows VM 上 InstallPatches 的输入，由 API 直接接收

VirtualMachineInstallPatchesResult

Object

安装作的结果摘要。

名称	类型	说明
error	ApiError	执行作期间遇到的错误。 details 数组包含它们的列表。
excludedPatchCount	integer (int32)	由于用户阻止其安装而未安装的修补程序数。
failedPatchCount	integer (int32)	由于某些问题而无法安装的修补程序数。有关详细信息，请参阅错误。
installationActivityId	string	生成此结果的作的活动 ID。它用于跨 CRP 和扩展日志进行关联。
installedPatchCount	integer (int32)	成功安装的修补程序数。
maintenanceWindowExceeded	boolean	作在完成所有预期作之前是否已用完时间。
notSelectedPatchCount	integer (int32)	检测到可用于安装但不符合作条件的修补程序数。
patches	PatchInstallationDetail[]	作期间安装的修补程序。
pendingPatchCount	integer (int32)	被标识为满足安装条件但无法安装的修补程序数。通常，当 maintenanceWindowExceeded == true 时会发生这种情况。
rebootStatus	VMGuestPatchRebootStatus	完成作后虚拟机的重新启动状态。
startDateTime	string (date-time)	作开始时的 UTC 时间戳。
status	PatchOperationStatus	作的总体成功或失败状态。在作完成之前，它将保持“InProgress”状态。此时，它将变为“失败”、“成功”、“未知”或“CompletedWithWarnings”。

VMGuestPatchClassificationLinux

枚举

值	说明
Critical
Security
Other

VMGuestPatchClassificationWindows

枚举

值	说明
Critical
Security
UpdateRollUp
FeaturePack
ServicePack
Definition
Tools
Updates

VMGuestPatchRebootSetting

枚举

定义在软件更新作期间重新启动 VM 是可以接受的。

值	说明
IfRequired
Never
Always

VMGuestPatchRebootStatus

枚举

完成作后虚拟机的重新启动状态。

值	说明
Unknown
NotNeeded
Required
Started
Failed
Completed

WindowsParameters

Object

Windows VM 上 InstallPatches 的输入，由 API 直接接收

名称	类型	说明
classificationsToInclude	VMGuestPatchClassificationWindows[]	安装 Windows 修补程序时要选择的更新分类。
excludeKbsRequiringReboot	boolean	筛选掉在设置为 true 时没有“NeverReboots”的 InstallationRebootBehavior 的 Kbs。
kbNumbersToExclude	string[]	在修补作中要排除的 Kbs
kbNumbersToInclude	string[]	要包含在修补作中的 Kbs
maxPatchPublishDate	string (date-time)	它用于安装此给定最晚发布日期或之前发布的修补程序。
patchNameMasksToExclude	string[]	这用于排除与给定修补程序名称掩码匹配的修补程序。字母数字字符串和通配符表达式，由 * 和？仅支持作为列表中的输入值。不支持空、空和仅空格字符串作为输入值。
patchNameMasksToInclude	string[]	这用于包括与给定补丁名称掩码匹配的补丁。字母数字字符串和通配符表达式，由 * 和？仅支持作为列表中的输入值。不支持空、空和仅空格字符串作为输入值。