Virtual Machines - Install Patches

服務:

Compute

API 版本:

2024-07-01

在 VM 上安裝修補程式。

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

URI 參數

名稱	位於	必要	類型	Description
resourceGroupName	path	True	string	資源群組的名稱。
subscriptionId	path	True	string	可唯一識別Microsoft Azure 訂用帳戶的訂用帳戶認證。 訂用帳戶標識碼會形成每個服務呼叫 URI 的一部分。
vmName	path	True	string	虛擬機的名稱。
api-version	query	True	string	用戶端 API 版本。

要求本文

名稱	類型	Description
installPatchesInput	VirtualMachineInstallPatchesParameters	由 API 直接接收的 InstallPatches 輸入

回應

名稱	類型	Description
200 OK	VirtualMachineInstallPatchesResult	還行
202 Accepted		接受
Other Status Codes	CloudError	描述作業失敗原因的錯誤回應。

安全性

azure_auth

Azure Active Directory OAuth2 Flow

類型: oauth2
Flow: implicit
授權 URL: https://login.microsoftonline.com/common/oauth2/authorize

範圍

名稱	Description
user_impersonation	模擬您的用戶帳戶

範例

Install patch state of a virtual machine.

範例要求

HTTP

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

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

Java

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/2024-07-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"))),
            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

Python

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",
            },
        },
    ).result()
    print(response)


# x-ms-original-file: specification/compute/resource-manager/Microsoft.Compute/ComputeRP/stable/2024-07-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

Go

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/v6"
)

// Generated from example definition: https://github.com/Azure/azure-rest-api-specs/blob/069a65e8a6d1a6c0c58d9a9d97610b7103b6e8a5/specification/compute/resource-manager/Microsoft.Compute/ComputeRP/stable/2024-07-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 }()),
		},
	}, 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

JavaScript

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

/**
 * 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/2024-07-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"),
    },
  };
  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

dotnet

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/2024-07-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://learn.microsoft.com/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"),
    },
};
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=2024-07-01

定義

名稱	Description
ApiError	Api 錯誤。
ApiErrorBase	API 錯誤基底。
CloudError	來自計算服務的錯誤回應。
InnerError	內部錯誤詳細數據。
LinuxParameters	Linux VM 上的 InstallPatches 輸入，如 API 直接接收
PatchInstallationDetail	作業期間安裝的修補程式。
PatchInstallationState	安裝作業完成後修補程序的狀態。
PatchOperationStatus	作業的整體成功或失敗狀態。 在作業完成之前，它會維持 「InProgress」。 屆時，它將會變成「失敗」、「成功」、「未知」或「CompletedWithWarnings」。
VirtualMachineInstallPatchesParameters	由 API 直接接收的 InstallPatches 輸入
VirtualMachineInstallPatchesResult	安裝作業的結果摘要。
VMGuestPatchClassification_Linux	安裝 Linux 修補程式時要選取的更新分類。
VMGuestPatchClassification_Windows	安裝 Windows 修補程式時要選取的更新分類。
VMGuestPatchRebootSetting	定義在軟體更新作業期間可接受重新啟動 VM 的時機。
VMGuestPatchRebootStatus	作業完成後 VM 的重新啟動狀態。
WindowsParameters	Windows VM 上的 InstallPatches 輸入，如 API 直接接收

ApiError

Api 錯誤。

名稱	類型	Description
code	string	錯誤碼。
details	ApiErrorBase[]	Api 錯誤詳細數據
innererror	InnerError	Api 內部錯誤
message	string	錯誤訊息。
target	string	特定錯誤的目標。

ApiErrorBase

API 錯誤基底。

名稱	類型	Description
code	string	錯誤碼。
message	string	錯誤訊息。
target	string	特定錯誤的目標。

CloudError

來自計算服務的錯誤回應。

名稱	類型	Description
error	ApiError	Api 錯誤。

InnerError

內部錯誤詳細數據。

名稱	類型	Description
errordetail	string	內部錯誤訊息或例外狀況傾印。
exceptiontype	string	例外狀況類型。

LinuxParameters

Linux VM 上的 InstallPatches 輸入，如 API 直接接收

名稱	類型	Description
classificationsToInclude	VMGuestPatchClassification_Linux[]	安裝 Linux 修補程式時要選取的更新分類。
maintenanceRunId	string	這會作為Linux中自動VM客體修補的維護執行標識碼。
packageNameMasksToExclude	string[]	修補作業中要排除的套件。 格式：packageName_packageVersion
packageNameMasksToInclude	string[]	要包含在修補作業中的套件。 格式：packageName_packageVersion

PatchInstallationDetail

作業期間安裝的修補程式。

名稱	類型	Description
classifications	string[]	修補程式發行者所提供的修補程序分類。。
installationState	PatchInstallationState	安裝作業完成後修補程序的狀態。
kbId	string	修補程式的 KBID。 僅適用於 Windows 修補程式。
name	string	修補程式的易記名稱。
patchId	string	修補程式的唯一標識碼。
version	string	封裝的版本字串。 它可能符合語意版本設定。 僅適用於Linux。

PatchInstallationState

安裝作業完成後修補程序的狀態。

名稱	類型	Description
Excluded	string
Failed	string
Installed	string
NotSelected	string
Pending	string
Unknown	string

PatchOperationStatus

作業的整體成功或失敗狀態。 在作業完成之前，它會維持 「InProgress」。 屆時，它將會變成「失敗」、「成功」、「未知」或「CompletedWithWarnings」。

名稱	類型	Description
CompletedWithWarnings	string
Failed	string
InProgress	string
Succeeded	string
Unknown	string

VirtualMachineInstallPatchesParameters

由 API 直接接收的 InstallPatches 輸入

名稱	類型	Description
linuxParameters	LinuxParameters	Linux VM 上的 InstallPatches 輸入，如 API 直接接收
maximumDuration	string	指定作業執行的時間上限。 它必須是符合 ISO 8601 規範的持續時間字串串，例如 PT4H（4 小時）
rebootSetting	VMGuestPatchRebootSetting	定義在軟體更新作業期間可接受重新啟動 VM 的時機。
windowsParameters	WindowsParameters	Windows VM 上的 InstallPatches 輸入，如 API 直接接收

VirtualMachineInstallPatchesResult

安裝作業的結果摘要。

名稱	類型	Description
error	ApiError	作業執行期間遇到的錯誤。 詳細數據陣列包含它們的清單。
excludedPatchCount	integer	由於使用者封鎖其安裝而未安裝的修補程式數目。
failedPatchCount	integer	由於某些問題而無法安裝的修補程式數目。 如需詳細資訊，請參閱錯誤。
installationActivityId	string	產生此結果之作業的活動標識碼。 它用來跨CRP和擴充功能記錄相互關聯。
installedPatchCount	integer	已成功安裝修補程式數目。
maintenanceWindowExceeded	boolean	作業是否在完成所有預定動作之前已用完時間。
notSelectedPatchCount	integer	偵測為可供安裝的修補程式數目，但不符合作業的準則。
patches	PatchInstallationDetail[]	作業期間安裝的修補程式。
pendingPatchCount	integer	已識別為符合安裝準則但無法安裝的修補程式數目。 一般而言，當 maintenanceWindowExceeded == true 時，就會發生這種情況。
rebootStatus	VMGuestPatchRebootStatus	作業完成後 VM 的重新啟動狀態。
startDateTime	string	作業開始時的 UTC 時間戳。
status	PatchOperationStatus	作業的整體成功或失敗狀態。 在作業完成之前，它會維持 「InProgress」。 屆時，它將會變成「失敗」、「成功」、「未知」或「CompletedWithWarnings」。

VMGuestPatchClassification_Linux

安裝 Linux 修補程式時要選取的更新分類。

名稱	類型	Description
Critical	string
Other	string
Security	string

VMGuestPatchClassification_Windows

安裝 Windows 修補程式時要選取的更新分類。

名稱	類型	Description
Critical	string
Definition	string
FeaturePack	string
Security	string
ServicePack	string
Tools	string
UpdateRollUp	string
Updates	string

VMGuestPatchRebootSetting

定義在軟體更新作業期間可接受重新啟動 VM 的時機。

名稱	類型	Description
Always	string
IfRequired	string
Never	string

VMGuestPatchRebootStatus

作業完成後 VM 的重新啟動狀態。

名稱	類型	Description
Completed	string
Failed	string
NotNeeded	string
Required	string
Started	string
Unknown	string

WindowsParameters

Windows VM 上的 InstallPatches 輸入，如 API 直接接收

名稱	類型	Description
classificationsToInclude	VMGuestPatchClassification_Windows[]	安裝 Windows 修補程式時要選取的更新分類。
excludeKbsRequiringReboot	boolean	篩選出 Kbs，當此設定為 true 時，不會有 'NeverReboots' 的 InstallationRebootBehavior。
kbNumbersToExclude	string[]	修補作業中要排除的 Kbs
kbNumbersToInclude	string[]	要包含在修補作業中的 Kbs
maxPatchPublishDate	string	這是用來安裝在此指定發佈日期上限之前或之前發佈的修補程式。