更新 Batch 集區屬性

2025-04-21

建立 Azure Batch 集區時，您可以指定定義集區組態的特定屬性。範例包括指定 VM 大小、要使用的 VM 映像、虛擬網路組態和加密設定。然而，當工作負載隨時間而變化或 VM 映像達到生命週期結束時，您可能需要更新集區屬性。

這些集區屬性中的某些屬性 (但不是全部) 可以進行修補或更新以適應這些情況。本文提供有關可更新的集區屬性、集區屬性更新的預期行為以及範例的資訊。

秘訣

某些集區屬性只能使用 Batch Management Plane API 或 SDK (使用 Entra 驗證) 來進行更新。您需要安裝或使用適當的 API 或 SDK 才能進行這些作業。

可更新的集區屬性

Batch 提供多種方法來更新集區的屬性值。選取要使用的 API 可決定可以更新的集區屬性集以及更新行為。

附註

如果您想要更新不屬於以下 Update 或 Patch API 的集區屬性，則必須重新建立集區以反映所需的狀態。

管理平面：Pool - Update

更新集區屬性的建議途徑是利用 Pool - Update API 作為 Batch Management Plane API 或 SDK 的一部分。此 API 提供了最全面且彈性的方式來更新集區屬性。使用此 API 可選擇性地更新僅限管理平面的集區屬性，也可以透過 Data Plane API 更新其他原本不變的屬性。

重要

您必須使用 API 版本 2024-07-01 或更新版本的 Batch Management Plane API 來更新集區屬性，如本節所述。

由於這項作業是 PATCH，因此只會更新要求中所指定的集區屬性。如果未將屬性指定為要求的一部分，則現有的值會保持未修改。

某些屬性僅當集區中沒有作用中的節點或集區中計算節點總數為零時才能更新。不要求集區大小為零才能讓新值生效的屬性包括：

應用套件
證書
中繼資料
scaleSettings
startTask

如果使用這些屬性更新集區時存在作用中的節點，則可能需要重新啟動作用中的計算節點才能使變更生效。如需詳細資訊，請參閱每個個別集區屬性的文件。

所有其他可更新的集區屬性都需要將集區的大小設為零個節點，才能被接受作為更新要求的一部分。

您也可以使用 Pool - Create API 來更新這些選定屬性，但由於該作業是 PUT，因此該要求會完全取代所有現有的屬性。因此，在該要求中未指定的任何屬性都會被移除或設定為相關聯的預設值。

範例：更新 VM 映像規格

以下範例顯示如何透過 Management Plane C# SDK 來更新集區 VM 映像組態：

public async Task UpdatePoolVmImage()
{
     // Authenticate
     var clientId = Environment.GetEnvironmentVariable("CLIENT_ID");
     var clientSecret = Environment.GetEnvironmentVariable("CLIENT_SECRET");
     var tenantId = Environment.GetEnvironmentVariable("TENANT_ID");
     var subscriptionId = Environment.GetEnvironmentVariable("SUBSCRIPTION_ID");
     ClientSecretCredential credential = new ClientSecretCredential(tenantId, clientId, clientSecret);
     ArmClient client = new ArmClient(credential, subscriptionId);

     // Get an existing Batch account
     string resourceGroupName = "<resourcegroup>";
     string accountName = "<batchaccount>";
     ResourceIdentifier batchAccountResourceId = BatchAccountResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, accountName);
     BatchAccountResource batchAccount = client.GetBatchAccountResource(batchAccountResourceId);

     // get the collection of this BatchAccountPoolResource
     BatchAccountPoolCollection collection = batchAccount.GetBatchAccountPools();

     // Update the pool
     string poolName = "mypool";
     BatchAccountPoolData data = new BatchAccountPoolData()
     {
         DeploymentConfiguration = new BatchDeploymentConfiguration()
         {
             VmConfiguration = new BatchVmConfiguration(new BatchImageReference()
             {
                 Publisher = "MicrosoftWindowsServer",
                 Offer = "WindowsServer",
                 Sku = "2022-datacenter-azure-edition-smalldisk",
                 Version = "latest",
             },
             nodeAgentSkuId: "batch.node.windows amd64"),
         },
     };

     ArmOperation<BatchAccountPoolResource> lro = await collection.CreateOrUpdateAsync(WaitUntil.Completed, poolName, data);
     BatchAccountPoolResource result = lro.Value;

     BatchAccountPoolData resourceData = result.Data;
     Console.WriteLine($"Succeeded on id: {resourceData.Id}");
}

範例：更新 VM 大小和目標節點通訊模式

以下範例示範如何透過 REST API 來更新集區 VM 映像大小和目標節點通訊模式以簡化：

PATCH https://management.azure.com/subscriptions/<subscriptionid>/resourceGroups/<resourcegroupName>/providers/Microsoft.Batch/batchAccounts/<batchaccountname>/pools/<poolname>?api-version=2024-07-01

要求本文

{
    "type": "Microsoft.Batch/batchAccounts/pools",
    "parameters": {
        "properties": {
            "vmSize": "standard_d32ads_v5",
            "targetNodeCommunicationMode": "simplified"
        }
    }
}

資料平面：Pool - Patch 或 Update 屬性

資料平面提供了修補或更新選定集區屬性的功能。可用的 API 包括作為 Batch Data Plane API 或 SDK 一部分的 Pool - Patch API 或 Pool - Update Properties API。

Patch API 允許依照文件 (例如 startTask) 中所指定的內容來修補選定集區屬性。由於這項作業是 PATCH，因此只會更新要求中所指定的集區屬性。如果未將屬性指定為要求的一部分，則現有的值會保持未修改。

Update Properties API 允許依照文件中所指定的內容來選取更新集區屬性。此要求會完全取代現有的屬性，因此會移除該要求中未指定的任何屬性。

必須重新啟動計算節點才能使下列屬性的變更生效：

applicationPackageReferences
certificateReferences
startTask

若要更新 targetNodeCommunicationMode 屬性，必須將集區的大小調整為零個活動節點。

常見問題集

更新集區屬性後，我是否需要在集區內含有作用中節點時執行其他任何操作？

是的，對於可以在有作用中的節點的情況下更新的集區屬性，有些選定的屬性需要重新啟動計算節點才能生效。或者，集區可以縮小到零個節點以反映修改後的屬性。

當集區具有作用中的節點時，我是否可以修改集區上的受控識別集合？

是的，但您不應該。雖然 Batch 不會禁止對處於活動狀態的節點的集合進行變更，但我們建議避免這樣做，因為如果集區擴展時，這會導致身份集合的不一致。我們建議僅在集區的大小為零時更新此屬性。如需詳細資訊，請參閱設定受控識別一文。

下一步

深入了解可用的 Batch API 和工具。
了解如何檢查集區和節點是否有錯誤。