你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure VM 映像生成器中的新增功能

项目
05/31/2024

适用于：✔️ Linux VM ✔️ Windows VM ✔️ 灵活规模集 ✔️ 统一规模集

本文包含了 Azure VM 映像生成器 (AIB) 服务的所有主要 API 更改和功能更新。

更新

2024 年 5 月

中断性变更：区分大小写

从 2024 年 5 月 21 日起，Azure VM 映像生成器的 API 版本 2024-02-01 及更高版本将对所有字段强制区分大小写。这意味着，API 请求中的字母大小写必须与预期格式完全匹配。

重要

面向现有 Azure 映像生成器用户的重要说明

Azure VM 映像生成器的现有用户请放心，此更改不会影响现有资源。强制区分大小写仅适用于使用 API 版本 2024-02-01 及更高版本新创建的资源。现有资源将继续按预期运行，无需进行任何更改。

如果遇到与区分大小写相关的任何问题，请参阅 Azure 映像生成器的更新后的 API 文档以获得指导。

以前，Azure 映像生成器的 API 在大小写方面更为宽容，但从现在开始，精准率至关重要。在进行 API 调用时，请确保对字段名称、参数和值使用正确的大小写。例如，如果字段名为“vmBoot”，则必须使用“vmBoot”（而不是“VMBoot”或“vmboot”）。

如果将 API 请求发送到 Azure 映像生成器的 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 映像生成器 Bicep 或 ARM 模板 JSON 模板。

注意

参考 Azure 映像生成器的 Swagger 进行 API 调用

在调用 Azure 映像生成器服务时，请始终参考 Swagger 文档，该文档是 Azure 映像生成器 API 规范的权威来源。虽然公共文档已经更新，包含了 API 发布前的正确大小写和字段名称，但 Swagger 定义了包含每个 AIB API 的精确细节，以确保用户正确调用服务。

下面是为了与 API 版本 2024-02-01 中的字段名称匹配而对文档进行的更改列表：

在创建 Azure 映像生成器 Bicep 或 ARM 模版 JSON 模板文档中：

已更新的字段：

将多处提及的 vmboot 替换为 vmBoot
将一处提及的 imageVersionID 替换为 imageVersionId

已删除的字段：

apiVersion：建议避免将此字段包含在请求中，因为它未在 API 中显式指定，因此，将其包含在 JSON 模板中可能会导致映像生成中出现错误。

在 Azure VM 映像生成器网络选项文档中：

已更新的字段：

将一处提及的 VirtualNetworkConfig 替换为 vnetConfig

已删除的字段：

vnetConfig 属性中的 subnetName - 此字段已弃用，新字段为 subnetId
vnetConfig 属性中的 resourceGroupName - 此字段已弃用，新字段为 subnetId

如何固定到较旧的 Azure 映像生成器 API 版本

固定到较旧的 API 版本的重要注意事项

固定到较旧的 Azure 映像生成器 API 版本后，可以与现有模板兼容，但鉴于以下考虑因素，不建议这样做：

弃用风险：较旧的 API 版本最终可能被弃用。

缺少功能：固定到较旧的 API 版本后，会错过较新版本中引入的最新功能和改进。这些增强功能通常会增强性能、安全性和功能。

如果想要避免由于新的区分大小写规则而更改映像模板中的属性，可以选择将 Azure VM 映像生成器 API 调用固定到以前的 API 版本。这样就可以继续使用熟悉的行为，而无需进行任何修改。

为了确保与现有模板的兼容性，在创建或更新映像模板时，请通过在调用服务时包含 api-version 参数来指定所需的 API 版本（例如 api-version=2022-07-01）。示例：

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 映像生成器的交互方式。有关详细信息，请参阅独立映像生成。

重要

确保订阅已注册 Microsoft.ContainerInstance 提供程序，并且没有阻止部署 Azure 容器实例资源的策略。此外，请确保配额可用于 Azure 容器实例资源。

2023 年 4 月

Azure 映像生成器添加了新的门户功能。在 Azure 门户中搜索“映像模板”，然后单击“创建”。还可以在此处开始在门户中生成和验证自定义映像。

API 版本

版本 2024-02-01

改进

新的 autoRun 属性，可用于在模板创建或更新时运行映像生成。有关详细信息，请参阅属性：autoRun。
新的 managedResourceTags 属性，可用于将标记应用于 Azure 映像生成器服务在映像生成期间在暂存资源组中创建的资源。有关详细信息，请参阅属性：managedResourceTags。
新的 containerInstanceSubnetId 属性，可用于指定要在其上为独立生成部署 Azure 容器实例的子网。仅当 subnetId 也被指定并且必须与 subnetId 中指定的子网位于同一虚拟网络中时，才能指定此字段。有关详细信息，请参阅使用自己的生成 VM 子网并使用自己的 ACI 子网。
添加了对更新 vmProfile 属性的支持，包括以下字段：
- vmSize
- osDiskSizeGB
- userAssignedIdentities
- vnetConfig
  - subnetId
  - containerInstanceSubnetId 有关 vmProfile 属性的详细信息，请参阅 vmProfile。

更改 API 版本 2024-02-01 引入了一项中断性变更，用于对所有字段强制区分大小写。这意味着，API 请求中的字母大小写必须与预期格式完全匹配。如果将 API 请求发送到 Azure 映像生成器的 API 版本 2024-02-01 及更高版本，而大小写不正确或无法识别字段，服务将拒绝该请求。用户将收到一个错误响应，指示请求无效。有关详细信息，请参阅中断性变更：区分大小写。

版本 2023-07-01

即将推出

支持更新 Azure Compute Gallery 分发目标。

更改

新建 errorHandling 属性。此属性使用户能够更好地控制映像生成过程中发生的错误的处理方式。有关详细信息，请参阅 errorHandling

版本 2022-07-01

改进

添加了对使用 Azure Compute Gallery 中存储的最新映像版本作为映像模板源的支持
添加了 versioning 以支持为映像分发生成版本号。有关详细信息，请参阅属性：版本控制
添加了在分发到 Azure Compute Gallery 时对每区域配置的支持。有关详细信息，请参阅 Distribute:targetRegions
添加了新的“文件”验证类型。有关详细信息，请参阅验证属性
VHD 现在可以分发到自定义存储帐户中的自定义 Blob 或容器。有关详细信息，请参阅分发：VHD
添加了对于使用直接共享库映像作为映像模板源的支持

更改

库分发现已弃用 replicationRegions。有关详细信息，请使用 gallery-replicated-regions
现在可以将 VHD 分发到自定义存储帐户中的自定义 Blob 或容器
添加了 targetRegions 数组并仅应用于“SharedImage”类型分发。有关 targetRegions 的详细信息，请参阅 Azure Compute Gallery
添加了对于使用直接共享库映像作为映像模板源的支持。直接共享库目前处于预览状态。
触发器现在以公共预览版提供，用于设置自动映像生成。有关详细信息，请参阅如何使用 AIB 触发器

版本 2022-02-14

改进

验证支持
- Shell (Linux)：脚本或内联
- PowerShell (Windows)：脚本或内联、特权运行、以系统身份运行
- 仅限源验证模式
自定义暂存资源组支持

版本 2021-10-01

中断性变更

API 版本 2021-10-01 引入了对错误架构的更改，该架构将成为每个未来 API 版本的一部分。如果有任何 Azure VM 映像生成器自动化，请注意切换到 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 MSI（新增）。
支持自定义代理 VM 大小（新增）。

版本 2020-02-14

改进

添加了对从以下源创建映像的支持：
- 托管映像
- Azure Compute Gallery
- 平台映像存储库（包括平台映像购买计划）
添加了对以下自定义项的支持：
- Shell (Linux)：脚本或内联
- PowerShell (Windows)：脚本或内联、特权运行、以系统身份运行
- 文件（Linux 和 Windows）
- Windows 重启 (Windows)
- Windows 更新 (Windows)：搜索条件、筛选器以及更新限制
添加了对以下分布类型的支持：
- VHD（虚拟硬盘）
- 托管映像
- Azure Compute Gallery
其他功能：
- 支持客户使用自己的虚拟网络（新增）
- 支持客户自定义生成 VM（VM 大小、OS 磁盘大小）（新增）
- 支持用户分配的 Microsoft Windows Installer (MSI)（用于自定义/分发步骤）（新增）
- 支持 Gen2 映像（新增）

预览版 API

以下 API 已被弃用，但仍受支持：

版本 2019-05-01-preview

后续步骤

详细了解 VM 映像生成器。

通过