Share via

Neuerungen in Azure VM Image Builder

  • Artikel

Gilt für: ✔️ Linux-VMs ✔️ Windows-VMs ✔️ Flexible Skalierungsgruppen ✔️ Einheitliche Skalierungsgruppen

Dieser Artikel enthält alle wichtigen API-Änderungen und Featureupdates für den Azure VM Image Builder(AIB)-Dienst.

Updates

Mai 2024

Breaking Change: Groß-/Kleinschreibung

Ab dem 21. Mai 2024 erzwingt azure VM Image Builder die API-Version 2024-02-01 und darüber hinaus die Groß-/Kleinschreibung für alle Felder. Dies bedeutet, dass die Groß-/Kleinschreibung von Buchstaben in Ihren API-Anforderungen exakt mit dem erwarteten Format übereinstimmen muss.

Wichtiger Hinweis für vorhandene Azure Image Builder-Benutzer

Wenn Sie ein vorhandener Benutzer von Azure VM Image Builder sind, stellen Sie sicher, dass diese Änderung sich nicht auf Ihre vorhandenen Ressourcen auswirkt. Die Durchsetzung der Groß-/Kleinschreibung gilt nur für neu erstellte Ressourcen mit API Version 2024-02-01 und höher. Ihre vorhandenen Ressourcen funktionieren ohne Änderungen weiterhin wie erwartet.

Wenn Probleme im Zusammenhang mit der Groß-/Kleinschreibung auftreten, lesen Sie bitte die aktualisierte API-Dokumentation von Azure Image Builder, um Anleitungen zu erhalten.

Bisher war die API des Azure Image Builder im Hinblick auf die Groß-/Kleinschreibung eher verwöhnend, aber die Präzision ist entscheidend. Stellen Sie beim Tätigen von API-Aufrufen sicher, dass Sie die richtige Groß-/Kleinschreibung für Feldnamen, Parameter und Werte verwenden. Wenn beispielsweise ein Feld den Namen "vmBoot" hat, müssen Sie "vmBoot" (nicht "VMBoot" oder "vmboot") verwenden.

Wenn Sie eine API-Anforderung an die API-Version 2024-02-01 von Azure Image Builder und darüber hinaus mit falschen Feldern oder nicht erkannten Feldern senden, lehnt der Dienst sie ab. Sie erhalten eine Fehlerantwort, die angibt, dass die Anforderung ungültig ist. Ein ähnlicher Fehler wie der folgende wird angezeigt:

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.

Die Fehlermeldung erwähnt ein "unbekanntes Feld" und leitet Sie zur offiziellen Dokumentation weiter: Erstellen Sie eine JSON-Vorlage für Azure Image Builder Bicep oder ARM.

Referenzieren des Swaggers von Azure Image Builder für API-Aufrufe

Verweisen Sie beim Aufrufen des Azure Image Builder-Diensts immer auf die Swagger-Dokumentation, die als endgültige Wahrheitsquelle für die API-Spezifikationen von Azure Image Builder dient. Während die öffentliche Dokumentation aktualisiert wurde, um die richtigen Groß- und Kleinschreibungs- und Feldnamen vor der API-Version einzuschließen, enthält die Swagger-Definition genaue Details zu jeder AIB-API, um sicherzustellen, dass Sie Aufrufe an den Dienst ordnungsgemäß ausführen.

Nachfolgend finden Sie eine Liste der Dokumentationsänderungen, die an die Feldnamen in API Version 2024-02-01 angepasst wurden:

In der Erstellen einer Azure Image Builder-Bicep- oder -ARM-JSON-Vorlage Dokumentation:

Felder aktualisiert:

  • Mehrere Erwähnungen von vmboot mit vmBoot ersetzt
  • Eine Erwähnung von imageVersionID mit imageVersionId ersetzt

Feld entfernt:

  • apiVersion: Es wird empfohlen, die Einbeziehung dieses Felds in Ihre Anforderungen zu vermeiden, da es nicht explizit in unserer API angegeben ist, sodass dies in Ihrer JSON-Vorlage zu Fehlern in Ihrem Imagebuild führen kann.

In der Dokumentation zu Azure VM Image Builder-Netzwerkoptionen:

Feld aktualisiert:

  • Eine Erwähnung von VirtualNetworkConfig mit vnetConfig ersetzt

Felder entfernt:

  • subnetName in der vnetConfig Eigenschaft – dieses Feld ist veraltet, und das neue Feld ist subnetId
  • resourceGroupName in der vnetConfig Eigenschaft – dieses Feld ist veraltet, und das neue Feld ist subnetId

So heften Sie sich an eine ältere Azure Image Builder-API-Version an

Wichtige Überlegungen zum Anheften an ältere API-Versionen

Das Anheften an eine ältere Azure Image Builder-API-Version kann Kompatibilität mit ihren vorhandenen Vorlagen bieten, wird jedoch aufgrund der folgenden Faktoren nicht empfohlen:

  • Veraltetes Risiko: Ältere API-Versionen sind möglicherweise veraltet.

  • Fehlende Features: Durch das Anheften an eine ältere API-Version verpassen Sie die neuesten Features und Verbesserungen, die in neueren Versionen eingeführt wurden. Diese Verbesserungen verbessern häufig die Leistung, Sicherheit und Funktionalität.

Wenn Sie aufgrund der neuen Regeln für die Groß-/Kleinschreibung keine Änderungen an den Eigenschaften in Ihren Imagevorlagen vornehmen möchten, haben Sie die Möglichkeit, Ihre Azure VM Image Builder-API-Aufrufe an eine frühere API-Version anzuheften. Auf diese Weise können Sie das vertraute Verhalten ohne Änderungen weiterhin verwenden.

Um die Kompatibilität mit ihren vorhandenen Vorlagen sicherzustellen, geben Sie beim Erstellen oder Aktualisieren einer Bildvorlage die gewünschte API-Version (z. B. api-version=2022-07-01) an, indem Sie den api-version Parameter in Ihren Dienstaufruf einschließen. Beispiel:

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