Migrieren einer nicht in ein VNet eingefügten API Management-Instanz zur stv2-Computeplattform

GILT FÜR: Entwickler | Basic | Standard | Premium

Dieser Artikel enthält Schritte zum direkten Migrieren einer API Management-Instanz, die auf der stv1-Computeplattform gehostet wird, zur stv2-Plattform, wenn die Instanz nicht in ein externes oder internes VNet eingefügt (bzw. in einem solchen bereitgestellt) wird. Migrieren Sie für dieses Szenario Ihre Instanz mithilfe des Azure-Portals oder unter Verwendung der REST-API zum Migrieren zu stv2. Ob dies erforderlich ist, erfahren Sie hier.

Falls Sie eine in ein VNet eingefügte API Management-Instanz migrieren müssen, die auf der stv1-Plattform gehostet wird, lesen Sie Migrieren einer in ein VNet eingefügten API Management-Instanz zur stv2-Plattform.

Was geschieht während der Migration?

Die Migration der API Management-Plattform von stv1 zu stv2 umfasst lediglich die Aktualisierung der zugrunde liegenden Computeressource und hat keine Auswirkungen auf die in der Speicherebene gespeicherte Dienst-/API-Konfiguration. Für eine Instanz, die nicht in einem VNet bereitgestellt wird, gilt Folgendes:

• Sie können wählen, ob sich die VIP-Adresse der Instanz ändert oder ob die ursprüngliche VIP-Adresse erhalten bleibt.
• Der Upgradeprozess umfasst das Erstellen einer neuen Computeressource parallel zur alten Computeressource.
• Der API Management-Status im Portal lautet Wird aktualisiert.
• Wenn Sie die VIP-Adresse beibehalten möchten, umfasst die Migration einen zusätzlichen Schritt, um die VIP von der alten zur neuen Computeressource zu migrieren. Während dieses Vorgangs reagieren die APIs nicht.
• Azure verwaltet das Verwaltungsendpunkt-DNS und aktualisiert die neue Computeressource bei einer erfolgreichen Migration sofort.
• Das Standardgateway und das Portal-DNS verweisen sofort auf die neue Computeressource.
• Wenn Ihre API Management-Instanz eine neue VIP-Adresse erhalten soll, müssen Sie Netzwerkabhängigkeiten aktualisieren, um die neue VIP-Adresse zu verwenden.

Voraussetzungen

• Die API Management-Instanz, die auf der stv1-Computeplattform gehostet wird. Informationen zur Bestätigung, dass Ihre Instanz auf der stv1-Plattform gehostet wird, finden Sie unter Wie finde ich heraus, welche Plattform meine API Management-Instanz hostet?.

• Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.

  

• Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.

  • Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.

  • Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.

  • Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

Migrieren der Instanz zur stv2-Plattform

Optionen für die öffentliche IP-Adresse

Sie können auswählen, ob sich die virtuelle IP-Adresse von API Management ändert oder ob die ursprüngliche virtuelle IP erhalten bleibt.

• Neue virtuelle IP-Adresse: Wenn Sie sich für diesen Modus entscheiden, reagieren API-Anforderungen während der Migration weiterhin. Die Infrastrukturkonfiguration (z. B. benutzerdefinierte Domänen, Standorte und Zertifizierungsstellenzertifikate) wird 30 Minuten lang gesperrt. Nach der Migration müssen Sie alle Netzwerkabhängigkeiten einschließlich DNS, Firewallregeln und VNets aktualisieren, um die neue VIP-Adresse zu verwenden.

• IP-Adresse beibehalten: Wenn Sie die virtuelle IP beibehalten, reagieren API-Anforderungen ungefähr 15 Minuten lang nicht, während die IP-Adresse zur neuen Infrastruktur migriert wird. Die Infrastrukturkonfiguration (z. B. benutzerdefinierte Domänen, Standorte und Zertifizierungsstellenzertifikate) wird 45 Minuten lang gesperrt. Nach der Migration ist keine weitere Konfiguration erforderlich.

Vorkonfigurierte IP-Adresse für die Migration

Für API Management-Instanzen, die über eine öffentliche IP-Adresse erreichbar sind, erstellt API Management vorab eine öffentliche IP-Adresse für den Migrationsprozess. Suchen Sie die vorab erstellte IP-Adresse in der JSON-Ausgabe der Eigenschaften Ihrer API Management-Instanz. Unter customProperties ist die vorab erstellte IP-Adresse der Wert der Eigenschaft Microsoft.WindowsAzure.ApiManagement.Stv2MigrationPreCreatedIps. Bei einer Bereitstellung mit mehreren Regionen ist der Wert eine durch Trennzeichen getrennte Liste der vorab erstellten IP-Adressen.

Verwenden Sie die vorab erstellte IP-Adresse (bzw. die Adressen), um den Migrationsprozess zu verwalten:

• Wenn Sie die virtuelle IP-Adresse migrieren und beibehalten, wird die vorab erstellte IP-Adresse vorübergehend der neuen stv2-Bereitstellung zugewiesen, bevor die ursprüngliche IP-Adresse der stv2-Bereitstellung zugewiesen wird. Wenn Sie Firewallregeln haben, die den Zugriff auf die API Management-Instanz einschränken, können Sie beispielsweise die vorab erstellte IP-Adresse zur Positivliste hinzufügen, um die Kontinuität des Clientzugriffs während der Migration zu gewährleisten. Nach Abschluss der Migration können Sie die vorab erstellte IP-Adresse von Ihrer Positivliste entfernen.
• Wenn Sie migrieren und eine neue virtuelle IP-Adresse generieren, wird die vorab erstellte IP-Adresse während der Migration der neuen stv2-Bereitstellung zugewiesen und nach Abschluss der Migration beibehalten. Verwenden Sie die vorab erstellte IP-Adresse, um Ihre Netzwerkabhängigkeiten wie DNS- und Firewallregeln zu aktualisieren, um auf die neue IP-Adresse zu verweisen.

Schritte bei der Migration

APIM_NAME={name of your API Management instance}
# In PowerShell, use the following syntax: $APIM_NAME={name of your API Management instance}
RG_NAME={name of your resource group}
# Get resource ID of API Management instance
APIM_RESOURCE_ID=$(az apim show --name $APIM_NAME --resource-group $RG_NAME --query id --output tsv)
# Call REST API to migrate to stv2 and preserve VIP address
az rest --method post --uri "$APIM_RESOURCE_ID/migrateToStv2?api-version=2023-03-01-preview" --body '{"mode": "PreserveIp"}'
# Alternate call to migrate to stv2 and change VIP address
# az rest --method post --uri "$APIM_RESOURCE_ID/migrateToStv2?api-version=2023-03-01-preview" --body '{"mode": "NewIp"}'

Überprüfen der Migration

Überprüfen Sie die Plattformversion Ihrer API Management-Instanz, wenn sich der Status in Online ändert, um sich zu vergewissern, dass die Migration erfolgreich war. Nach erfolgreicher Migration lautet der Wert stv2 oder stv2.1.

Automatisches Zurücksetzen, wenn die Migration fehlschlägt

Wenn während des Migrationsprozesses ein Fehler auftritt, wird die Instanz automatisch auf die stv1-Plattform zurückgesetzt. Nach erfolgreichem Abschluss der Migration (für die Plattformversion der Instanz wird stv2 oder stv2.1 und für den Status wird Online angezeigt) ist kein Rollback zur stv1-Plattform mehr möglich.

Im Falle einer nicht erfolgreichen Migration erhalten Sie Hilfe vom Azure-Support.

Wenn Sie die Möglichkeit benötigen, ein manuelles Rollback auszuführen, empfiehlt es sich, eine neue stv2-Instanz parallel zu Ihrer ursprünglichen API Management-Instanz bereitzustellen.

Aktualisieren von Netzwerkabhängigkeiten

Nach erfolgreicher Migration zu einer neuen VIP-Adresse müssen Sie alle Netzwerkabhängigkeiten einschließlich DNS, Firewallregeln und VNets aktualisieren, um die neue VIP-Adresse zu verwenden.

Hilfe und Support

Wir helfen Ihnen bei der Migration zur stv2-Plattform mit minimalen Unterbrechungen für Ihre Dienste.

Bei Fragen können Sie schnelle Antworten von Communityexperten auf Microsoft Q&A erhalten. Wenn Sie über einen Supportplan verfügen und technische Hilfe benötigen, erstellen Sie eine Supportanfrage.

1. Geben Sie als Zusammenfassung eine Beschreibung Ihres Problems ein, z. B. „stv1 Einstellung“.
2. Wählen Sie unter Problemtyp die Option Technisch aus.
3. Wählen Sie unter Abonnement Ihr Abonnement aus.
4. Wählen Sie unter Dienst die Option Meine Dienste und dann API Management-Dienst aus.
5. Wählen Sie unter Ressource die Azure-Ressource aus, für die Sie eine Supportanfrage erstellen.
6. Wählen Sie als Problemtyp die Option Administration und Verwaltung aus.
7. Wählen Sie als Problemuntertyp die Option Upgrade, Skalierung oder SKU-Änderungen aus.

Häufig gestellte Fragen

• Welche Informationen benötigen wir für die Auswahl eines Migrationspfads?

  • Wie lautet der Netzwerkmodus der API Management-Instanz?
  • Sind benutzerdefinierte Domänen konfiguriert?
  • Ist eine Firewall beteiligt?
  • Gibt es bekannte Upstream- oder Downstreamabhängigkeiten für die beteiligten IP-Adressen?
  • Handelt es sich um eine Bereitstellung in mehreren Regionen?
  • Können wir die vorhandene Instanz ändern, oder ist ein paralleles Setup erforderlich?
  • Darf es Downtime geben?
  • Kann die Migration außerhalb der Geschäftszeiten durchgeführt werden?

• Wie lauten die Voraussetzungen für die Migration?

  Bei nicht in ein VNet eingefügten Instanzen müssen keine Voraussetzungen erfüllt werden. Wenn Sie unter Beibehaltung Ihrer öffentlichen IP-Adresse migrieren, reagiert die API Management-Instanz ungefähr 15 Minuten lang nicht mehr. Bei Verwendung der Option Neue virtuelle IP-Adresse, die API Management über eine neue IP-Adresse verfügbar macht, kommt es unter Umständen zu keiner Downtime. Bei Instanzen, die über einen A-Eintrag mit einer benutzerdefinierten Domäne konfiguriert werden und/oder bei denen Netzwerkabhängigkeiten von der öffentlichen virtuellen IP-Adresse bestehen, kommt es zu Downtime, wenn eine neue virtuelle IP-Adresse angefordert wird.

• Verursacht die Migration Downtime?

  Bei nicht in ein VNet eingefügten Instanzen kommt es nur zu einer Downtime von ca. 15 Minuten, wenn die ursprüngliche IP-Adresse beibehalten werden soll. Wenn Sie mit einer neuen IP-Adresse migrieren und keine Netzwerkabhängigkeiten von der neuen IP-Adresse bestehen, gibt es jedoch keine Downtime. Netzwerkabhängigkeiten umfassen benutzerdefinierte Domänennamen ohne CNAME, Listen zugelassener IP-Adressen, Firewallregeln und VNets.

• Kann es durch die bzw. während der Migration zu Daten- oder Konfigurationsverlusten kommen?

  Bei der Migration von stv1 zu stv2 wird nur die Computeplattform aktualisiert. Die interne Speicherebene wird nicht geändert. Daher ist die gesamte Konfiguration während des Migrationsprozesses sicher. Somit bleibt auch die systemseitig zugewiesene verwaltete Identität erhalten (sofern aktiviert).

• Wie kann ich bestätigen, dass die Migration abgeschlossen ist und erfolgreich war?

  Die Migration gilt als abgeschlossen und erfolgreich, wenn der Status auf der Übersichtsseite Online und die Plattformversion entweder stv2 oder stv2.1 lautet. Überprüfen Sie außerdem, ob der Netzwerkstatus auf dem Blatt „Netzwerk“ für alle erforderlichen Verbindungen grün angezeigt wird.

• Kann ich die Migration über das Portal durchführen?

  Ja. Das Blatt Plattformmigration im Azure-Portal führt durch die Migration für nicht in ein VNet eingefügte Instanzen.

• Kann ich die IP-Adresse der Instanz beibehalten?

  Ja. Die IP-Adresse kann beibehalten werden, dies führt aber zu einer Downtime von ca. 15 Minuten.

• Gibt es einen Migrationspfad, ohne dass die vorhandene Instanz geändert werden muss?

  Ja. Hierzu ist eine parallele Migration erforderlich. Das bedeutet, dass Sie parallel zu Ihrer aktuellen Instanz eine neue API Management-Instanz erstellen und die Konfiguration in die neue Instanz kopieren.

• Was passiert, wenn die Migration nicht erfolgreich abgeschlossen werden kann?

  Wenn für Ihre API Management-Instanz nicht die Plattformversion stv2 oder stv2.1 und nicht der Status Online anzeigt werden, nachdem Sie die Migration initiiert haben, war sie wahrscheinlich nicht erfolgreich. Ihr Dienst wird automatisch auf die alte Instanz zurückgesetzt, und es werden keine Änderungen vorgenommen. Wenden Sie sich im Falle von Problemen an den Azure-Support (also beispielsweise, wenn der Status länger als zwei Stunden Wird aktualisiert lautet).

• Welche Funktionalität ist während der Migration nicht verfügbar?

  Für nicht in ein VNet eingefügte Instanzen gilt Folgendes:

  • Wenn Sie sich für die Beibehaltung der ursprünglichen IP-Adresse entschieden haben, reagieren API-Anforderungen ungefähr 15 Minuten lang nicht, während die IP-Adresse zur neuen Infrastruktur migriert wird. Die Infrastrukturkonfiguration (z. B. benutzerdefinierte Domänen, Standorte und Zertifizierungsstellenzertifikate) wird 45 Minuten lang gesperrt.
  • Wenn Sie sich für die Migration zu einer neuen IP-Adresse entschieden haben reagieren API-Anforderungen während der Migration weiterhin. Die Infrastrukturkonfiguration (z. B. benutzerdefinierte Domänen, Standorte und Zertifizierungsstellenzertifikate) wird 30 Minuten lang gesperrt. Nach der Migration müssen Sie alle Netzwerkabhängigkeiten einschließlich DNS, Firewallregeln und VNets aktualisieren, um die neue VIP-Adresse zu verwenden.

• Wie lange dauert die Migration?

  Die erwartete Dauer für die gesamte Migration beträgt ca. 45 Minuten. Überprüfen Sie, ob der Status Ihrer Instanz wieder Online und nicht mehr Wird aktualisiert lautet, um zu ermitteln, ob die Migration bereits ausgeführt wurde. Wenn der Status länger als zwei Stunden Wird aktualisiert lautet, wenden Sie sich an den Azure-Support.

• Kann ich bei Bedarf ein Rollback für die Migration ausführen?

  Wenn während des Migrationsprozesses ein Fehler auftritt, wird automatisch ein Rollback der Instanz auf die stv1-Plattform ausgeführt. Nach erfolgreicher Migration des Diensts können Sie jedoch kein Rollback mehr auf die stv1-Plattform ausführen.

• Sind Änderungen an benutzerdefinierten Domänen bzw. an privaten DNS-Zonen erforderlich?

  Bei nicht in ein VNet eingefügten Instanzen sind keine Änderungen erforderlich, wenn die IP-Adresse beibehalten wird. Wenn sie sich für eine neue IP-Adresse entschieden haben, müssen benutzerdefinierte Domänen, die auf die IP-Adresse verweisen, aktualisiert werden.

• Meine stv1-Instanz wird in mehreren Azure-Regionen bereitgestellt. Wie führe ich ein Upgrade auf stv2 aus?

  Führen Sie für eine API Management-Instanz, die nicht in ein VNet eingefügt wird, die Migrationsschritte über das Portal oder mithilfe der Azure CLI aus. Alle Regionen werden zu stv2 migriert.

• Was sollten wir bei selbstgehosteten Gateways berücksichtigen?

  Sie müssen für Ihre selbstgehosteten Gateways keine Schritte unternehmen. Sie müssen nur in Azure ausgeführte API Management-Instanzen migrieren, die von der Einstellung der stv1-Plattform betroffen sind. Beachten Sie, dass es u. U. eine neue IP-Adresse für den Konfigurationsendpunkt der API Management-Instanz gibt. Daher müssen alle an die IP-Adresse angehefteten Netzwerkeinschränkungen aktualisiert werden.

• Wie wirkt sich die Migration auf das Entwicklerportal aus?

  Es gibt keine Auswirkungen auf das Entwicklerportal. Wenn benutzerdefinierte Domänen verwendet werden, sollte der DNS-Eintrag nach der Migration mit der effektiven IP-Adresse aktualisiert werden. Wenn jedoch die Standarddomänen verwendet werden, werden sie bei erfolgreicher Migration automatisch aktualisiert. Während der Migration gibt es keine Downtime für das Entwicklerportal.

• Gibt es nach der Migration zu stv2 Auswirkungen auf die Kosten?

  Das Abrechnungsmodell bleibt für stv2 gleich, und während sowie nach der Migration entstehen keine weiteren Kosten.

• Welche RBAC-Berechtigungen sind für die Migration von stv1 zu stv2 erforderlich?

  Der Benutzer/Prozess, der die Migration durchführt, benötigt Schreibzugriff auf die API Management-Instanz.

Zugehöriger Inhalt

• Gewusst wie: Welche Plattform hostet meine API Management-Instanz?

• Computeplattform für Azure API Management – klassische Ebenen

• Einstellung der stv1-Plattform – Globales Azure (August 2024)

• Einstellung der stv1-Platform – Azure Government und Azure, betrieben von 21Vianet (Februar 2025)