Virtual Machines - Install Patches

Dienst:

Compute

API-Version:

2024-07-01

Installiert Patches auf dem virtuellen Computer.

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

URI-Parameter

Name	In	Erforderlich	Typ	Beschreibung
resourceGroupName	path	True	string	Der Name der Ressourcengruppe.
subscriptionId	path	True	string	Abonnementanmeldeinformationen, die das Microsoft Azure-Abonnement eindeutig identifizieren. Die Abonnement-ID ist Teil des URI für jeden Dienstaufruf.
vmName	path	True	string	Der Name des virtuellen Computers.
api-version	query	True	string	Client-API-Version.

Anforderungstext

Name	Typ	Beschreibung
installPatchesInput	VirtualMachineInstallPatchesParameters	Input for InstallPatches as directly received by the API

Antworten

Name	Typ	Beschreibung
200 OK	VirtualMachineInstallPatchesResult	OKAY
202 Accepted		Angenommen
Other Status Codes	CloudError	Fehlerantwort, die beschreibt, warum der Vorgang fehlgeschlagen ist.

Sicherheit

azure_auth

Azure Active Directory OAuth2-Fluss

Typ: oauth2
Ablauf: implicit
Autorisierungs-URL: https://login.microsoftonline.com/common/oauth2/authorize

Bereiche

Name	Beschreibung
user_impersonation	Identitätswechsel ihres Benutzerkontos

Beispiele

Install patch state of a virtual machine.

Beispielanforderung

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

Beispiel für eine Antwort

Statuscode:

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
}

Statuscode:

202

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

Definitionen

Name	Beschreibung
ApiError	API-Fehler.
ApiErrorBase	API-Fehlerbasis.
CloudError	Eine Fehlerantwort des Computediensts.
InnerError	Innere Fehlerdetails.
LinuxParameters	Input for InstallPatches on a Linux VM, as directly received by the API
PatchInstallationDetail	Die Patches, die während des Vorgangs installiert wurden.
PatchInstallationState	Der Status des Patches nach Abschluss des Installationsvorgangs.
PatchOperationStatus	Der Gesamterfolgs- oder Fehlerstatus des Vorgangs. Es bleibt "InProgress" bis zum Abschluss des Vorgangs. An diesem Punkt wird es "Failed", "Succeeded", "Unknown" oder "CompletedWithWarnings" werden.
VirtualMachineInstallPatchesParameters	Input for InstallPatches as directly received by the API
VirtualMachineInstallPatchesResult	Die Ergebniszusammenfassung eines Installationsvorgangs.
VMGuestPatchClassification_Linux	Die Updateklassifizierungen, die beim Installieren von Patches für Linux ausgewählt werden sollen.
VMGuestPatchClassification_Windows	Die Updateklassifizierungen, die beim Installieren von Patches für Windows ausgewählt werden sollen.
VMGuestPatchRebootSetting	Definiert, wann es akzeptabel ist, einen virtuellen Computer während eines Softwareupdatevorgangs neu zu starten.
VMGuestPatchRebootStatus	Der Neustartstatus der VM nach Abschluss des Vorgangs.
WindowsParameters	Input for InstallPatches on a Windows VM, as directly received by the API

ApiError

API-Fehler.

Name	Typ	Beschreibung
code	string	Der Fehlercode.
details	ApiErrorBase[]	Die API-Fehlerdetails
innererror	InnerError	Interner API-Fehler
message	string	Die Fehlermeldung.
target	string	Das Ziel des bestimmten Fehlers.

ApiErrorBase

API-Fehlerbasis.

Name	Typ	Beschreibung
code	string	Der Fehlercode.
message	string	Die Fehlermeldung.
target	string	Das Ziel des bestimmten Fehlers.

CloudError

Eine Fehlerantwort des Computediensts.

Name	Typ	Beschreibung
error	ApiError	API-Fehler.

InnerError

Innere Fehlerdetails.

Name	Typ	Beschreibung
errordetail	string	Die interne Fehlermeldung oder das Ausnahmeabbild.
exceptiontype	string	Der Ausnahmetyp.

LinuxParameters

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

Name	Typ	Beschreibung
classificationsToInclude	VMGuestPatchClassification_Linux[]	Die Updateklassifizierungen, die beim Installieren von Patches für Linux ausgewählt werden sollen.
maintenanceRunId	string	Dies wird als Wartungsausführungsbezeichner für das Automatische VM-Gastpatching in Linux verwendet.
packageNameMasksToExclude	string[]	Pakete, die im Patchvorgang ausgeschlossen werden sollen. Format: packageName_packageVersion
packageNameMasksToInclude	string[]	Pakete, die in den Patchvorgang eingeschlossen werden sollen. Format: packageName_packageVersion

PatchInstallationDetail

Die Patches, die während des Vorgangs installiert wurden.

Name	Typ	Beschreibung
classifications	string[]	Die Klassifizierung(en) des Patches, wie vom Patchherausgeber bereitgestellt.
installationState	PatchInstallationState	Der Status des Patches nach Abschluss des Installationsvorgangs.
kbId	string	Die KBID des Patches. Gilt nur für Windows-Patches.
name	string	Der Anzeigename des Patches.
patchId	string	Ein eindeutiger Bezeichner für den Patch.
version	string	Die Versionszeichenfolge des Pakets. Sie kann der semantischen Versionsverwaltung entsprechen. Gilt nur für Linux.

PatchInstallationState

Der Status des Patches nach Abschluss des Installationsvorgangs.

Name	Typ	Beschreibung
Excluded	string
Failed	string
Installed	string
NotSelected	string
Pending	string
Unknown	string

PatchOperationStatus

Der Gesamterfolgs- oder Fehlerstatus des Vorgangs. Es bleibt "InProgress" bis zum Abschluss des Vorgangs. An diesem Punkt wird es "Failed", "Succeeded", "Unknown" oder "CompletedWithWarnings" werden.

Name	Typ	Beschreibung
CompletedWithWarnings	string
Failed	string
InProgress	string
Succeeded	string
Unknown	string

VirtualMachineInstallPatchesParameters

Input for InstallPatches as directly received by the API

Name	Typ	Beschreibung
linuxParameters	LinuxParameters	Input for InstallPatches on a Linux VM, as directly received by the API
maximumDuration	string	Gibt die maximale Zeitspanne an, die der Vorgang ausführt. Es muss eine ISO 8601-kompatible Dauerzeichenfolge wie PT4H (4 Stunden) sein.
rebootSetting	VMGuestPatchRebootSetting	Definiert, wann es akzeptabel ist, einen virtuellen Computer während eines Softwareupdatevorgangs neu zu starten.
windowsParameters	WindowsParameters	Input for InstallPatches on a Windows VM, as directly received by the API

VirtualMachineInstallPatchesResult

Die Ergebniszusammenfassung eines Installationsvorgangs.

Name	Typ	Beschreibung
error	ApiError	Die Fehler, die während der Ausführung des Vorgangs aufgetreten sind. Das Detailarray enthält die Liste dieser Elemente.
excludedPatchCount	integer	Die Anzahl der Patches, die nicht installiert wurden, da der Benutzer seine Installation blockiert.
failedPatchCount	integer	Die Anzahl der Patches, die aufgrund eines Problems nicht installiert werden konnten. Details finden Sie unter "Fehler".
installationActivityId	string	Die Aktivitäts-ID des Vorgangs, der dieses Ergebnis erzeugt hat. Es wird verwendet, um in CRP- und Erweiterungsprotokollen zu korrelieren.
installedPatchCount	integer	Die Anzahl der erfolgreich installierten Patches.
maintenanceWindowExceeded	boolean	Gibt an, ob der Vorgang nicht mehr genügend Zeit hat, bevor er alle beabsichtigten Aktionen abgeschlossen hat.
notSelectedPatchCount	integer	Die Anzahl der Patches, die für die Installation als verfügbar erkannt wurden, erfüllten jedoch die Kriterien des Vorgangs nicht.
patches	PatchInstallationDetail[]	Die Patches, die während des Vorgangs installiert wurden.
pendingPatchCount	integer	Die Anzahl der Patches, die als Die Installationskriterien identifiziert wurden, aber nicht installiert werden konnten. Dies geschieht in der Regel, wenn maintenanceWindowExceededed == true.
rebootStatus	VMGuestPatchRebootStatus	Der Neustartstatus der VM nach Abschluss des Vorgangs.
startDateTime	string	Der UTC-Zeitstempel, als der Vorgang begonnen hat.
status	PatchOperationStatus	Der Gesamterfolgs- oder Fehlerstatus des Vorgangs. Es bleibt "InProgress" bis zum Abschluss des Vorgangs. An diesem Punkt wird es "Failed", "Succeeded", "Unknown" oder "CompletedWithWarnings" werden.

VMGuestPatchClassification_Linux

Die Updateklassifizierungen, die beim Installieren von Patches für Linux ausgewählt werden sollen.

Name	Typ	Beschreibung
Critical	string
Other	string
Security	string

VMGuestPatchClassification_Windows

Die Updateklassifizierungen, die beim Installieren von Patches für Windows ausgewählt werden sollen.

Name	Typ	Beschreibung
Critical	string
Definition	string
FeaturePack	string
Security	string
ServicePack	string
Tools	string
UpdateRollUp	string
Updates	string

VMGuestPatchRebootSetting

Definiert, wann es akzeptabel ist, einen virtuellen Computer während eines Softwareupdatevorgangs neu zu starten.

Name	Typ	Beschreibung
Always	string
IfRequired	string
Never	string

VMGuestPatchRebootStatus

Der Neustartstatus der VM nach Abschluss des Vorgangs.

Name	Typ	Beschreibung
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	Typ	Beschreibung
classificationsToInclude	VMGuestPatchClassification_Windows[]	Die Updateklassifizierungen, die beim Installieren von Patches für Windows ausgewählt werden sollen.
excludeKbsRequiringReboot	boolean	Filtert KBs aus, die nicht über "InstallationRebootBehavior" von "NeverReboots" verfügen, wenn dies auf "true" festgelegt ist.
kbNumbersToExclude	string[]	Kbs, die im Patchvorgang ausgeschlossen werden sollen
kbNumbersToInclude	string[]	Kbs, die in den Patchvorgang aufgenommen werden sollen
maxPatchPublishDate	string	Dies wird verwendet, um Patches zu installieren, die am oder vor diesem angegebenen maximalen Veröffentlichungsdatum veröffentlicht wurden.