Versionen in Azure API Management

GILT FÜR: Alle API Management-Ebenen

Mit Versionen können Sie Gruppen verwandter APIs für Ihre Entwickler präsentieren. Sie können Versionen verwenden, um Breaking Changes in Ihrer API sicher zu verarbeiten. Clients können sich entschließen, Ihre neue API-Version zu verwenden, wenn sie bereit sind, während vorhandene Clients weiterhin eine ältere Version verwenden. Versionen werden über einen Versionsbezeichner (bei dem es sich um einen von Ihnen ausgewählten Zeichenfolgenwert handelt) unterschieden, und mit einem Versionsverwaltungsschema können Clients ermitteln, welche Version einer API verwendet werden soll. In diesem Artikel wird beschrieben, wie Versionen in der API-Verwaltung verwendet werden.

In den meisten Fällen kann jede API-Version als eigene unabhängige API angesehen werden. Zwei verschiedene API-Versionen können unterschiedliche Sätze von Vorgängen sowie unterschiedliche Richtlinien aufweisen.

Mit Versionen können Sie:

• Veröffentlichen Sie mehrere Versionen Ihrer API gleichzeitig.
• Verwenden Sie einen Pfad, eine Abfragezeichenfolge oder einen Header, um zwischen Versionen zu unterscheiden.
• Verwenden Sie einen beliebigen Zeichenfolgenwert, um Ihre Version zu identifizieren. Es kann sich um eine Zahl, ein Datum oder einen Namen handeln.
• Zeigen Sie Ihre API-Versionen im Entwicklerportal gruppiert an.
• Erstellen Sie eine neue Version einer vorhandenen (nicht versionsbasierten) API, ohne dass sich dies auf vorhandene Clients auswirkt.

Erste Schritte mit Versionen mithilfe einer exemplarischen Vorgehensweise

Versionsverwaltungsschemas

Unterschiedliche API-Entwickler haben unterschiedliche Anforderungen für die Versionsverwaltung. Azure API Management schreibt keinen einzelnen Ansatz für die Versionsverwaltung vor, sondern bietet stattdessen mehrere Optionen.

Pfadbasierte Versionsverwaltung

Wenn das Pfadversionsschema verwendet wird, muss der Versionsbezeichner für alle API-Anforderungen im URL-Pfad enthalten sein.

Zum Beispiel könnten https://apis.contoso.com/products/v1 und https://apis.contoso.com/products/v2 auf dieselbe products API, aber auf die Versionen v1 und v2 verweisen.

Das Format einer API-Anforderungs-URL, wenn Sie die pfadbasierte Versionsverwaltung verwenden, lautet https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}.

Headerbasierte Versionsverwaltung

Wenn das Headerversionsverwaltungsschema verwendet wird, muss der Versionsbezeichner in einen HTTP-Anforderungsheader für alle API-Anforderungen eingeschlossen werden. Sie können den Namen des HTTP-Anforderungsheaders angeben.

Sie können z. B. einen benutzerdefinierten Header mit dem Namen Api-Version erstellen, und Clients könnten v1 oder v2 im Wert dieser Kopfzeile angeben.

Auf Abfragezeichenfolgen basierende Versionsverwaltung

Wenn das Versionsverwaltungsschema der Abfragezeichenfolge verwendet wird, muss der Versionsbezeichner in einen Abfragezeichenfolgenparameter für alle API-Anforderungen eingeschlossen werden. Sie können den Namen des Abfragezeichenfolgenparameters angeben.

Das Format einer API-Anforderungs-URL, wenn Sie abfragezeichenfolgenbasierte Versionsverwaltung verwenden, lautet https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}.

Zum Beispiel könnten https://apis.contoso.com/products?api-version=v1 und https://apis.contoso.com/products?api-version=v2 auf dieselbe products API, aber auf die Versionen v1 und v2 verweisen.

Hinweis

Abfrageparameter sind in der servers Eigenschaft einer OpenAPI-Spezifikation nicht zulässig. Wenn Sie eine OpenAPI-Spezifikation aus einer API-Version exportieren, wird keine Abfragezeichenfolge in der Server-URL angezeigt.

Originalversionen

Wenn Sie einer nicht versionsgesteuerten API eine Version hinzufügen, wird automatisch eine Original Version erstellt und reagiert auf die Standard-URL, ohne dass ein Versionsbezeichner angegeben ist. Die Original Version stellt sicher, dass alle vorhandenen Aufrufer vom Hinzufügen einer Version nicht betroffen sind. Wenn Sie eine neue API mit von Anfang an aktivierten Versionen erstellen, wird keine Original Version erstellt.

Darstellung von Versionen

Die API-Verwaltung verwaltet eine Ressource namens "Versionssatz", die eine Reihe von Versionen für eine einzelne logische API darstellt. Ein Versionssatz enthält den Anzeigenamen der versionsspezifischen API und das Versionsverwaltungsschema, das verwendet wird , um Anforderungen an angegebene Versionen zu leiten.

Jede Version einer API wird als eigene API-Ressource verwaltet und einem Versionssatz zugeordnet. Ein Versionssatz kann APIs mit unterschiedlichen Vorgängen oder Richtlinien enthalten. Möglicherweise nehmen Sie erhebliche Änderungen zwischen den Versionen in einem Satz vor.

Das Azure-Portal erstellt Versionssätze für Sie. Sie können den Namen und die Beschreibung für eine Im Azure-Portal festgelegte Version ändern.

Ein Versionssatz wird automatisch gelöscht, wenn die endgültige Version gelöscht wird.

Sie können Versionssätze direkt anzeigen und verwalten, indem Sie Azure CLI, Azure PowerShell, Ressourcen-Manager-Vorlagen oder die Azure Resource Manager-API verwenden.

Hinweis

Alle Versionen in einem Versionssatz weisen das gleiche Versionsverwaltungsschema auf. Sie basiert auf dem Versionsverwaltungsschema, das beim ersten Hinzufügen einer Version zu einer API verwendet wird.

Migrieren einer nicht versionsbasierten API zu einer versionsbasierten API

Wenn Sie das Azure-Portal verwenden, um die Versionsverwaltung für eine vorhandene API zu aktivieren, werden die folgenden Änderungen an Ihren API-Verwaltungsressourcen vorgenommen:

• Ein neuer Versionssatz wird erstellt.
• Die vorhandene Version wird verwaltet und als Original API-Version konfiguriert. Die API ist mit dem Versionssatz verknüpft, aber ein Versionsbezeichner muss nicht angegeben werden.
• Die neue Version wird als neue API erstellt und mit dem Versionssatz verknüpft. Ein Versionsverwaltungsschema und ein Bezeichner müssen für den Zugriff auf die neue API verwendet werden.

Versionen und Überarbeitungen

Versionen und Überarbeitungen sind unterschiedliche Features. Jede Version kann mehrere Überarbeitungen haben, genau wie eine nicht versionsbasierte API. Sie können Überarbeitungen verwenden, ohne Versionen zu verwenden, oder umgekehrt. In der Regel werden Versionen verwendet, um API-Versionen mit grundlegenden Änderungen zu trennen, und Überarbeitungen können für kleinere und nicht-unterbrechende Änderungen an einer API verwendet werden.

Wenn Sie feststellen, dass Ihre Revision Breaking Changes aufweist, oder wenn Sie Ihre Revision formal in eine Beta-/Testversion umwandeln möchten, können Sie eine Version aus einer Revision erstellen. Wählen Sie im Azure-Portal im Kontextmenü (...) auf der Registerkarte "Überarbeitungen" die Option "Version aus dieser Überarbeitung erstellen" aus.

Entwicklerportal

Das Entwicklerportal listet jede Version einer API separat auf:

In den Details zu einer API können Sie auch eine Liste aller Versionen der API anzeigen. Eine Original Version wird ohne Versionsbezeichner angezeigt:

Tipp

Sie müssen einem Produkt API-Versionen hinzufügen, um sie im Entwicklerportal sichtbar zu machen.