Azure VM Image Builder 的新功能

發行項
05/11/2024

適用於： ✔️ Linux VM ✔️ Windows VM ✔️ 彈性擴展集 ✔️ 統一擴展集

本文包含 Azure VM Image Builder (AIB) 服務的所有主要 API 變更和功能更新。

更新

2024 年 5 月

重大變更：區分大小寫

從 2024 年 5 月 21 日起，Azure VM 映射產生器的 API 版本 2024-02-01 及更新版本將會對所有字段強制執行區分大小寫。這表示 API 要求中的字母大寫必須完全符合預期的格式。

現有 Azure Image Builder 使用者的重要注意事項

如果您是 Azure VM Image Builder 的現有使用者，請放心，這項變更不會影響現有的資源。區分大小寫強制僅適用於使用 API 2024-02-01 版和更新版本新建立的資源。您現有的資源將繼續如預期般運作，而不需要進行任何變更。

如果您遇到任何與區分大小寫相關的問題，請參閱 Azure Image Builder 的更新 API 檔以取得指引。

先前，Azure Image Builder 的 API 在案例方面更寬容，但向前邁進，精確度至關重要。進行 API 呼叫時，請確定您使用正確的功能變數名稱、參數和值大寫。例如，如果欄位名為「vmBoot」，您必須使用「vmBoot」（而非 “VMBoot” 或 “vmboot” ）。

如果您將 API 要求傳送至 Azure Image Builder 的 API 版本 2024-02-01 和更新版本，且大小寫不正確或無法辨識的字段，服務將會拒絕它。您會收到錯誤回應，指出要求無效。錯誤看起來會像這樣：

Unmarshalling entity encountered error: unmarshalling type *v2024_02_01.ImageTemplate: struct field Properties: unmarshalling type *v2024_02_01.ImageTemplateProperties: struct field Optimize: unmarshalling type *v2024_02_01.ImageTemplatePropertiesOptimize: unmarshalling type *v2024_02_01.ImageTemplatePropertiesOptimize, unknown field \"vmboot\". There is an issue with the syntax with the JSON template you are submitting. Please check the JSON template for syntax and grammar. For more information on the syntax and grammar of the JSON template, visit http://aka.ms/azvmimagebuildertmplref.

錯誤訊息會提及「未知的欄位」，並引導您前往官方檔：建立 Azure Image Builder Bicep 或 ARM 範本 JSON 範本。

參考適用於 API 呼叫的 Azure Image Builder 的 Swagger

對 Azure Image Builder 服務進行呼叫時，請一律參考 Swagger 檔，其可作為 Azure Image Builder API 規格的明確真相來源。雖然公開檔已更新為在 API 發行之前包含適當的大小寫和功能變數名稱，但 Swagger 定義包含每個 AIB API 的精確詳細數據，以確保您正確地呼叫服務。

以下是為了符合 API 2024-02-01 版功能變數名稱所做的文件變更清單：

在建立 Azure Image Builder Bicep 或 ARM 範本 JSON 範本檔中：

欄位已更新：

已將的幾個提及 vmboot 取代為 vmBoot
已將的一個提及 imageVersionID 取代為 imageVersionId

欄位已移除：

apiVersion：建議您避免在您的要求中包含此欄位，因為它未在 API 中明確指定，因此在您的 JSON 範本 中包含它可能會導致 映像建置發生錯誤。

在 Azure VM 映像產生器網路選項檔中：

欄位已更新：

已將的一個提及 VirtualNetworkConfig 取代為 vnetConfig

已移除欄位：

subnetName 在屬性中 vnetConfig – 此欄位已被取代，而新欄位為 subnetId
resourceGroupName 在屬性中 vnetConfig – 此欄位已被取代，而新欄位為 subnetId

如何釘選到較舊的 Azure 映射產生器 API 版本

釘選至舊版 API 的重要考慮

釘選至較舊的 Azure Image Builder API 版本可以提供與現有範本的相容性，但不建議使用，原因如下：

淘汰風險：舊版 API 版本最終可能已被取代。

遺漏功能：釘選至較舊的 API 版本，您會錯過較新版本中引進的最新功能和改進功能。這些增強功能通常會改善效能、安全性和功能。

如果您想要避免因為新的區分大小寫規則而變更映像範本中的屬性，您可以選擇將 Azure VM 映射產生器 API 呼叫釘選到先前的 API 版本。這可讓您在不進行任何修改的情況下繼續使用熟悉的行為。

若要確保與現有範本的相容性，請在建立或更新映像範本時指定所需的 API 版本（例如 api-version=2022-07-01），方法是在呼叫服務時包含 api-version 參數。範例：

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.VirtualMachineImages/imageTemplates/{imageTemplateName}?api-version=2022-07-01

az resource create \
    --api-version=2022-07-01 \
    --resource-group <resourceGroupName> \
    --properties <jsonResource> \
    --is-full-object \
    --resource-type Microsoft.VirtualMachineImages/imageTemplates \
    -n <imageTemplateName>

New-AzResourceGroupDeployment -ResourceGroupName <resourceGroupName> -TemplateFile <templateFilePath> -TemplateParameterObject @{"api-version" = "2022-07-01"; "imageTemplateName" = <imageTemplateName>; "svclocation" = <location>}

測試您的程序代碼

釘選到較舊的 API 版本之後，請測試您的程式代碼，以確認其行為如預期般運作。請確定您現有的範本會繼續正常運作。

2023 年 11 月

Azure 映像產生器會以階段方式使用 Azure 容器執行個體來啟用隔離式映像組建。預計將於 2024 年初推出。您現有的映像範本將繼續運作，而且您建立或組建新映像範本的方式不會有任何變更。

您可能會觀察到暫存資源群組中暫時出現一組不同的暫時性 Azure 資源，但這不會影響您的實際組建或您與 Azure Image Builder 互動的方式。如需詳細資訊，請參閱隔離式映像建置。

重要

請確定您的訂用帳戶已註冊 Microsoft.ContainerInstance 提供者，而且沒有任何原則封鎖 Azure 容器執行個體資源的部署。也請確定 Azure 容器執行個體資源有可用的配額。

2023 年 4 月

已為 Azure Image Builder 新增入口網站功能。在 Azure 入口網站中搜尋「影像範本」，然後按一下 [建立]。您也可以在這裡開始使用，並在入口網站內建置和驗證自訂映像。

API 發行版本

2023-07-01 版

即將推出

支援更新 Azure Compute Gallery 散發目標。

變更

新的 errorHandling 屬性。此屬性可讓使用者更充分掌控在映像組建流程期間如何處理錯誤。如需詳細資訊，請參閱 errorHandling

2022-07-01 版

改善

已新增支援，以使用儲存在 Azure Compute Gallery 中的最新映像版本作為映像範本的來源
已新增 versioning，以支持產生映像散發的版本號碼。如需詳細資訊，請參閱屬性：版本設定
已新增散發至 Azure Compute Gallery 時每個區域設定的支援。如需詳細資訊，請參閱 Distribute:targetRegions
已新增全新 'File' 驗證類型。如需詳細資訊，請參閱驗證屬性
VHD 現在可以散發至自訂儲存體帳戶中的自訂 Blob 或容器。如需詳細資訊，請參閱散發：VHD
已新增使用 Direct Shared Gallery 映像作為映像範本來源的支援

變更

replicationRegions 現已不再用於資源庫散發。如需詳細資訊，請使用 gallery-replicated-regions
VHD 現在可以散發至自訂儲存體帳戶中的自訂 Blob 或容器
targetRegions 陣列只新增並套用至 "SharedImage" 類型散發。如需 targetRegions 的詳細資訊，請參閱 Azure Compute Gallery
已新增使用 Direct Shared Gallery 映像作為映像範本來源的支援。直接共用資源庫目前處於預覽狀態
觸發程序現在可在公開預覽中取得，以設定自動映像組建。如需詳細資訊，請參閱如何使用 AIB 觸發程序

版本 2022-02-14

改善

驗證支援
- Shell (Linux)：指令碼或內嵌
- PowerShell (Windows)：指令碼或內嵌、以更高權限執行、以系統身分執行
- 僅限來源驗證模式
自訂的暫存資源群組支援

版本 2021-10-01

重大變更

API 版本 2021-10-01 引進了錯誤結構描述的變更，該結構描述將會成為未來每個 API 發行版本的一部分。如果您有任何 Azure VM Image Builder 自動化，在切換到 API 2021-10-01 或更新版本時，請注意新的錯誤輸出。建議您在切換至最新的 API 版本之後，不要還原為舊版，因為這麼做會導致必須再次變更自動化才能產生較早的錯誤結構描述。我們沒有打算在未來發行版本中再次變更錯誤結構描述。

2020-02-14 和更早版本的錯誤輸出

{ 
  "code": "ValidationFailed",
  "message": "Validation failed: 'ImageTemplate.properties.source': Field 'imageId' has a bad value: '/subscriptions/subscriptionID/resourceGroups/resourceGroupName/providers/Microsoft.Compute/images/imageName'. Please review  http://aka.ms/azvmimagebuildertmplref  for details on fields requirements in the Image Builder Template." 
}

2021-10-01 和更早版本的錯誤輸出

{ 
  "error": {
    "code": "ValidationFailed", 
    "message": "Validation failed: 'ImageTemplate.properties.source': Field 'imageId' has a bad value: '/subscriptions/subscriptionID/resourceGroups/resourceGroupName/providers/Microsoft.Compute/images/imageName'. Please review  http://aka.ms/azvmimagebuildertmplref  for details on fields requirements in the Image Builder Template." 
  }
}

改善

已新增組建 VM MSIs 的支援。
已新增 Proxy VM 大小自訂的支援。

版本 2020-02-14

改善

已新增從下列來源建立映像的支援：
- 受控映像
- Azure Compute Gallery
- 平台映像存放庫 (包括平台映像購買方案)
已新增下列自訂的支援：
- Shell (Linux)：指令碼或內嵌
- PowerShell (Windows)：指令碼或內嵌、以更高權限執行、以系統身分執行
- 檔案 (Linux 和 Windows)
- Windows 重新開機 (Windows)
- Windows Update (Windows)：具有搜尋準則、篩選條件和更新限制
已新增下列散發類型的支援：
- VHD (虛擬硬碟)
- 受控映像
- Azure Compute Gallery
其他功能：
- 已針對客戶使用自己的虛擬網路新增支援
- 已新增客戶自訂組建 VM (VM 大小、作業系統磁碟大小) 的支援
- 已新增使用者指派 Microsoft Windows Installer (MSI) (自訂/散發步驟的支援)
- 已新增 Gen2 映像的支援

預覽 API

已取代下列 API，但仍支援：

版本 2019-05-01-預覽

下一步

深入了解 VM Image Builder。

共用方式為