Sitzungsmigration: Einrichtung und Konfiguration

Dieser Leitfaden enthält detaillierte Einrichtungsanweisungen und Codebeispiele für die Sitzungsmigration auf allen unterstützten Plattformen. Einen Überblick über die Serverrotation und ihre Auswirkungen auf Sitzungen finden Sie unter Server-Rotation und Sitzungsmigration.

Übersicht

Die Medienserver der Vonage Video API werden im Rahmen der normalen Cloud-Wartung, der automatischen Skalierung und der Infrastruktur-Updates regelmäßig ausgetauscht. Sitzungen, die länger als 8 Stunden laufen, sind besonders wahrscheinlich betroffen.

Session Migration ist erhältlich bei SDK Version 2.30.0 und erreicht Allgemeine Verfügbarkeit (GA) in SDK 2.31.0 (August 2025).

Wie es funktioniert

1. Das Vonage-Backend erkennt, dass ein Medienserver, der eine Sitzung hostet, für eine Rotation vorgesehen ist.
2. A sessionNotification Ereignis wird an Ihren Server-Callback-Endpunkt gesendet - an 4 Stunden und wieder bei 1 Stunde vor der Rotation.
3. Wenn die Sitzungsmigration aktiviert ist, migriert die Plattform automatisch alle in Frage kommenden Verbindungen auf einen neuen Medienserver.
4. Die Clients stellen die Verbindung transparent und mit minimaler Ausfallzeit wieder her. Die Wiederverbindung ist in der Regel innerhalb weniger Sekunden abgeschlossen.

Was wird automatisch migriert und was erfordert manuelle Eingriffe?

Bei einer Sitzungsmigration werden nicht alle Dienste automatisch behandelt. Anhand der nachstehenden Tabelle können Sie erkennen, was Ihre Anwendung verarbeiten muss.

Aktivieren der automatischen Sitzungsmigration

Client SDK (Web / Native)

Aktivieren Sie die Sitzungsmigration durch Übergabe von sessionMigration: true beim Initialisieren einer Sitzung:

Web (JavaScript)

const session = OT.initSession(apiKey, sessionId, {
  sessionMigration: true
});

iOS (Swift)

let settings = OTSessionSettings()
settings.sessionMigration = true
let session = OTSession(apiKey: apiKey, sessionId: sessionId, delegate: self, settings: settings)

Android (Kotlin)

val settings = Session.SessionProperties.Builder()
    .sessionMigration(true)
    .build()
val session = Session(context, apiKey, sessionId, settings)

React Native

// Pass sessionMigration in the OTSession options prop
<OTSession
  apiKey={apiKey}
  sessionId={sessionId}
  token={token}
  options={{ sessionMigration: true }}
>

SIP (Wähl-API)

Um die Sitzungsmigration für SIP-Verbindungen zu aktivieren, fügen Sie sessionMigration: true in Ihrem Dial-API-Anfragetext:

{
  "sessionId": "<session-id>",
  "token": "A valid token with the role set to moderator",
  "sip": {
    "uri": "sip:user@sip.partner.com;transport=tls",
    "from": "from@example.com",
    "sessionMigration": true
  }
}

Audio-Anschluss (Connect API)

Um die Sitzungsmigration für Audio Connector WebSocket-Verbindungen zu aktivieren, fügen Sie sessionMigration: true in Ihrem Connect-API-Anforderungstext:

{
  "sessionId": "<session-id>",
  "token": "A valid token with the role set to moderator",
  "websocket": {
    "uri": "wss://your-websocket-server.example.com",
    "sessionMigration": true
  }
}

Video Connector (Python SDK)

Um die Sitzungsmigration für den Video Connector zu aktivieren, setzen Sie enable_migration=True in Ihren Sitzungseinstellungen:

from vonage_video_connector import VonageVideoClient
from vonage_video_connector.models import SessionSettings

session_settings = SessionSettings(enable_migration=True)
client = VonageVideoClient()
client.connect(
    application_id="<application-id>",
    session_id="<session-id>",
    token="<token>",
    session_settings=session_settings
)

Manuelles Auslösen der Sitzungsmigration

Neben der automatischen Migration während der Serverrotation können Sie eine Sitzungsmigration auch manuell über die REST-API auslösen. Dies ist nützlich für:

• Proaktive Migration einer Sitzung vor einer geplanten Rotation (z. B. bei der 7,5-Stunden-Marke)
• Testen und Simulieren des Serverrotationsverhaltens in Ihrer Anwendung
• den Kunden die Kontrolle darüber zu geben, wann die Migration stattfindet (z. B. während einer Pause in einer langen Sitzung)

Session-API migrieren

Methode: POST

URI:

/v2/project/<projectId>/session/<sessionId>/migrate

Überschriften:

Beispielanfrage:

Antwort-Codes

Handhabung von sessionNotification-Ereignissen

Die Vonage-Plattform sendet sessionNotification Callback-Ereignisse an Ihren Server vor einer geplanten Rotation. Sie können diese verwenden, um Benutzer proaktiv zu benachrichtigen oder eine manuelle Migration zu einem geeigneten Zeitpunkt auszulösen.

Beispiel für die Nutzlast eines Rückrufs:

{
  "sessionId": "<session-id>",
  "projectId": "<project-id>",
  "event": "sessionNotification",
  "reason": "serverRotation",
  "remainingTime": 3600
}

Um diese Ereignisse zu empfangen, konfigurieren Sie eine Sitzungsüberwachungs-Callback-URL in Ihrer Vonage API Dashboard.

Anmerkungen

• Die Sitzungsmigration gilt nur für Medienserver-Rotation. Sie deckt nicht die Rotation von SIP-Servern oder TURN-Servern ab, die von der Plattform separat behandelt werden.
• sessionMigration wird standardmäßig auf false und muss bei jeder Client-Verbindung, die automatisch wieder verbunden werden soll, explizit aktiviert werden. Verbindungen ohne dieses Flag werden während der Migration geschlossen.
• Die minimal erforderliche SDK-Version ist 2.30.0. Stellen Sie sicher, dass alle Clients über SDK 2.30.0 oder höher verfügen.
• Bei SIP- und Audio-Connector-Verbindungen bleibt der externe Rufzweig (SIP oder WebSocket) während der Migration verbunden. Die Medienverbindungen werden auf dem neuen Server wiederhergestellt. Während des Wechsels kann am Endpunkt eine kurze Stille auftreten.
• Archivierung, Broadcasting, Experience Composer und Live Captions müssen nach der Migration manuell neu gestartet werden. Für Experience Composer muss der Neustart auf der dieselbe Sitzungs-ID - die migrierte Sitzung behält dieselbe Sitzungs-ID auf dem neuen Server.
• Nach der Migration bietet der neue Server eine 10-Minuten-Frist damit die Clients die Verbindung wiederherstellen und die Dienste wieder aufgenommen werden können. Während dieses Zeitfensters wird jeder Versuch, eine neue Verbindung herzustellen, oder jede API-Anforderung (z. B. das Starten eines Archivs) automatisch an den neuen Server weitergeleitet.
• Die Migrate Session API verhindert mehrere gleichzeitige Migrationen. Wenn bereits eine Migration im Gange ist, gibt die API ein 409 Fehler mit Code 15214. Wenn der Aufruf zu früh nach der Erstellung der Sitzung oder einer früheren Migration erfolgt, wird 409 mit Code 15215.
• Bei Sitzungen, die sich 8 Stunden nähern, sollten Sie die Migration proaktiv bei der 7,5-Stunden-Marke mithilfe der Migrate Session API auslösen, um Unterbrechungen während der Spitzenauslastung zu vermeiden.
• Monitor sessionNotification Ereignisse - Nutzen Sie die 4-Stunden- und 1-Stunden-Warnungen, um die Nutzer proaktiv zu informieren oder eine manuelle Migration zu einem Zeitpunkt mit geringem Datenverkehr zu planen.