Versionsverwaltungsrichtlinie für Azure-Dienste, SDKs und CLI-Tools

  • Artikel

Mit den meisten Azure-Diensten können Sie ihre Ressourcen programmgesteuert mit REST-APIs steuern und verwalten. Dienste werden durch neue veröffentlichte Versionen ihrer APIs mit unterschiedlichen Verträgen weiterentwickelt, die neue Features hinzufügen und/oder ihr Verhalten ändern.

In diesem Artikel wird die Richtlinie beschrieben, die der Azure-Dienst, das SDK und die CLI-Teams für die Versionsverwaltung der Azure REST-APIs verwenden. Während Azure-Teams alle Anstrengungen unternehmen, diese Richtlinie einzuhalten, können gelegentlich Abweichungen auftreten.

Dienstversionsverwaltung

Jede veröffentlichte Version einer API wird durch einen Datumswert im YYYY-MM-DD Format identifiziert, der als ".api-version Neuere Versionen weisen spätere Datumsangaben auf.

Für alle API-Vorgänge müssen Clients eine gültige API-Version für den Dienst über den api-version Abfragezeichenfolgenparameter in der URL angeben. Beispiel: https://management.azure.com/subscriptions?api-version=2020-01-01 Client-SDKs und -Tools enthalten den api-version Wert automatisch. Weitere Überlegungen finden Sie im Abschnitt "Client-SDKs und -Dienstversionen " weiter unten in diesem Artikel.

In der Regel werden veröffentlichte Dienstversionen seit vielen Jahren Standard wieder verfügbar und unterstützt, auch wenn neuere Versionen verfügbar sind. In den meisten Fällen sollten Sie nur eine neue Dienstversion innerhalb des vorhandenen Codes einführen, um neue Features nutzen zu können.

Stabile Versionen

Die meisten veröffentlichten Dienstversionen sind stabile Versionen. Stabile Versionen sind abwärtskompatibel, d. h. jeder Code, den Sie schreiben, der auf einer Version eines Diensts basiert, kann eine neuere stabile Version übernehmen, ohne dass Codeänderungen an Standard Tainness oder vorhandenen Funktionen erforderlich sind.

Umbruch von Änderungsversionen

Eine bahnbrechende Änderungsversion eines Diensts ist nicht abwärtskompatibel. Die Einführung einer bahnbrechenden Änderungsversion in vorhandenem Clientcode erfordert möglicherweise Codeänderungen, um sicherzustellen, dass sich der Client genauso verhält wie bei der Zielbestimmung für die vorherige Version.

Aktuelle Änderungsversionen sind selten, über die Dokumentation angekündigt und stehen in der Regel vor der Veröffentlichung einer Vorschauversion. Die Veröffentlichung einer endgültigen Änderungsversion kann dazu führen, dass vorhandene stabile Versionen zurückversetzt werden, die mindestens drei Jahre nach der endgültigen Änderungsversion verfügbar Standard sein werden. Bei änderungen, die aufgrund von Sicherheits- oder Complianceproblemen veröffentlicht wurden, können vorhandene stabile Dienstversionen Standard je nach Schweregrad des Problems ein Jahr oder weniger verfügbar sein.

Aufgrund der raschen Innovation und Entwicklungen in KI können KI-gesteuerte Dienste eine geringere Mindestverfügbarkeit von einem Jahr haben. Jeder Dienst veröffentlicht seine richtlinienumbruchenden Änderungen.

Jeder von einer Nicht-Microsoft-Komponente abhängige Azure-Dienst kann seine Supportrichtlinie verkleinern, um der richtlinie der Komponente zu entsprechen. Jede unterbrechungsbedingte Änderung wird mit der Richtlinie des Komponentenanbieters verknüpft, die das Datum anzeigt, an dem die Komponente nicht mehr unterstützt wird.

Vorschauversionen

Gelegentlich veröffentlicht Microsoft eine Vorschauversion eines Diensts, um Feedback zu vorgeschlagenen Änderungen und neuen Features zu sammeln. Vorschaudienstversionen werden mit dem Suffix -preview in ihrem api-version Suffix identifiziert , 2022-07-07-previewz. B. .

Sofern nicht explizit beabsichtigt, eine wesentliche Änderung der vorherigen stabilen Version einzuführen, enthalten neue Vorschauversionen alle Features der neuesten stabilen Version und fügen neue Vorschaufeatures hinzu. Zwischen Vorschauversionen kann ein Dienst jedoch alle neu hinzugefügten Vorschaufeatures unterbrechen.

Vorschauen sind nicht für die langfristige Verwendung vorgesehen. Sobald eine neue stabile oder Vorschauversion eines Diensts verfügbar wird, werden vorhandene Vorschauversionen ab der Verfügbarkeit der neuen Version bis zu 90 Tage möglicherweise nicht mehr verfügbar. Verwenden Sie Vorschauversionen nur in Situationen, in denen Sie aktiv für neue Dienstfeatures entwickeln und bereit sind, eine neue, nicht preview-Version in Kürze nach der Veröffentlichung einzuführen. Wenn einige Features aus einer Vorschauversion in einer neuen stabilen Version veröffentlicht werden, werden Features, die sich noch in der Vorschau befinden Standard, in der Regel in einer neuen Vorschauversion veröffentlicht.

Client-SDKs und Dienstversionen

Die Azure-SDKs zielen darauf ab, die Dienstversionsverwaltung als Problem beim Schreiben von Code zu beseitigen. Jedes SDK besteht aus Clientbibliotheken, einer für jeden Dienst, und jede Clientbibliotheksversion zielt auf eine einzelne Version des Diensts ab, auf dem er basiert.

Wenn Sie ein SDK für den Zugriff auf einen Azure-Dienst verwenden, erfordert die Nutzung neuer Versionen und Features in der Regel ein Upgrade der von der Anwendung verwendeten Clientbibliotheksversion. Neue stabile Versionen von Diensten werden von neuen Point Releases von Clientbibliotheken begleitet. Für neue, grundlegende Änderungsversionen werden neue Clientbibliotheken entweder als Point Release-Versionen oder Hauptversionsversionen veröffentlicht. Die Art der Veröffentlichung hängt von der Art der Änderung des Diensts ab, und die Art und Weise, wie die Bibliothek sie aufnehmen kann. Nur Clientbibliotheken der Betaversion verwenden Vorschaudienstversionen.

SDK-Clientbibliotheken unterstützen manuelle Außerkraftsetzung der Dienstversion. Das Überschreiben der Standarddienstversion einer Clientbibliothek ist ein erweitertes Szenario und kann zu unerwartetem Verhalten führen. Wenn Sie dieses Feature verwenden, testen Sie Ihre Anwendung sorgfältig, um sicherzustellen, dass sie wie gewünscht funktioniert.

Azure-Befehlszeilentools

Wie bei den SDKs sind die Azure-Befehlszeilentools (einschließlich azure CLI und Azure PowerShell) so konzipiert, dass die Nutzung von Azure-Verwaltungsdiensten ohne Rücksicht auf Versionen möglich ist. Für den Zugriff auf neue Dienstfeatures ist häufig eine neue Version eines Tools erforderlich. Neue abwärtskompatible Toolversionen werden monatlich veröffentlicht. Versionen mit unterbrechungsrelevanten Änderungen werden ungefähr zweimal jährlich veröffentlicht oder müssen wichtige Sicherheitsprobleme beheben.

Die Azure-Befehlszeilentools können gelegentlich Vorschaufeatures verfügbar machen. Diese Befehle sind mit einer Preview Bezeichnung gekennzeichnet und geben eine Warnung aus, die auf eingeschränkte Unterstützung und potenzielle Änderungen in zukünftigen Toolversionen hinweist.

Nächste Schritte