Virtual Machine Scale Set VM Extensions - Create Or Update

服務:

Compute

API 版本:

2024-07-01

建立或更新 VMSS VM 擴充功能的作業。

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachineScaleSets/{vmScaleSetName}/virtualMachines/{instanceId}/extensions/{vmExtensionName}?api-version=2024-07-01

URI 參數

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

要求本文

名稱	類型	Description
location	string	延伸模組的位置。
properties.autoUpgradeMinorVersion	boolean	指出如果部署期間有新的次要版本，擴充功能是否應該使用較新的次要版本。 不過，部署之後，除非重新部署，否則擴充功能不會升級次要版本，即使此屬性設定為 true 也一定會升級。
properties.enableAutomaticUpgrade	boolean	指出如果有較新版本的延伸模組可用，平臺是否應該自動升級延伸模組。
properties.forceUpdateTag	string	即使延伸模組組態尚未變更，延伸模組處理程式也應該強制更新。
properties.instanceView	VirtualMachineExtensionInstanceView	虛擬機擴充實例檢視。
properties.protectedSettings	object	延伸模組可以包含 protectedSettings 或 protectedSettingsFromKeyVault 或完全沒有受保護的設定。
properties.protectedSettingsFromKeyVault	KeyVaultSecretReference	以傳址方式傳遞的延伸模組受保護設定，並從金鑰保存庫取用
properties.provisionAfterExtensions	string[]	必須布建此延伸模組之後的延伸模組名稱集合。
properties.publisher	string	擴充處理程序發行者的名稱。
properties.settings	object	擴充功能的 Json 格式化公用設定。
properties.suppressFailures	boolean	指出延伸模組產生的失敗是否會隱藏（不論此值為何，無法連線到 VM 等作業失敗）。 默認值為 false。
properties.type	string	指定延伸模組的類型;例如“CustomScriptExtension”。
properties.typeHandlerVersion	string	指定文稿處理程式的版本。

回應

名稱	類型	Description
200 OK	VirtualMachineScaleSetVMExtension	還行
201 Created	VirtualMachineScaleSetVMExtension	創建
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	模擬您的用戶帳戶

範例

Create VirtualMachineScaleSet VM extension.

範例要求

HTTP

PUT https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachineScaleSets/myvmScaleSet/virtualMachines/0/extensions/myVMExtension?api-version=2024-07-01

{
  "properties": {
    "autoUpgradeMinorVersion": true,
    "publisher": "extPublisher",
    "type": "extType",
    "typeHandlerVersion": "1.2",
    "settings": {
      "UserName": "xyz@microsoft.com"
    }
  }
}

Java

import com.azure.core.management.serializer.SerializerFactory;
import com.azure.core.util.serializer.SerializerEncoding;
import com.azure.resourcemanager.compute.fluent.models.VirtualMachineScaleSetVMExtensionInner;
import java.io.IOException;

/**
 * Samples for VirtualMachineScaleSetVMExtensions CreateOrUpdate.
 */
public final class Main {
    /*
     * x-ms-original-file:
     * specification/compute/resource-manager/Microsoft.Compute/ComputeRP/stable/2024-07-01/examples/
     * virtualMachineScaleSetExamples/VirtualMachineScaleSetVMExtension_Create.json
     */
    /**
     * Sample code: Create VirtualMachineScaleSet VM extension.
     * 
     * @param azure The entry point for accessing resource management APIs in Azure.
     */
    public static void createVirtualMachineScaleSetVMExtension(com.azure.resourcemanager.AzureResourceManager azure)
        throws IOException {
        azure.virtualMachines().manager().serviceClient().getVirtualMachineScaleSetVMExtensions().createOrUpdate(
            "myResourceGroup", "myvmScaleSet", "0", "myVMExtension",
            new VirtualMachineScaleSetVMExtensionInner().withPublisher("extPublisher").withTypePropertiesType("extType")
                .withTypeHandlerVersion("1.2").withAutoUpgradeMinorVersion(true)
                .withSettings(SerializerFactory.createDefaultManagementSerializerAdapter()
                    .deserialize("{\"UserName\":\"xyz@microsoft.com\"}", Object.class, SerializerEncoding.JSON)),
            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_scale_set_vm_extension_create.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_machine_scale_set_vm_extensions.begin_create_or_update(
        resource_group_name="myResourceGroup",
        vm_scale_set_name="myvmScaleSet",
        instance_id="0",
        vm_extension_name="myVMExtension",
        extension_parameters={
            "properties": {
                "autoUpgradeMinorVersion": True,
                "publisher": "extPublisher",
                "settings": {"UserName": "xyz@microsoft.com"},
                "type": "extType",
                "typeHandlerVersion": "1.2",
            }
        },
    ).result()
    print(response)


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

	"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/virtualMachineScaleSetExamples/VirtualMachineScaleSetVMExtension_Create.json
func ExampleVirtualMachineScaleSetVMExtensionsClient_BeginCreateOrUpdate() {
	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.NewVirtualMachineScaleSetVMExtensionsClient().BeginCreateOrUpdate(ctx, "myResourceGroup", "myvmScaleSet", "0", "myVMExtension", armcompute.VirtualMachineScaleSetVMExtension{
		Properties: &armcompute.VirtualMachineExtensionProperties{
			Type:                    to.Ptr("extType"),
			AutoUpgradeMinorVersion: to.Ptr(true),
			Publisher:               to.Ptr("extPublisher"),
			Settings: map[string]any{
				"UserName": "xyz@microsoft.com",
			},
			TypeHandlerVersion: to.Ptr("1.2"),
		},
	}, 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.VirtualMachineScaleSetVMExtension = armcompute.VirtualMachineScaleSetVMExtension{
	// 	ID: to.Ptr("/subscriptions/{subscriptionId}/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachineScaleSets/myvmScaleSet/virtualMachines/0/extensions/myVMExtension"),
	// 	Name: to.Ptr("myVMExtension"),
	// 	Type: to.Ptr("Microsoft.Compute/virtualMachineScaleSets/virtualMachines/extensions"),
	// 	Properties: &armcompute.VirtualMachineExtensionProperties{
	// 		Type: to.Ptr("extType"),
	// 		AutoUpgradeMinorVersion: to.Ptr(true),
	// 		ProvisioningState: to.Ptr("Succeeded"),
	// 		Publisher: to.Ptr("extPublisher"),
	// 		Settings: map[string]any{
	// 			"UserName": "xyz@microsoft.com",
	// 		},
	// 		TypeHandlerVersion: to.Ptr("1.2"),
	// 	},
	// }
}

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 The operation to create or update the VMSS VM extension.
 *
 * @summary The operation to create or update the VMSS VM extension.
 * x-ms-original-file: specification/compute/resource-manager/Microsoft.Compute/ComputeRP/stable/2024-07-01/examples/virtualMachineScaleSetExamples/VirtualMachineScaleSetVMExtension_Create.json
 */
async function createVirtualMachineScaleSetVMExtension() {
  const subscriptionId = process.env["COMPUTE_SUBSCRIPTION_ID"] || "{subscription-id}";
  const resourceGroupName = process.env["COMPUTE_RESOURCE_GROUP"] || "myResourceGroup";
  const vmScaleSetName = "myvmScaleSet";
  const instanceId = "0";
  const vmExtensionName = "myVMExtension";
  const extensionParameters = {
    typePropertiesType: "extType",
    autoUpgradeMinorVersion: true,
    publisher: "extPublisher",
    settings: { UserName: "xyz@microsoft.com" },
    typeHandlerVersion: "1.2",
  };
  const credential = new DefaultAzureCredential();
  const client = new ComputeManagementClient(credential, subscriptionId);
  const result = await client.virtualMachineScaleSetVMExtensions.beginCreateOrUpdateAndWait(
    resourceGroupName,
    vmScaleSetName,
    instanceId,
    vmExtensionName,
    extensionParameters,
  );
  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 Azure.Core;
using Azure.Identity;
using Azure.ResourceManager.Compute;

// Generated from example definition: specification/compute/resource-manager/Microsoft.Compute/ComputeRP/stable/2024-07-01/examples/virtualMachineScaleSetExamples/VirtualMachineScaleSetVMExtension_Create.json
// this example is just showing the usage of "VirtualMachineScaleSetVMExtensions_CreateOrUpdate" 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 VirtualMachineScaleSetVmResource created on azure
// for more information of creating VirtualMachineScaleSetVmResource, please refer to the document of VirtualMachineScaleSetVmResource
string subscriptionId = "{subscription-id}";
string resourceGroupName = "myResourceGroup";
string virtualMachineScaleSetName = "myvmScaleSet";
string instanceId = "0";
ResourceIdentifier virtualMachineScaleSetVmResourceId = VirtualMachineScaleSetVmResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, virtualMachineScaleSetName, instanceId);
VirtualMachineScaleSetVmResource virtualMachineScaleSetVm = client.GetVirtualMachineScaleSetVmResource(virtualMachineScaleSetVmResourceId);

// get the collection of this VirtualMachineScaleSetVmExtensionResource
VirtualMachineScaleSetVmExtensionCollection collection = virtualMachineScaleSetVm.GetVirtualMachineScaleSetVmExtensions();

// invoke the operation
string vmExtensionName = "myVMExtension";
VirtualMachineScaleSetVmExtensionData data = new VirtualMachineScaleSetVmExtensionData
{
    Publisher = "extPublisher",
    ExtensionType = "extType",
    TypeHandlerVersion = "1.2",
    AutoUpgradeMinorVersion = true,
    Settings = BinaryData.FromObjectAsJson(new
    {
        UserName = "xyz@microsoft.com",
    }),
};
ArmOperation<VirtualMachineScaleSetVmExtensionResource> lro = await collection.CreateOrUpdateAsync(WaitUntil.Completed, vmExtensionName, data);
VirtualMachineScaleSetVmExtensionResource result = lro.Value;

// the variable result is a resource, you could call other operations on this instance as well
// but just for demo, we get its data from this resource instance
VirtualMachineScaleSetVmExtensionData resourceData = result.Data;
// for demo we just print out the id
Console.WriteLine($"Succeeded on id: {resourceData.Id}");

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

範例回覆

狀態碼:

201

{
  "name": "myVMExtension",
  "type": "Microsoft.Compute/virtualMachineScaleSets/virtualMachines/extensions",
  "id": "/subscriptions/{subscriptionId}/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachineScaleSets/myvmScaleSet/virtualMachines/0/extensions/myVMExtension",
  "properties": {
    "autoUpgradeMinorVersion": true,
    "provisioningState": "Creating",
    "publisher": "extPublisher",
    "type": "extType",
    "typeHandlerVersion": "1.2",
    "settings": {
      "UserName": "xyz@microsoft.com"
    }
  }
}

狀態碼:

200

{
  "name": "myVMExtension",
  "type": "Microsoft.Compute/virtualMachineScaleSets/virtualMachines/extensions",
  "id": "/subscriptions/{subscriptionId}/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachineScaleSets/myvmScaleSet/virtualMachines/0/extensions/myVMExtension",
  "properties": {
    "autoUpgradeMinorVersion": true,
    "provisioningState": "Creating",
    "publisher": "extPublisher",
    "type": "extType",
    "typeHandlerVersion": "1.2",
    "settings": {
      "UserName": "xyz@microsoft.com"
    }
  }
}

定義

名稱	Description
ApiError	Api 錯誤。
ApiErrorBase	API 錯誤基底。
CloudError	來自計算服務的錯誤回應。
InnerError	內部錯誤詳細數據。
InstanceViewStatus	實例檢視狀態。
KeyVaultSecretReference	描述 Key Vault 秘密的參考
StatusLevelTypes	層級程序代碼。
SubResource
VirtualMachineExtensionInstanceView	虛擬機擴充功能的實例檢視。
VirtualMachineScaleSetVMExtension	描述 VMSS VM 擴充功能。

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	例外狀況類型。

InstanceViewStatus

實例檢視狀態。

名稱	類型	Description
code	string	狀態代碼。
displayStatus	string	狀態的簡短可當地語系化標籤。
level	StatusLevelTypes	層級程序代碼。
message	string	詳細的狀態消息，包括警示和錯誤訊息。
time	string	狀態的時間。

KeyVaultSecretReference

描述 Key Vault 秘密的參考

名稱	類型	Description
secretUrl	string	參考 Key Vault 中秘密的 URL。
sourceVault	SubResource	包含秘密之 Key Vault 的相對 URL。

StatusLevelTypes

層級程序代碼。

名稱	類型	Description
Error	string
Info	string
Warning	string

SubResource

名稱	類型	Description
id	string	資源標識碼

VirtualMachineExtensionInstanceView

虛擬機擴充功能的實例檢視。

名稱	類型	Description
name	string	虛擬機擴充功能名稱。
statuses	InstanceViewStatus[]	資源狀態資訊。
substatuses	InstanceViewStatus[]	資源狀態資訊。
type	string	指定延伸模組的類型;例如“CustomScriptExtension”。
typeHandlerVersion	string	指定文稿處理程式的版本。

VirtualMachineScaleSetVMExtension

描述 VMSS VM 擴充功能。

名稱	類型	Description
id	string	資源標識碼
location	string	延伸模組的位置。
name	string	延伸模組的名稱。
properties.autoUpgradeMinorVersion	boolean	指出如果部署期間有新的次要版本，擴充功能是否應該使用較新的次要版本。 不過，部署之後，除非重新部署，否則擴充功能不會升級次要版本，即使此屬性設定為 true 也一定會升級。
properties.enableAutomaticUpgrade	boolean	指出如果有較新版本的延伸模組可用，平臺是否應該自動升級延伸模組。
properties.forceUpdateTag	string	即使延伸模組組態尚未變更，延伸模組處理程式也應該強制更新。
properties.instanceView	VirtualMachineExtensionInstanceView	虛擬機擴充實例檢視。
properties.protectedSettings	object	延伸模組可以包含 protectedSettings 或 protectedSettingsFromKeyVault 或完全沒有受保護的設定。
properties.protectedSettingsFromKeyVault	KeyVaultSecretReference	以傳址方式傳遞的延伸模組受保護設定，並從金鑰保存庫取用
properties.provisionAfterExtensions	string[]	必須布建此延伸模組之後的延伸模組名稱集合。
properties.provisioningState	string	只出現在回應中的布建狀態。
properties.publisher	string	擴充處理程序發行者的名稱。
properties.settings	object	擴充功能的 Json 格式化公用設定。
properties.suppressFailures	boolean	指出延伸模組產生的失敗是否會隱藏（不論此值為何，無法連線到 VM 等作業失敗）。 默認值為 false。
properties.type	string	指定延伸模組的類型;例如“CustomScriptExtension”。
properties.typeHandlerVersion	string	指定文稿處理程式的版本。
type	string	資源類型