Überarbeitungen in azure API Management

GILT FÜR: Alle API Management-Ebenen

Mit Überarbeitungen können Sie Änderungen an Ihren APIs auf kontrollierte und sichere Weise vornehmen. Wenn Sie Änderungen vornehmen möchten, erstellen Sie eine neue Überarbeitung. Anschließend können Sie Ihre API bearbeiten und testen, ohne die API-Verbraucher zu stören. Wenn Sie fertig sind, aktualisieren Sie Ihre Überarbeitung. Gleichzeitig können Sie optional einen Eintrag im Änderungsprotokoll posten, um Ihre API-Verbraucher mit den von Ihnen vorgenommenen Änderungen auf dem neuesten Stand zu halten. Das Änderungsprotokoll wird in Ihrem Entwicklerportal veröffentlicht.

Hinweis

Das Entwicklerportal ist in der Stufe "Verbrauch" nicht verfügbar.

Mit Überarbeitungen haben Sie folgende Möglichkeiten:

• Nehmen Sie sicher Änderungen an Ihren API-Definitionen und -Richtlinien vor, ohne Ihre Produktions-API zu stören.
• Testen Sie Änderungen, bevor Sie sie veröffentlichen.
• Dokumentieren Sie die von Ihnen vorgenommenen Änderungen, damit Ihre Entwickler verstehen können, was neu ist.
• Führen Sie bei Problemen ein Rollback aus.

Beginnen Sie mit Überarbeitungen, indem Sie unsere exemplarische Vorgehensweise ausführen.

Zugriff auf bestimmte Revisionen

Auf jede Überarbeitung ihrer API kann mithilfe einer speziell gebildeten URL zugegriffen werden. Fügen Sie ;rev={revisionNumber} am Ende Der API-URL an, aber vor der Abfragezeichenfolge, um auf eine bestimmte Revision dieser API zuzugreifen. Sie können z. B. diese URL verwenden, um auf Revision 3 der customers API zuzugreifen:

https://apis.contoso.com/customers;rev=3/leads?customerId=123

Standardmäßig verfügt jede Revision über die gleichen Sicherheitseinstellungen wie die aktuelle Revision. Sie können die Richtlinien für eine bestimmte Überarbeitung absichtlich ändern, wenn Für jede Überarbeitung unterschiedliche Sicherheit angewendet werden soll. Sie können z. B. eine IP-Filterrichtlinie hinzufügen, um zu verhindern, dass externe Anrufer auf eine Überarbeitung zugreifen, die noch in der Entwicklung liegt.

Hinweis

Das ;rev={id} muss an die API-ID angefügt werden und nicht an den URI-Pfad.

Aktuelle Überarbeitung

Eine einzelne Revision kann als aktuelle Revision festgelegt werden. Diese Revision wird für alle API-Anforderungen verwendet, die keine explizite Revisionsnummer in der URL angeben. Sie können ein Rollback zu einer vorherigen Überarbeitung ausführen, indem Sie diese Überarbeitung als aktuell festlegen.

Sie können eine Überarbeitung mit dem Azure-Portal als aktuell festlegen. Wenn Sie PowerShell verwenden, können Sie das New-AzApiManagementApiRelease Cmdlet verwenden.

Beschreibung der Überarbeitungen

Wenn Sie eine Überarbeitung erstellen, können Sie eine Beschreibung für Ihre eigenen Nachverfolgungszwecke festlegen. Beschreibungen werden ihren API-Benutzern nicht angezeigt.

Wenn Sie eine Überarbeitung als aktuell festlegen, können Sie optional auch eine öffentliche Änderungsprotokollnotiz angeben. Das Änderungsprotokoll ist im Entwicklerportal enthalten, damit Ihre API-Benutzer es einsehen können. Sie können ihre Änderungsprotokollnotiz mithilfe des Update-AzApiManagementApiRelease PowerShell-Cmdlets ändern.

Vorsicht

Wenn Sie eine nicht aktuelle Überarbeitung einer API bearbeiten, können Sie die folgenden Eigenschaften nicht ändern:

• Name
• Typ
• Description
• Abonnement erforderlich
• API-Version
• API-Versionsbeschreibung
• Pfad
• Protokolle

Diese Eigenschaften können nur in der aktuellen Revision geändert werden. Wenn Ihre Bearbeitungen eine dieser Eigenschaften in einer nicht aktuellen Überarbeitung ändern, wird die Fehlermeldung Can't change property for non-current revision angezeigt.

Eine Überarbeitung offline nehmen

Eine Revision kann offline geschaltet werden, wodurch sie für Nutzer unzugänglich wird, selbst wenn diese versuchen, über die URL darauf zuzugreifen. Sie können eine Überarbeitung über das Azure-Portal als offline markieren.

Hinweis

Es wird empfohlen, Überarbeitungen offline zu nehmen, wenn Sie sie nicht zum Testen verwenden.

Versionen und Überarbeitungen

Versionen und Überarbeitungen sind unterschiedliche Features. Jede Version kann mehrere Überarbeitungen aufweisen, genau wie eine nichtversionierte API. Sie können Überarbeitungen verwenden, ohne Versionen zu verwenden, oder umgekehrt. In der Regel werden Versionen verwendet, um API-Versionen mit Breaking Changes abzugrenzen, während Revisionen für kleinere Änderungen und Nonbreaking Changes an einer API verwendet werden können.

Wenn Ihre Revision umfassende Änderungen enthält oder wenn Sie Ihre Revision formell in eine Beta-Testversion umwandeln möchten, können Sie aus einer Revision eine Version erstellen. Wählen Sie im Azure-Portal auf der Registerkarte "Überarbeitungen" die Option "Version aus Überarbeitung erstellen" aus.